Backup-Archive Clients Installation and User`s Guide

IBM Spectrum Protect for Windows
Backup-Archive Clients
Version 8.1.2
Installation and User's Guide
IBM
IBM Spectrum Protect for Windows
Backup-Archive Clients
Version 8.1.2
Installation and User's Guide
IBM
Note:
Before you use this information and the product it supports, read the information in “Notices” on page 805.
This edition applies to version 8, release 1, modification 2 of IBM Spectrum Protect (product numbers 5725-W98,
5725-W99, and 5725-X15) and to all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright IBM Corporation 1993, 2017.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Tables . . . . . . . . . . . . . . . xi
About this publication . . . . . . . . xiii
Who should read this publication. .
Publications . . . . . . . . .
Conventions used in this publication
Reading syntax diagrams . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xiii
xiii
xiv
xiv
What's new for Version 8.1.2 . . . . . xvii
Chapter 1. Installing the IBM Spectrum
Protect backup-archive clients . . . . . 1
Upgrading the backup-archive client . . . . . . 1
Upgrade path for clients and servers . . . . . 1
Additional upgrade information . . . . . . . 1
Automatic backup-archive client deployment . . 1
Client environment requirements . . . . . . . 3
Windows client environment requirements . . . 3
Windows client installable components . . . 3
System requirements for Windows clients. . . 3
Windows client communication methods . . . 3
Backup-archive client features that are available
on Windows platforms . . . . . . . . . 4
Windows supported file systems. . . . . . 4
NDMP support requirements (Extended Edition only) 4
Installation requirements for backing up and
archiving Tivoli Storage Manager FastBack client data 5
Client configuration wizard for Tivoli Storage
Manager FastBack . . . . . . . . . . . . 6
Windows backup-archive client installation overview 6
Windows client installation might require a reboot 6
Installation procedures . . . . . . . . . . 7
Installing the Windows client for the first time 7
Upgrading the Windows client . . . . . . 11
Reinstalling the Windows client . . . . . 13
Silent installation . . . . . . . . . . 14
Modifying, repairing, or uninstalling the
Windows client . . . . . . . . . . . 17
Troubleshooting problems during installation . . 19
Software updates . . . . . . . . . . . 20
Installing the client management service to collect
diagnostic information. . . . . . . . . . . 20
Chapter 2. Configure the IBM Spectrum
Protect client . . . . . . . . . . . . 21
Client options file overview . . . . . . . . .
Creating and modifying the client options file . .
Create a shared directory options file . . . . .
Creating multiple client options files . . . . .
Environment variables. . . . . . . . . . .
Configuring the language for displaying the Java
GUI . . . . . . . . . . . . . . . . .
Web client configuration overview. . . . . . .
Configuring the web client on Windows systems
© Copyright IBM Corp. 1993, 2017
21
23
25
25
26
27
27
28
|
|
|
|
|
|
|
Configuring the scheduler . . . . . . . . .
Comparison between client acceptor-managed
services and traditional scheduler services . . .
Configuring the client to use the client acceptor
service to manage the scheduler . . . . . .
Starting the client scheduler . . . . . . . . .
Scheduling events using the GUI . . . . . .
Configuring IBM Spectrum Protect client/server
communication across a firewall . . . . . . .
Configuring IBM Spectrum Protect client/server
communication with Secure Sockets Layer . . . .
Creating a symbolic link to access the latest
GSKit library . . . . . . . . . . . . .
Certificate Authorities root certificates . . . .
Configure your system for journal-based backup . .
Configuring the journal engine service . . . .
JournalSettings stanza (Windows) . . . . .
JournalExcludeList stanza . . . . . . .
JournaledFileSystemSettings stanza . . . .
Overriding stanzas . . . . . . . . . .
Client-side data deduplication . . . . . . . .
Configuring the client for data deduplication . .
Excluding files from data deduplication . . . .
Automated client failover configuration and use . .
Automated client failover overview . . . . .
Requirements for automated client failover . .
Restrictions for automated client failover . .
Failover capabilities of IBM Spectrum Protect
components . . . . . . . . . . . .
Configuring the client for automated failover . .
Determining the status of replicated client data
Preventing automated client failover . . . . .
Forcing the client to fail over . . . . . . .
Configuring the client to back up and archive Tivoli
Storage Manager FastBack data . . . . . . . .
Configuring the backup-archive client to protect
FastBack client data . . . . . . . . . . .
Configuring the backup-archive client in a cluster
server environment . . . . . . . . . . . .
Protecting data in MSCS clusters (Windows
Server clients) . . . . . . . . . . . .
Configuring cluster protection (Windows
Server clients) . . . . . . . . . . .
Configure the web client in a cluster environment
Configure the web client to process cluster
disk resources . . . . . . . . . . .
Frequently asked questions . . . . . . . .
Configuring online-image backup support . . . .
Configuring Open File Support . . . . . . . .
Configuring NetApp and IBM Spectrum Protect for
snapshot difference incremental backups . . . .
Protecting clustered-data ONTAP NetApp file
server volumes . . . . . . . . . . . .
SnapMirror support for NetApp
snapshot-assisted progressive incremental backup
(snapdiff) . . . . . . . . . . . . . .
30
30
31
32
33
33
36
39
40
41
41
43
44
45
48
48
52
54
56
56
57
58
59
59
61
62
62
63
64
66
66
67
68
68
75
78
78
79
81
84
iii
Register your workstation with a server . . . . . 87
Closed registration . . . . . . . . . . . 87
Open registration . . . . . . . . . . . 88
Creating an include-exclude list . . . . . . . 88
Include-exclude options . . . . . . . . . 89
Exclude file spaces and directories. . . . . 89
Include-exclude statements for networked file
systems. . . . . . . . . . . . . . 91
Exclude files and directories from a
journal-based backup . . . . . . . . . 91
Control processing with exclude statements . 91
System files to exclude . . . . . . . . 92
Exclude files with UNC names . . . . . . 93
Include and exclude files that contain
wildcard characters . . . . . . . . . . 93
Include and exclude groups of files with
wildcard characters . . . . . . . . . . 94
Examples using wildcards with include and
exclude patterns . . . . . . . . . . . 95
Determine compression and encryption
processing . . . . . . . . . . . . . . 96
Preview include-exclude list files . . . . . . 97
Include and exclude option processing . . . . 98
Processing rules when using UNC names . . . 99
Explicit use of UNC names for remote drives 100
Conversion of DOS pathnames for fixed and
remote drives . . . . . . . . . . . 100
Character-class matching examples . . . . 100
Chapter 3. Getting started . . . . . . 101
|
|
|
|
|
|
|
|
|
|
|
|
Configuring the client security settings to connect
to the IBM Spectrum Protect server version 8.1.2
and later . . . . . . . . . . . . . . .
Default security settings for the client (fast path)
Configuring the client without automatic
certificate distribution . . . . . . . . .
Secure password storage . . . . . . . . .
Backup-archive client operations and security
rights . . . . . . . . . . . . . . . .
Backup Operators group operations . . . . .
Considerations before you start using a Backup
Operators group account . . . . . . . .
Permissions required to restore files that use
adaptive subfile backup . . . . . . . . . .
Permissions required to back up, archive, restore or
retrieve files on cluster resources . . . . . . .
IBM Spectrum Protect client authentication . . .
User account control . . . . . . . . . . .
Enabling client access to network shares when
UAC is enabled. . . . . . . . . . . .
Starting a Java GUI session . . . . . . . . .
IBM Spectrum Protect password . . . . . .
Setup wizard . . . . . . . . . . . .
Starting a command-line session . . . . . . .
Using batch mode . . . . . . . . . . .
Issuing a series of commands by using
interactive mode . . . . . . . . . . .
Displaying Euro characters in a command-line
prompt . . . . . . . . . . . . . .
Use options on the DSMC command . . . .
iv
101
101
103
106
107
109
110
110
110
111
112
112
113
113
113
114
114
114
115
116
|
|
|
|
Specifying input strings that contain blank spaces
or quotation marks . . . . . . . . . .
Using the web client in the new security
environment . . . . . . . . . . . . .
Starting a web client session . . . . . .
User privileges . . . . . . . . . .
Start the client scheduler automatically . . . .
Changing your password . . . . . . . .
Sorting file lists using the backup-archive client
GUI . . . . . . . . . . . . . . .
Displaying online help . . . . . . . . .
Ending a session . . . . . . . . . . .
Online forums . . . . . . . . . . . .
. 116
.
.
.
.
.
117
117
118
119
119
.
.
.
.
120
122
122
122
Chapter 4. Backing up your data . . . 125
Planning your backups (Windows) . . . . . .
Which files are backed up . . . . . . . . .
Open file support for backup operations . . . .
Backing up data using the GUI . . . . . . .
Specifying drives in your domain . . . . .
Backing up data using the command line . . . .
Deleting backup data . . . . . . . . . . .
When to back up and when to archive files . . .
Pre-backup considerations (Windows) . . . . .
LAN-free data movement . . . . . . . .
LAN-free prerequisites . . . . . . . .
LAN-free data movement options . . . .
Unicode file spaces (Windows) . . . . . .
Incremental backups on memory-constrained
systems . . . . . . . . . . . . . .
Incremental backups on systems with a large
number of files . . . . . . . . . . . .
Control processing with an include-exclude list
Data encryption during backup or archive
operations . . . . . . . . . . . . .
Maximum file size for operations. . . . . .
How the client handles long user and group
names . . . . . . . . . . . . . . .
Incremental, selective, or incremental-by-date
backups (Windows) . . . . . . . . . . .
Full and partial incremental backup . . . . .
Journal-based backup. . . . . . . . .
Incremental-by-date backup . . . . . . .
Comparing incremental-by-date, journal-based,
and NetApp snapshot difference to full
incremental and partial incremental backups . .
Snapshot differential backup with an HTTPS
connection . . . . . . . . . . . . .
Running a snapshot differential backup with
an HTTPS connection . . . . . . . .
Selective backup . . . . . . . . . . .
Backing up files from one or more file spaces for a
group backup (Windows) . . . . . . . . .
Backing up data with client-node proxy support
(Windows) . . . . . . . . . . . . . .
Enabling multiple node operations from the
GUI . . . . . . . . . . . . . . .
Setting up encryption . . . . . . . . .
Scheduling backups with client-node proxy
support . . . . . . . . . . . . . .
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
125
126
127
129
130
130
132
133
134
134
134
135
135
135
136
137
137
138
139
139
139
141
143
144
145
146
147
147
148
149
150
150
Associate a local snapshot with a server file space
(Windows) . . . . . . . . . . . . . .
Backing up Windows system state . . . . . .
Backing up Automated System Recovery files . .
Preparation for Automated System Recovery . . .
Creating a client options file for Automated
System Recovery . . . . . . . . . . .
Backing up the boot drive and system drive for
Automated System Recovery . . . . . . .
Image backup . . . . . . . . . . . . .
Performing prerequisite tasks before creating an
image backup . . . . . . . . . . . .
Utilizing image backups to perform file system
incremental backups . . . . . . . . . .
Method 1: Using image backups with file
system incremental backups . . . . . .
Method 2: Using image backups with
incremental-by-date image backups . . . .
Comparing methods 1 and 2 . . . . . .
Performing an image backup using the GUI . .
Performing an image backup using the
command line . . . . . . . . . . . .
Back up NAS file systems using Network Data
Management Protocol . . . . . . . . . .
Backing up NAS file systems with the web
client GUI using NDMP protocol . . . . . .
Back up NAS file systems using the command
line . . . . . . . . . . . . . . . .
Methods for backing up and recovering data on
NAS file servers accessed by CIFS protocol . .
Support for CDP Persistent Storage Manager . . .
Backing up VMware virtual machines . . . . .
Preparing the environment for full backups of
VMware virtual machines . . . . . . . .
Creating full backups for VMware virtual
machines . . . . . . . . . . . . . .
Parallel backups of virtual machines. . . . .
Back up virtual machines on a Hyper-V system
Hyper-V backup support limitations. . . . .
Back up and archive Tivoli Storage Manager
FastBack data . . . . . . . . . . . . .
Backing up Net Appliance CIFS share definitions
Display backup processing status. . . . . . .
Backup (Windows): Additional considerations . .
Open files . . . . . . . . . . . . .
Ambiguous file space names in file
specifications . . . . . . . . . . . .
Management classes . . . . . . . . . .
Deleted file systems . . . . . . . . . .
Removable media backup . . . . . . . .
Fixed drives . . . . . . . . . . . . .
NTFS and ReFS file spaces . . . . . . . .
Universal Naming Convention names . . . .
Examples: UNC names in domain lists . . .
Examples: UNC name backup . . . . . .
Microsoft Dfs file protection methods . . . .
151
152
153
154
154
155
156
157
158
158
159
160
160
161
162
163
164
166
167
168
169
171
173
173
173
174
174
174
177
177
178
178
179
179
180
180
180
180
181
182
Chapter 5. Restoring your data . . . . 185
Duplicate file names . . . . . . . . .
Universal Naming Convention names restore.
Active or inactive backup restore . . . . .
.
.
.
. 185
. 186
. 186
Restoring files and directories . . . . . . . .
Restoring data by using the GUI . . . . . .
Examples for restoring data using the command
line . . . . . . . . . . . . . . . .
Examples: Restoring large amounts of data
Standard query restore, no-query restore, and
restartable restore . . . . . . . . . .
Restoring Windows system state . . . . . . .
Restoring Automated System Recovery files . . .
Restoring the operating system when the computer
is working . . . . . . . . . . . . . .
Recovering a computer when the Windows OS is
not working . . . . . . . . . . . . . .
Creating a bootable WinPE CD . . . . . .
Restoring the Windows operating system with
Automated System Recovery . . . . . . .
Microsoft Dfs tree and file restore . . . . . .
Restoring an image . . . . . . . . . . .
Restoring an image using the GUI . . . . .
Restoring an image using the command line . .
Restore data from a backup set . . . . . . .
Restore backup sets: considerations and
restrictions . . . . . . . . . . . . .
Backup set restore . . . . . . . . . . .
Restoring backup sets using the GUI . . . .
Backup set restores using the client
command-line interface . . . . . . . . .
Restore Net Appliance CIFS shares . . . . . .
Restoring data from a VMware backup . . . . .
Restoring full VM backups . . . . . . . .
Shadow copy considerations for restoring an
application protection backup from the data
mover . . . . . . . . . . . . . .
Scenarios for running full VM instant access and
full VM instant restore from the backup-archive
client command line . . . . . . . . . .
Full VM instant restore cleanup and repair
scenarios . . . . . . . . . . . . .
Recovering from non-standard error
conditions . . . . . . . . . . . .
Scenario: Restoring file-level VM backups . . .
Restoring full VM backups that were created
with VMware Consolidated Backup . . . . .
Restore Windows individual Active Directory
objects. . . . . . . . . . . . . . . .
Reanimate tombstone objects or restoring from a
system state backup . . . . . . . . . .
Restoring Active Directory objects using the
GUI and command line . . . . . . . . .
Restrictions and limitations when restoring
Active Directory objects . . . . . . . . .
Preserve attributes in tombstone objects . . .
Modifying the client acceptor and agent services
to use the web client . . . . . . . . . .
Restoring or retrieving data during a failover. . .
Authorizing another user to restore or retrieve
your files . . . . . . . . . . . . . . .
Restoring or retrieving files from another client
node . . . . . . . . . . . . . . . .
Restoring or retrieving your files to another
workstation . . . . . . . . . . . . . .
187
187
Contents
v
187
189
190
191
192
192
193
193
193
193
194
195
196
196
198
199
200
201
202
202
203
205
207
210
212
213
216
217
218
219
219
221
221
222
223
224
225
Deleting file spaces . . . . . . . . . . .
Restoring data to a point in time . . . . . . .
Restore NAS file systems . . . . . . . . .
Restoring NAS file systems using the web client
Restoring NAS files and directories using the
web client . . . . . . . . . . . . .
Options and commands to restore NAS file
systems from the command line . . . . . .
226
227
228
229
Copy group name attribute. . . . .
Copy type attribute . . . . . . .
Copy frequency attribute . . . . .
Versions data exists attribute . . . .
Versions data deleted attribute . . .
Retain extra versions attribute . . . .
Retain only version attribute . . . .
Copy serialization attribute . . . . .
Copy mode parameter . . . . . .
Copy destination attribute . . . . .
Retain versions attribute. . . . . .
Deduplicate data attribute . . . . .
Select a management class for files . . .
Assign a management class to files . . .
Override the management class for archived
Select a management class for directories .
Bind management classes to files . . . .
Rebind backup versions of files . . . .
Retention grace period . . . . . . .
Event-based policy retention protection. .
Archive files on a data retention server .
230
231
Chapter 6. Archive and retrieve your
data (Windows) . . . . . . . . . . 233
Archive files. . . . . . . . . . . . .
Snapshot backup or archive with open file
support . . . . . . . . . . . . .
Archiving data with the GUI . . . . . .
Archive data examples by using the command
line . . . . . . . . . . . . . . .
Associate a local snapshot with a server file
space (Windows) . . . . . . . . .
Archiving data with client node proxy . . .
Deleting archive data . . . . . . . . .
Retrieve archives . . . . . . . . . . .
Retrieving archives with the GUI . . . . .
Retrieve archive copies by using the command
line . . . . . . . . . . . . . . .
. 233
. 234
. 234
. 235
.
.
.
.
.
236
236
238
238
239
Chapter 7. IBM Spectrum Protect
scheduler overview . . . . . . . . . 241
242
242
243
244
245
248
250
251
254
254
255
Chapter 9. Storage management
policies . . . . . . . . . . . . . . 261
vi
. 261
. 262
. 263
.
.
.
.
.
.
263
263
264
264
264
264
265
265
266
266
266
266
267
267
268
268
269
270
270
271
271
Install the backup-archive scheduler service . .
Using the Client Service Configuration Utility
(Windows) . . . . . . . . . . . .
Examples: Automating backups . . . .
Examples: Configuring the client acceptor to
manage an existing scheduler service . .
Creating a new scheduler and associating a
client acceptor to manage the scheduler .
dsmcutil command . . . . . . . . . .
Dsmcutil commands: Required options and
examples . . . . . . . . . . . . .
Dsmcutil valid options . . . . . . . .
. 273
. 273
. 274
. 276
. 276
. 277
. 278
. 287
Chapter 11. Processing options . . . 291
246
Chapter 8. Client return codes . . . . 259
Policy domains and policy sets . . . . . .
Management classes and copy groups . . . .
Display information about management classes
and copy groups . . . . . . . . . . .
|
246
255
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 10. IBM Spectrum Protect
Client Service Configuration Utility . . 273
. 239
Examples: Blank spaces in file names in schedule
definitions . . . . . . . . . . . . . .
Preferential start times for certain nodes . . . .
Scheduler processing options . . . . . . . .
Evaluate schedule return codes in schedule
scripts . . . . . . . . . . . . . . .
Return codes from preschedulecmd and
postschedulecmd scripts . . . . . . . . .
Client-acceptor scheduler services versus the
traditional scheduler services . . . . . . . .
Setting the client scheduler process to run as a
background task and start automatically at startup .
Examples: Display information about scheduled
work . . . . . . . . . . . . . . . .
Display information about completed work . . .
Examples: event logs . . . . . . . . . .
Specify scheduling options . . . . . . . . .
Enable or disable scheduled commands . . . .
Change processing options used by the scheduler
service. . . . . . . . . . . . . . . .
Manage multiple schedule requirements on one
system . . . . . . . . . . . . . . .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
files
. .
. .
. .
. .
. .
. .
|
Processing options overview . . . . .
Communication options . . . . . . .
TCP/IP options . . . . . . . .
Named Pipes option . . . . . . .
Shared memory options . . . . . .
Backup and archive processing options . .
Restore and retrieve processing options. .
Scheduling options . . . . . . . .
Format and language options . . . . .
Command processing options . . . . .
Authorization options . . . . . . .
Error processing options. . . . . . .
Transaction processing options . . . .
Web client options. . . . . . . . .
Diagnostics options . . . . . . . .
Using options with commands . . . .
Entering options with a command . .
Initial command-line-only options . .
Client options that can be set by the IBM
Spectrum Protect server . . . . . .
Client options reference . . . . . . .
Absolute . . . . . . . . . . .
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
291
292
292
293
293
293
302
305
306
306
307
307
308
309
309
309
310
315
.
.
.
.
.
.
. 316
. 317
. 318
|
Adlocation . . . . . . . . . . . .
Archmc. . . . . . . . . . . . . .
Asnodename . . . . . . . . . . . .
Session settings and schedules for a proxy
operation . . . . . . . . . . . .
Asrmode . . . . . . . . . . . . .
Auditlogging . . . . . . . . . . .
Auditlogname . . . . . . . . . . .
Autodeploy . . . . . . . . . . . .
Autofsrename . . . . . . . . . . .
Backmc. . . . . . . . . . . . . .
Backupsetname . . . . . . . . . . .
Basesnapshotname . . . . . . . . . .
Cadlistenonport . . . . . . . . . .
Casesensitiveaware . . . . . . . . .
Changingretries . . . . . . . . . .
Class . . . . . . . . . . . . . .
Clientview . . . . . . . . . . . .
Clusterdisksonly . . . . . . . . . .
Clusternode . . . . . . . . . . . .
Collocatebyfilespec . . . . . . . . .
Commmethod . . . . . . . . . . . .
Commrestartduration . . . . . . . . .
Commrestartinterval . . . . . . . . .
Compressalways. . . . . . . . . . .
Compression . . . . . . . . . . . .
Console . . . . . . . . . . . . .
Createnewbase . . . . . . . . . . .
Datacenter . . . . . . . . . . . .
Datastore . . . . . . . . . . . .
Dateformat . . . . . . . . . . . .
Dedupcachepath. . . . . . . . . . .
Dedupcachesize. . . . . . . . . . .
Deduplication . . . . . . . . . . .
Deletefiles . . . . . . . . . . . .
Description . . . . . . . . . . . .
Detail. . . . . . . . . . . . . .
Diffsnapshot . . . . . . . . . . .
Diffsnapshotname . . . . . . . . . .
Dirmc . . . . . . . . . . . . . .
Dirsonly . . . . . . . . . . . . .
Disablenqr . . . . . . . . . . . .
Diskbuffsize . . . . . . . . . . .
Diskcachelocation . . . . . . . . .
Domain. . . . . . . . . . . . . .
Domain.image . . . . . . . . . . .
Domain.nas . . . . . . . . . . . .
Domain.vmfull . . . . . . . . . . .
Enable8dot3namesupport. . . . . . . .
Enablearchiveretentionprotection . . . .
Enablededupcache . . . . . . . . . .
Enableinstrumentation . . . . . . . .
Enablelanfree . . . . . . . . . . .
Encryptiontype. . . . . . . . . . .
Encryptkey . . . . . . . . . . . .
Errorlogmax . . . . . . . . . . . .
Errorlogname . . . . . . . . . . .
Errorlogretention . . . . . . . . .
Exclude options . . . . . . . . . .
Controlling compression processing . . .
Processing NAS file systems . . . . .
. 319
. 319
. 320
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
322
323
324
326
328
329
331
332
333
334
335
336
337
338
338
341
342
343
344
345
346
347
348
350
352
352
352
355
355
356
357
358
359
360
362
363
364
364
365
366
367
370
371
372
381
383
384
385
387
388
389
391
392
393
395
398
398
|
|
Virtual machine exclude options . . . .
Fbbranch . . . . . . . . . . . . .
Fbclientname . . . . . . . . . . .
Fbpolicyname . . . . . . . . . . .
Fbreposlocation . . . . . . . . . .
Fbserver . . . . . . . . . . . . .
Fbvolumename . . . . . . . . . . .
Filelist . . . . . . . . . . . . .
Filename . . . . . . . . . . . . .
Filesonly . . . . . . . . . . . .
Forcefailover . . . . . . . . . . .
Fromdate . . . . . . . . . . . . .
Fromnode . . . . . . . . . . . . .
Fromtime . . . . . . . . . . . . .
Groupname . . . . . . . . . . . .
Host . . . . . . . . . . . . . .
Httpport . . . . . . . . . . . . .
Hsmreparsetag . . . . . . . . . . .
Ieobjtype . . . . . . . . . . . .
Ifnewer . . . . . . . . . . . . .
Imagegapsize . . . . . . . . . . .
Imagetofile . . . . . . . . . . . .
Inactive . . . . . . . . . . . . .
Inclexcl . . . . . . . . . . . . .
Considerations for Unicode-enabled clients
Include options. . . . . . . . . . .
Compression and encryption processing .
Processing NAS file systems . . . . .
Virtual machine include options . . . .
Incrbydate . . . . . . . . . . . .
Incremental . . . . . . . . . . . .
Incrthreshold . . . . . . . . . . .
Instrlogmax . . . . . . . . . . . .
Instrlogname . . . . . . . . . . .
Journalpipe . . . . . . . . . . . .
Lanfreecommmethod . . . . . . . . .
Lanfreeshmport. . . . . . . . . . .
Lanfreetcpport. . . . . . . . . . .
Lanfreessl . . . . . . . . . . . .
Lanfreetcpserveraddress . . . . . . .
Language . . . . . . . . . . . . .
Latest. . . . . . . . . . . . . .
Localbackupset. . . . . . . . . . .
Managedservices . . . . . . . . . .
Maxcmdretries . . . . . . . . . . .
Mbobjrefreshthresh . . . . . . . . .
Mbpctrefreshthresh . . . . . . . . .
Memoryefficientbackup . . . . . . . .
Mode . . . . . . . . . . . . . .
Monitor . . . . . . . . . . . . .
Myprimaryserver . . . . . . . . . .
Myreplicationserver . . . . . . . . .
Namedpipename . . . . . . . . . . .
Nasnodename . . . . . . . . . . . .
Nodename . . . . . . . . . . . . .
Nojournal . . . . . . . . . . . .
Noprompt . . . . . . . . . . . . .
Nrtablepath . . . . . . . . . . . .
Numberformat . . . . . . . . . . .
Optfile . . . . . . . . . . . . .
Password . . . . . . . . . . . . .
Contents
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
399
402
403
405
406
408
409
410
413
414
415
416
416
417
418
418
419
419
421
422
422
423
424
425
425
426
431
431
432
442
443
443
444
445
446
447
448
449
450
451
451
452
453
454
456
456
457
458
460
464
464
465
467
467
468
470
470
471
472
474
474
vii
|
|
|
|
|
|
|
|
Passwordaccess. . . . . . . . . .
Pick . . . . . . . . . . . . .
Pitdate . . . . . . . . . . . .
Pittime . . . . . . . . . . . .
Postschedulecmd/Postnschedulecmd . . .
Postsnapshotcmd . . . . . . . . .
Preschedulecmd/Prenschedulecmd . . .
Preservelastaccessdate. . . . . . .
Preservepath . . . . . . . . . .
Presnapshotcmd. . . . . . . . . .
Queryschedperiod . . . . . . . . .
Querysummary . . . . . . . . . .
Quiet . . . . . . . . . . . . .
Quotesareliteral . . . . . . . . .
Replace . . . . . . . . . . . .
Replserverguid. . . . . . . . . .
Replservername. . . . . . . . . .
Replsslport . . . . . . . . . . .
Repltcpport . . . . . . . . . . .
Repltcpserveraddress . . . . . . .
Resetarchiveattribute . . . . . . .
Resourceutilization . . . . . . . .
Regulating backup and archive sessions
Regulating restore sessions . . . . .
Multiple client session considerations .
Retryperiod . . . . . . . . . . .
Revokeremoteaccess . . . . . . . .
Runasservice . . . . . . . . . .
Schedcmddisabled . . . . . . . . .
Schedcmdexception . . . . . . . .
Schedgroup . . . . . . . . . . .
Schedlogmax . . . . . . . . . . .
Schedlogname . . . . . . . . . .
Schedlogretention . . . . . . . .
Schedmode . . . . . . . . . . .
Schedrestretrdisabled . . . . . . .
Scrolllines . . . . . . . . . . .
Scrollprompt . . . . . . . . . .
Sessioninitiation . . . . . . . .
Setwindowtitle. . . . . . . . . .
Shmport . . . . . . . . . . . .
Showmembers . . . . . . . . . . .
Skipmissingsyswfiles . . . . . . .
Skipntpermissions . . . . . . . .
Skipntsecuritycrc . . . . . . . .
Skipsystemexclude . . . . . . . .
Snapdiff . . . . . . . . . . . .
Snapdiffchangelogdir . . . . . . .
Snapdiffhttps . . . . . . . . . .
Snapshotproviderfs . . . . . . . .
Snapshotproviderimage . . . . . . .
Snapshotroot . . . . . . . . . .
Srvoptsetencryptiondisabled . . . . .
Srvprepostscheddisabled . . . . . .
Srvprepostsnapdisabled. . . . . . .
Ssl . . . . . . . . . . . . . .
Sslacceptcertfromserv . . . . . . .
Ssldisablelegacytls . . . . . . . .
Sslfipsmode . . . . . . . . . . .
Sslrequired . . . . . . . . . . .
Stagingdirectory . . . . . . . . .
viii
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
476
477
478
479
480
482
483
485
486
488
490
491
492
493
494
496
497
498
500
501
502
504
505
505
506
507
507
508
509
510
511
512
514
515
516
518
518
519
520
522
523
524
524
525
526
527
528
533
534
536
536
537
540
540
541
542
544
544
545
546
548
|
|
|
|
|
|
|
Subdir. . . . . . . .
Systemstatebackupmethod .
Tapeprompt . . . . . .
Tcpadminport . . . . .
Tcpbuffsize . . . . . .
Tcpcadaddress . . . . .
Tcpclientaddress . . . .
Tcpclientport . . . . .
Tcpnodelay . . . . . .
Tcpport . . . . . . .
Tcpserveraddress . . . .
Tcpwindowsize . . . . .
Timeformat . . . . . .
Toc . . . . . . . . .
Todate. . . . . . . .
Totime. . . . . . . .
Txnbytelimit . . . . .
Type . . . . . . . .
Usedirectory . . . . .
Useexistingbase . . . .
Usereplicationfailover. .
V2archive . . . . . .
Verbose . . . . . . .
Verifyimage . . . . . .
Virtualfsname . . . . .
Virtualnodename . . . .
Vmautostartvm . . . . .
Vmbackdir . . . . . .
Vmbackuplocation . . . .
Vmbackupmailboxhistory. .
Vmbackuptype . . . . .
Vmchost . . . . . . .
Vmcpw . . . . . . . .
Vmctlmc . . . . . . .
Vmcuser . . . . . . .
Vmdatastorethreshold . .
Vmdefaultdvportgroup . .
Vmdefaultdvswitch . . .
Vmdefaultnetwork . . .
Vmdiskprovision . . . .
Vmenabletemplatebackups .
Vmexpireprotect . . . .
Vmiscsiadapter. . . . .
Vmiscsiserveraddress . .
Vmlimitperdatastore . . .
Vmlimitperhost. . . . .
Vmlist. . . . . . . .
Vmmaxbackupsessions . . .
Vmmaxparallel . . . . .
Vmmaxpersnapshot . . . .
Vmmaxrestoresessions . .
Vmmaxrestoreparalleldisks
Vmmaxsnapshotretry . . .
Vmmaxvirtualdisks . . .
Vmmc . . . . . . . .
Vmmountage . . . . . .
Vmnoprdmdisks . . . . .
Vmnovrdmdisks . . . . .
Vmpreferdagpassive . . .
Vmprocessvmwithindependent
Vmprocessvmwithphysdisks .
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
549
551
552
553
554
555
556
557
557
558
559
559
561
562
563
564
565
566
567
568
569
570
570
571
572
572
573
574
575
577
578
579
580
580
582
583
584
585
586
587
588
589
590
591
592
593
594
595
597
599
600
601
602
603
604
605
606
607
608
609
610
|
Vmprocessvmwithprdm .
Vmrestoretype . . .
Vmskipctlcompression
Vmskipmaxvirtualdisks
Vmskipmaxvmdks. .
Vmskipphysdisks . .
Vmstoragetype . . .
Vmtagdatamover. . .
Vmtagdefaultdatamover
Vmtempdatastore . .
Vmverifyifaction . .
Vmverifyiflatest . .
Vmvstortransport . .
Vssaltstagingdir . .
Vssusesystemprovider
Vmtimeout . . . .
Webports . . . . .
Wildcardsareliteral .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
611
612
615
615
616
617
618
619
621
623
624
626
627
628
629
630
631
632
Chapter 12. Using commands . . . . 635
Start and end a client command session . . . .
Process commands in batch mode . . . . .
Process commands in interactive mode . . . .
Enter client command names, options, and
parameters . . . . . . . . . . . . . .
Command name . . . . . . . . . . .
Options . . . . . . . . . . . . . .
Options in interactive mode . . . . . .
Parameters . . . . . . . . . . . . .
File specification syntax . . . . . . . . .
Wildcard characters . . . . . . . . . . .
Client commands reference . . . . . . . . .
Archive . . . . . . . . . . . . . . .
Open file support . . . . . . . . . . .
Archive FastBack . . . . . . . . . . . .
Backup FastBack . . . . . . . . . . . .
Backup Group . . . . . . . . . . . . .
Backup Image . . . . . . . . . . . . .
Offline and online image backup . . . . . .
Utilizing image backup to perform file system
incremental backup . . . . . . . . . .
Backup NAS . . . . . . . . . . . . .
Backup Systemstate . . . . . . . . . . .
Backup VM . . . . . . . . . . . . . .
Cancel Process . . . . . . . . . . . . .
Cancel Restore . . . . . . . . . . . . .
Delete Access . . . . . . . . . . . . .
Delete Archive . . . . . . . . . . . . .
Delete Backup . . . . . . . . . . . . .
Delete Filespace . . . . . . . . . . . .
Delete Group . . . . . . . . . . . . .
Expire . . . . . . . . . . . . . . . .
Help . . . . . . . . . . . . . . . .
Incremental . . . . . . . . . . . . . .
Open file support . . . . . . . . . . .
Journal-based backup. . . . . . . . . .
Backing up NTFS or ReFS volume mount points
Backing up data on NTFS or ReFS mounted
volumes . . . . . . . . . . . . .
Back up Microsoft Dfs root . . . . . . . .
Incremental-by-Date . . . . . . . . . .
638
638
639
639
640
640
640
640
641
642
643
643
645
646
649
652
654
656
657
658
660
662
678
678
679
679
681
685
686
688
689
691
695
695
696
697
697
698
Associate a local snapshot with a server file
space . . . . . . . . . . . . . .
Loop . . . . . . . . . . . . . . .
Macro . . . . . . . . . . . . . . .
Monitor Process . . . . . . . . . . .
Preview Archive . . . . . . . . . . .
Preview Backup . . . . . . . . . . .
Query Access . . . . . . . . . . . .
Query Adobjects . . . . . . . . . . .
Query Archive . . . . . . . . . . . .
Query Backup . . . . . . . . . . . .
Query NAS file system images . . . . .
Query Backupset . . . . . . . . . . .
Query Backupset without the backupsetname
parameter . . . . . . . . . . . .
Query Filespace . . . . . . . . . . .
Query NAS file spaces . . . . . . . .
Query Group . . . . . . . . . . . .
Query Image . . . . . . . . . . . .
Query Inclexcl . . . . . . . . . . . .
Query Mgmtclass . . . . . . . . . . .
Query Node. . . . . . . . . . . . .
Query Options . . . . . . . . . . . .
Query Restore . . . . . . . . . . . .
Query Schedule . . . . . . . . . . .
Query Session . . . . . . . . . . . .
Query Systeminfo . . . . . . . . . .
Query Systemstate . . . . . . . . . .
Query VM . . . . . . . . . . . . .
Restart Restore. . . . . . . . . . . .
Restore . . . . . . . . . . . . . .
Restoring NTFS or ReFS volume mount points
Restoring data on NTFS mounted volumes
Restore Microsoft Dfs junctions . . . . .
Restore active files. . . . . . . . . .
Universal Naming Convention restores . . .
Restore from file spaces that are not
Unicode-enabled . . . . . . . . . .
Restore named streams . . . . . . . .
Restore sparse files . . . . . . . . .
Restore Adobjects. . . . . . . . . . .
Restore Backupset . . . . . . . . . .
Restore backup sets: considerations and
restrictions . . . . . . . . . . . .
Restore backup sets in a SAN environment .
Restore Backupset without the backupsetname
parameter . . . . . . . . . . . .
Restore Group . . . . . . . . . . . .
Restore Image . . . . . . . . . . . .
Restore NAS . . . . . . . . . . . .
Restore Systemstate . . . . . . . . . .
Restore VM . . . . . . . . . . . . .
Retrieve . . . . . . . . . . . . . .
Retrieve archives from file spaces that are not
Unicode-enabled . . . . . . . . . .
Retrieve named streams . . . . . . . .
Retrieve sparse files . . . . . . . . .
Schedule . . . . . . . . . . . . . .
Selective . . . . . . . . . . . . . .
Open file support . . . . . . . . . .
Contents
.
.
.
.
.
.
.
.
.
.
.
.
698
698
699
700
701
702
703
703
705
707
711
711
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
712
714
716
716
718
719
721
722
723
724
725
725
726
728
729
737
737
742
742
. 743
. 743
. 743
.
.
.
.
.
744
744
744
745
746
. 749
. 750
.
.
.
.
.
.
.
750
753
754
758
760
760
769
.
.
.
.
.
.
772
773
773
773
775
777
ix
|
Associate a local snapshot with a server file
space . . . . . . . . . . . . . .
Set Access . . . . . . . . . . . . .
Set Event. . . . . . . . . . . . . .
Set Netappsvm . . . . . . . . . . .
Set Password . . . . . . . . . . . .
Set Vmtags . . . . . . . . . . . . .
Data protection tagging overview . . . .
Representation of tags in the IBM Spectrum
Protect vSphere Client plug-in . . . . .
Supported data protection tags . . . .
Inheritance of data protection settings . .
Tips for data protection tagging . . . .
x
.
.
.
.
.
.
.
778
778
781
783
784
790
791
.
.
.
.
792
792
800
802
Appendix. Accessibility features for
the IBM Spectrum Protect product
family. . . . . . . . . . . . . . . 803
Notices . . . . . . . . . . . . . . 805
Glossary . . . . . . . . . . . . . 809
Index . . . . . . . . . . . . . . . 811
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Tables
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
|
|
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
Windows client communication methods . . . 4
Supported features on Windows platforms
4
Stoppable services . . . . . . . . . . 11
File path and name limits . . . . . . . . 22
Client acceptor-managed services versus
traditional scheduler services. . . . . . . 30
Data deduplication settings: Client and server 51
Options for excluding file spaces and
directories . . . . . . . . . . . . . 90
Options for controlling processing using
include and exclude statements . . . . . . 91
Wildcard and other special characters . . . . 94
Specifying a drive specification using
wildcards . . . . . . . . . . . . . 95
Using wildcard characters with include and
exclude patterns . . . . . . . . . . . 96
Options for controlling compression and
encryption processing . . . . . . . . . 96
UNC name patterns and DOS patterns
100
Required user security rights for IBM
Spectrum Protect backup and restore services . 108
Working with your files using the
backup-archive client GUI . . . . . . . 121
Planning your backups . . . . . . . . 125
Command line backup examples . . . . . 131
Maximum file size . . . . . . . . . . 138
Comparing incremental image backup
methods . . . . . . . . . . . . . 160
NAS options and commands . . . . . . 164
Backup and restore capabilities for VMware
virtual machines on Windows platforms . . 168
Client command line informational messages 175
UNC examples . . . . . . . . . . . 181
Command-line restore examples . . . . . 188
Backup set GUI restore restrictions . . . . 198
Backup set command-line restore restrictions 198
Components for the restore command when
you restore files to the same computer . . . 214
Components for the restore command when
you restore files to a different computer. . . 215
NAS options and commands . . . . . . 231
Command-line archive examples . . . . . 235
Command line examples of retrieving
archives . . . . . . . . . . . . . 240
Sample classic query schedule output
249
Sample enhanced query schedule output
250
Client return codes and their meanings
259
Default attribute values in the standard
management class . . . . . . . . . . 263
TCP/IP options . . . . . . . . . . . 292
Named Pipes communication option
293
Shared memory communication options
293
Backup and archive processing options
293
Restore and retrieve processing options
302
Scheduling options. . . . . . . . . . 305
Format and language options . . . . . . 306
© Copyright IBM Corp. 1993, 2017
|
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
|
|
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
Command processing options . . . . . .
Authorization options. . . . . . . . .
Error processing options . . . . . . . .
Transaction processing options . . . . . .
Web client options . . . . . . . . . .
Diagnostics options . . . . . . . . .
Client command options . . . . . . . .
Options that are valid on the initial command
line only . . . . . . . . . . . . .
Options that can be set by the IBM Spectrum
Protect server . . . . . . . . . . .
Setting the value of the asnodename option to
distribute backups.. . . . . . . . . .
Clusternode and clusterdisksonly
combinations. . . . . . . . . . . .
Interaction of domain definitions from several
sources. . . . . . . . . . . . . .
System services components and
corresponding keywords . . . . . . . .
Other optional parameters . . . . . . .
Incremental command: Related options
Effects of server and client SSL settings on
success or failure of login attempts . . . .
Commands . . . . . . . . . . . .
Wildcard characters . . . . . . . . .
Archive command: Related options . . . .
Archive FastBack command: Related options
Backup FastBack command: Related options
Backup Group command: Related options
Backup Image command: Related options
Backup NAS command: Related options
Delete Archive command: Related options
Delete Backup command: Related options
Delete Filespace command: Related options
Delete Group command: Related options
Expire command: Related options. . . . .
Incremental command: Related options
Query Adobjects command: Related options
Query Archive command: Related options
Query Backup command: Related options
Query Backupset command: Related options
Query Backupset command: Related options
Query Filespace command: Related options
Query Group command: Related options
Query Image command: Related options
Query Mgmtclass command: Related options
Query Node command: Related options
Query Options command: Related options
Query Systeminfo command: Related options
Query Systemstate command: Related options
Query VM command: Related options for
VMware virtual machine queries. . . . . .
Query VM command: Related options for
Hyper-V virtual machine queries. . . . . .
Restore command: Related options . . . .
Restore Adobjects command: Related options
307
307
307
308
309
309
311
316
317
320
340
370
397
429
530
547
635
643
644
647
650
653
655
660
680
684
686
687
689
693
704
706
709
712
713
715
717
719
722
723
723
727
728
730
733
740
745
xi
90.
91.
92.
93.
94.
95.
xii
Restore Backupset command: Related options
Restore Group command: Related options
Restore Image command: Related options
Restore NAS command: Related options
Restore VM command: Related options when
restoring VMware virtual machines . . . .
Restore VM command: Related options when
restoring Hyper-V virtual machines . . . .
748
753
756
759
96.
97.
98.
99.
Retrieve command: Related options . .
Schedule command: Related options . .
Selective command: Related options . .
Order of precedence of vSphere inventory
objects . . . . . . . . . . . .
764
768
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
.
.
.
. 771
. 774
. 776
.
. 801
About this publication
IBM Spectrum Protect™ is a client/server licensed product that provides storage
management services in a multiplatform computer environment.
The backup-archive client program enables users to back up and archive files from
their workstations or file servers to storage, and restore and retrieve backup
versions and archived copies of files to their local workstations.
In addition to the backup-archive client, IBM Spectrum Protect includes the
following components:
v A server program that acts as a backup and archive server for distributed
workstations and file servers.
v An administrative client program that you can access from a web browser or
from the command line. The program enables the IBM Spectrum Protect
administrator to control and monitor server activities, define storage
management policies for backup, archive, and space management services, and
set up schedules to perform those services at regular intervals.
v An application programming interface (API) that you can use to enhance an
existing application with storage management services. When an application is
registered with a server as a client node, the application can back up, restore,
archive, and retrieve objects from storage.
v A web backup-archive client that enables an authorized administrator, help desk
person, or other users to perform backup, restore, archive, and retrieve services
by using a web browser on a remote system.
Related concepts:
“Planning your backups (Windows)” on page 125
“What's new for Version 8.1.2” on page xvii
Chapter 1, “Installing the IBM Spectrum Protect backup-archive clients,” on page 1
Who should read this publication
This publication provides instructions for a user to install, configure, and use the
IBM Spectrum Protect client.
Unless otherwise specified, references to Windows refer to all supported Microsoft
Windows operating systems.
Publications
The IBM Spectrum Protect product family includes IBM Spectrum Protect
Snapshot, IBM Spectrum Protect for Space Management, IBM Spectrum Protect for
Databases, and several other storage management products from IBM®.
To view IBM product documentation, see IBM Knowledge Center.
© Copyright IBM Corp. 1993, 2017
xiii
Conventions used in this publication
This publication uses the following typographical conventions:
Example
Description
autoexec.ncf
hsmgui.exe
A series of lowercase letters with an extension indicates program file
names.
DSMI_DIR
A series of uppercase letters indicates return codes and other values.
dsmQuerySessInfo Boldface type indicates a command that you type on a command line,
the name of a function call, the name of a structure, a field within a
structure, or a parameter.
timeformat
Boldface italic type indicates a backup-archive client option. The bold
type is used to introduce the option, or used in an example.
dateformat
Italic type indicates an option, the value of an option, a new term, a
placeholder for information you provide, or for special emphasis in the
text.
maxcmdretries
Monospace type indicates fragments of a program or information as it
might appear on a display screen, such a command example.
plus sign (+)
A plus sign between two keys indicates that you press both keys at the
same time.
Reading syntax diagrams
To read a syntax diagram for entering a command, follow the path of the line.
Read from left to right and from top to bottom.
v The ►►─── symbol indicates the beginning of a syntax diagram.
v The ───► symbol at the end of a line indicates that the syntax diagram continues
on the next line.
v The ►─── symbol at the beginning of a line indicates that a syntax diagram
continues from the previous line.
v The ───►◄ symbol indicates the end of a syntax diagram.
Syntax items, such as a keyword or a variable, can be:
v On the line (required element)
v Above the line (default element)
v Below the line (optional element)
Symbols
Enter these symbols exactly as they appear in the syntax diagram.
v * Asterisk
v { } Braces
v : Colon
v , Comma
v = Equal Sign
v - Hyphen
v () Parentheses
v . Period
v
xiv
Space
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
v " quotation mark
v 'single quotation mark
Variables
Italicized lowercase items such as <var_name> indicate variables. In this example,
you can specify a <var_name> when you enter the cmd_name command.
►► cmd_name
<var_name>
►◄
Repetition
An arrow returning to the left means that the item can be repeated. A character
within the arrow means that you must separate repeated items with that character.
,
►► ▼ repeat
►◄
A footnote (1) by the arrow refers to a limit that tells how many times the item can
be repeated.
,
(1)
►► ▼
repeat
►◄
Notes:
1
Specify repeat up to 5 times.
Required choices
When two or more items are in a stack and one of them is on the line, you must
specify one item.
In this example, you must choose A, B, or C.
►► cmd_name
A
B
C
►◄
Optional choices
When an item is below the line, that item is optional. In the first example, you can
select A or nothing at all.
►► cmd_name
►◄
A
When two or more items are in a stack below the line, all of them are optional. In
the second example, you can choose A, B, C, or nothing at all.
About this publication
xv
►► cmd_name
►◄
A
B
C
Repeatable choices
A stack of items followed by an arrow returning to the left indicates that you can
select more than one item, or in some cases, repeat a single item.
In this example, you can select any combination of A, B, or C.
,
►► cmd_name
▼
A
B
C
►◄
Defaults
Defaults are above the line. The default is selected unless you override it, or you
can select the default explicitly. To override the default, include an option from the
stack below the line.
In this example, A is the default. Select either B or C to override A.
A
►► cmd_name
►◄
B
C
xvi
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
What's new for Version 8.1.2
IBM Spectrum Protect Version 8.1.2 introduces new features and updates.
For a list of new features and updates in this release and previous Version 8.1
releases, see Backup-archive client updates.
New and changed information in this product documentation is indicated by a
vertical bar (|) to the left of the change.
Protect your client with enhanced security settings
Beginning in IBM Spectrum Protect Version 8.1.2, several changes are
introduced in the backup-archive client to work with the IBM Spectrum
Protect V8.1.2 server, which provides enhancements to improve the
security between client and server communications.
After the IBM Spectrum Protect server is upgraded to V8.1.2 and
configured with the improved security protocol, and the backup-archive
client is upgraded to V8.1.2, the security settings for the client must be
configured to work with the security enhancements on the server. For more
information about the configuring the client for different security scenarios,
see “Configuring the client security settings to connect to the IBM
Spectrum Protect server version 8.1.2 and later” on page 101.
The following changes are available in this release:
New sslacceptcertfromserv option, changes to three existing SSL-related
options
To simplify the process of distributing server certificates, IBM
Spectrum Protect now includes a new sslacceptcertfromserv
option to control whether the backup-archive client or the API
application accepts and trusts the IBM Spectrum Protect server's
Secure Sockets Layer (SSL) public certificate the first time they
connect.
In addition, three SSL-related options ssl, ssldisablelegacytls,
and sslarequired have changed. Their operation varies depending
on whether operation is with IBM Spectrum Protect server V8.1.2
or with IBM Spectrum Protect server V8.1.1 and earlier V8 levels,
and V7.1.7 and earlier levels.
For a description of these option settings and important version
information, see “Sslacceptcertfromserv” on page 544, “Ssl” on
page 542, “Ssldisablelegacytls” on page 544, and “Sslrequired”
on page 546.
The IBM Spectrum Protect password location is changed
Beginning in V8.1.2, the IBM Global Security Kit (GSKit) keystores
are used to store all IBM Spectrum Protect passwords. When you
upgrade to IBM Spectrum Protect V8.1.2 backup-archive client, the
existing passwords are automatically migrated to new locations on
the client system.
For more information about the new password location and related
considerations, see “Secure password storage” on page 106.
A new way of importing server certificates is available with the
dsmcert utility. For information about importing server certificates,
© Copyright IBM Corp. 1993, 2017
xvii
see “Configuring IBM Spectrum Protect client/server
communication with Secure Sockets Layer” on page 36.
Because of the use of the new secure password storage, new
procedures for granting password access to non-administrative
users are available.
For Windows clients, see “Backup-archive client operations and
security rights” on page 107.
Automatically deploy backup-archive client updates
The IBM Spectrum Protect server administrator can use server
commands to schedule updates for one or more backup-archive
clients. The updates can be fix packs or new releases. This feature
was available in previous releases of IBM Spectrum Protect, but an
improved procedure is available for V8.1.2. For more information,
see Schedule automatic updates for backup-archive clients.
Deprecated functions
The following functions are deprecated in this release:
lanfreessl and replsslport options
Two SSL-related options, lanfreessl and replsslport, are
deprecated and unavailable if you are connecting to an
IBM Spectrum Protect server V8.1.2 and later. These
options are still valid and available if you are connecting to
an IBM Spectrum Protect server V8.1.1 and earlier V8
levels, and V7.1.7 and earlier levels.
IBM Spectrum Protect web client
You can no longer use the web client to connect to the IBM
Spectrum Protect V8.1.2 or later server. However, you can
still use the web client to connect to IBM Spectrum Protect
V8.1.1, V8.1.0, or V7.1.7 or earlier servers. For more
information, see “Using the web client in the new security
environment” on page 117.
NDMP command-line and web client operations
If you are connecting to IBM Spectrum Protect server
V8.1.2 or later, you can no longer use the client
command-line interface or web client to back up or restore
NAS file servers using Network Data Management
Protocol (NDMP). Alternatively, you can use IBM Spectrum
Protect server commands with the administrative
command-line client (dsmadmc) to restore NDMP data. For
more information, see the NDMP information in “Using
the web client in the new security environment” on page
117.
Open registration
If the client is connecting to IBM Spectrum Protect server
V8.1.2 or later, the open registration feature is no longer
available. To connect to the IBM Spectrum Protect server,
you must use closed registration. For more information, see
“Closed registration” on page 87.
Open registration is still available if the client is connecting
to IBM Spectrum Protect V8.1.1, V8.1.0, or V7.1.7 and
earlier servers.
xviii
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
For more information about security improvements on the server, see
Protect your storage environment with an improved security protocol.
Enhanced support for Data Protection for Microsoft Hyper-V running on
Windows Server 2016
Back up virtual machines by using resilient change tracking (RCT)
To improve the scalability and performance of virtual machine
(VM) backups, resilient change tracking (RCT) is used for all VM
backup operations of Hyper-V hosts that run on the Microsoft
Windows Server 2016 operating system.
For more information, see Virtual machine backups with resilient
change tracking (RCT).
Exercise more control over backup operations on VMs with physical
disks You can control whether full Hyper-V RCT VM backups are
processed if the VM has one or more physical disks (pass-through
disks) provisioned.
For more information, see the following options:
v “Vmprocessvmwithphysdisks” on page 610
v “Vmskipphysdisks” on page 617
Specify the number of snapshot attempts and the level of data
consistency for backup operations
To determine the total number of snapshot attempts to try for a
virtual machine that fails during backup processing due to
snapshot failure, use the INCLUDE.VMSNAPSHOTATTEMPTS option. You
can choose to attempt application-consistent or crash-consistent
snapshots.
For more information, see “INCLUDE.VMSNAPSHOTATTEMPTS” on page
437.
Exclude VM disks from or include VM disks in backup operations
You can use the exclude.vmdisk option to exclude a VM disk
(VHDX) from VM backup operations or use the include.vmdisk
option to include a VM disk in VM backup operations.
For more information, see the following topics:
v “Exclude.vmdisk” on page 399
v “Include.vmdisk” on page 434
v “Domain.vmfull” on page 372
v “Backup VM” on page 662
Enhanced support for Data Protection for Microsoft Hyper-V running on
Windows Server 2012 and 2012 R2
Scalability and reliability of VM backups are improved
VMs are logically grouped into a single snapshot to reduce or
eliminate snapshot conflicts at the Hyper-V host level. Improved
snapshot retry processing simplifies scheduling and improves
reliability across cluster nodes.
v To control the number of VMs to include in a snapshot, use the
vmmaxpersnapshot option. For more information, see
“Vmmaxpersnapshot” on page 599.
Backup-archive client updates
xix
v To control how many snapshot retries are attempted, use the
vmmaxsnapshotretry option. For more information, see
“Vmmaxsnapshotretry” on page 602.
Use these grouping and retry improvements along with the
vmmaxparallel option to help improve performance.
For information, see Tuning scheduled VM backups for Windows
Server 2012 and 2012 R2 clusters.
Enhanced Virtual Volumes (VVOL) support
VVOL support is enhanced to include support for persisted snapshots on
the hardware storage and application protection. For more information
about new VVOL support features, see IBM Spectrum Protect for Virtual
Environments: Data Protection for VMware updates.
To use enhanced VVOL features, use the options that are described in the
following sections:
Specify the location for virtual machine backup and restore operations:
local, server, or both
For virtual machines that are hosted on VVOL datastores, you can
now specify one of the following backup locations for backup and
restore operations: local, server, or both. A local backup is a
persisted snapshot on the hardware storage.
To specify the backup location for the Backup VM or Restore VM
command, use the vmbackuplocation option. For more information,
see “Vmbackuplocation” on page 575.
You can also specify the backup location or locations to query
when you run the Query VM command. For more information, see
“Query VM” on page 729.
The Local Backup Management (IBM Spectrum Protect) tags are
available for local backups. For more information, see “Supported
data protection tags” on page 792.
Create a schedule group
You can use the schedgroup option to create a group that contains
multiple schedules. You can then use the IBM Spectrum Protect
vSphere Client plug-in to assign the schedule group to an object in
the VMware vSphere Web client rather than an individual
schedule. An example of the use of this option is to group multiple
daily local backup schedules with a single IBM Spectrum Protect
server backup schedule.
For more information, see “Schedgroup” on page 511.
Restore multiple virtual disks simultaneously
You can use the IBM Spectrum Protect client restore multiple virtual disks
simultaneously on the Microsoft Windows and Linux operating systems by
using the vmmaxrestoreparalleldisks option.
For instructions about setting the option settings, see
“Vmmaxrestoreparalleldisks” on page 601.
The snapdiffchangelogdir client option is added for snapshot differential
backup operations
Snapshot differential backups no longer use the stagingdirectory option
for storing snapshot differential change log files. Beginning with V8.1.2,
xx
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
use the new snapdiffchangelogdir option to specify the location where the
client stores persistent change logs for snapshot differential backups.
For a description of the option settings and important information about
migrating from prior client versions, see “Snapdiffchangelogdir” on page
533.
Related information:
“About this publication” on page xiii
Backup-archive client updates
xxi
xxii
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chapter 1. Installing the IBM Spectrum Protect backup-archive
clients
The IBM Spectrum Protect backup-archive client helps you protect information on
your workstations.
You can maintain backup versions of your files that you can restore if the original
files are damaged or lost. You can also archive infrequently used files, preserve
them in their current state, and retrieve them when necessary.
The backup-archive client works in conjunction with the IBM Spectrum Protect
server. Contact your IBM Spectrum Protect server administrator to obtain backup
or archive access to the server, or refer to the server publications to install and
configure the IBM Spectrum Protect server.
Related concepts:
“What's new for Version 8.1.2” on page xvii
“Planning your backups (Windows)” on page 125
Upgrading the backup-archive client
The following sections explain what you need to do if you are upgrading to IBM
Spectrum Protect backup-archive client Version 8.1.2 from a previous version.
Upgrade path for clients and servers
IBM Spectrum Protect clients and servers can be upgraded at different times. The
combination of servers and clients that you deploy must be compatible with each
other.
To prevent disruption of your backup and archive activities while you upgrade
from one release to another, follow the compatibility guidelines for IBM Spectrum
Protect clients and servers in technote 1053218.
Additional upgrade information
When you upgrade the backup-archive client, there is additional information to
consider before you use the new client software.
Be aware of the following information when you upgrade a backup-archive client:
v The size of the buffer to record change notifications for a particular journal file
system (DirNotifyBufferSize) has changed. The default value is 16 KB.
v For a list of new and changed messages since the previous IBM Spectrum
Protect release, see the client_message.chg file in the client package.
Automatic backup-archive client deployment
The IBM Spectrum Protect server administrator can automatically deploy a
backup-archive client to update workstations where the backup-archive client is
already installed.
The IBM Spectrum Protect server can be configured to automatically upgrade
backup-archive clients on client workstations. The existing backup-archive clients
must be at version 6.4.3 or later.
© Copyright IBM Corp. 1993, 2017
1
For more information about automatically deploying client upgrades from the
server, see the following documents:
v For IBM Spectrum Protect 8.1.2 or later servers, see technote 2004596.
v For IBM Tivoli® Storage Manager V7.1 servers and IBM Spectrum Protect V8.1.0
and V8.1.1 servers, see technote 1673299.
|
|
|
|
|
Restrictions: The following restrictions apply to automatic client deployment:
v The Windows cluster services environment is not supported.
v Only the backup-archive client can be deployed from the IBM Spectrum Protect
server. Other related products such as IBM Spectrum Protect for Space
Management, IBM Spectrum Protect HSM for Windows, IBM Spectrum Protect
for Virtual Environments, and other Data Protection products are not supported.
If a deployment of an unsupported product is attempted, the deployment
process stops with a failure message.
|
|
|
|
|
|
v Do not schedule automatic client deployments to workstations that already have
the IBM Spectrum Protect for ERP application installed on them.
When the server administrator schedules automatic backup-archive client
deployments, the updated client packages (which include the client components
and the API library) are installed on the workstations that receive them. A
dependency check is performed by the client installation program to ensure that
the API library does not conflict with the client package that is already installed.
IBM Spectrum Protect for ERP applications do not use the same installation
technology that is used by the client installation program. Therefore, the client
installation dependency check is not able to detect whether the API library that
is being used by the IBM Spectrum Protect for ERP applications is compatible
with the API library that will be installed by automatic client deployments. If a
client package is automatically deployed to and installed on a workstation, the
API library that is installed might not be compatible with the API library that
was installed by the IBM Spectrum Protect for ERP application. The newly
deployed API library can cause the IBM Spectrum Protect for ERP applications
to fail.
How the autodeploy client option can affect client deployment
You can use the autodeploy option to conditionally enable automatic client
deployment, if the deployment does not require a restart of the client workstation.
By default, the autodeploy option is enabled, and the client workstation is restarted
if required.
To use automatic deployment but not restart the system, specify the autodeploy
noreboot option.
To turn off automatic client deployment, add autodeploy no to the client options
file.
You can set the autodeploy option in the following places:
v On a schedule definition on the IBM Spectrum Protect server. Schedule
definitions that deploy client software updates have an action=deploy statement.
On those schedules, you can include the autodeploy option as part of the
command that you include on the –postnschedulecmd statement.
v On the client node, in an options file that is associated with the client scheduler
or client acceptor. The deployment manager detects options files that are
associated with the scheduler or client acceptor. If multiple scheduler or client
2
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
acceptor processes are running on the same computer at the same time, and the
processes use different options files, the deployment manager uses the
autodeploy option value that is set in one of the options files.
v On the client in the client options file (dsm.opt). The autodeploy option that is
set in the client options file overrides any other autodeploy setting.
Related reference:
“Autodeploy” on page 328
Client environment requirements
Each of the IBM Spectrum Protect clients has hardware and software requirements.
The following list shows the location of the environment prerequisites for each
supported platform.
v “Windows client environment requirements”
v “NDMP support requirements (Extended Edition only)” on page 4
For current information about the client environment prerequisites for all of the
supported backup-archive client platforms, see technote 1243309.
Windows client environment requirements
This section contains client environment information, backup-archive client
components, and hardware and software requirements for the supported Windows
platforms.
Windows client installable components
The backup-archive client is comprised of several installable components.
The installable components for the Windows backup-archive client are as follows:
v Backup-archive command-line client
v Administrative client
v Backup-archive client graphical user interface, which uses Oracle Java™
technology
v Backup-archive web client
v IBM Spectrum Protect API (64-bit)
System requirements for Windows clients
The backup-archive client on Windows requires a minimum amount of disk space
for installation and a supported operating system.
For software and hardware requirements for all supported versions of Windows
clients, including the most recent fix packs, see
technote 1197133.
Windows client communication methods
The TCP/IP and shared memory communication methods are available for the
Windows backup-archive client.
You can use the following communication methods with the Windows
backup-archive client:
Chapter 1. Installing the IBM Spectrum Protect backup-archive clients
3
Table 1. Windows client communication methods
To use this communication
method:
Install this software:
To connect to these IBM
Spectrum Protect servers:
TCP/IP
TCP/IP (Standard with all
supported Windows
AIX®, Linux, Windows
Named Pipes
Named Pipes (Standard with Windows
all supported Windows
platforms)
Shared Memory
TCP/IP (Standard with all
supported Windows
platforms)
Windows
Backup-archive client features that are available on Windows
platforms
This topic lists which features are supported or not supported on the various
Windows platforms.
Table 2 shows the supported and unsupported features on the various Windows
platforms.
Table 2. Supported features on Windows platforms
Windows 10
Windows Server 2012
Windows Server 2012 R2
Windows Server 2016
Journal-based backup
yes
yes
Online image backup
yes
yes
Offline image backup
yes
yes
System state support with Volume Shadowcopy Services
(VSS)
yes
yes
LAN-free operations
yes
yes
Automated System Recovery (ASR)
yes
BIOS: yes
Features
UEFI: yes
Open File Support (OFS)
yes
yes
Windows supported file systems
The IBM Spectrum Protect Windows backup-archive client is supported on specific
file systems.
The Windows backup-archive client supports the following types of file systems:
v File Allocation Table (FAT and FAT32)
v Microsoft New Technology File System (NTFS)
v Microsoft Resilient File System (ReFS). ReFS was introduced on Windows Server
2012 systems.
NDMP support requirements (Extended Edition only)
You can use the Network Data Management Protocol (NDMP) to back up and
restore network attached storage (NAS) file systems to tape drives or libraries that
are locally attached to Network Appliance and EMC Celerra NAS file servers.
NDMP support is available only on IBM Spectrum Protect Extended Edition.
4
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
NDMP support requires the following hardware and software:
v IBM Spectrum Protect Extended Edition
v Tape drive and tape library. For supported combinations, go to: product
information
Installation requirements for backing up and archiving Tivoli Storage
Manager FastBack client data
Before you can back up or archive your FastBack client data, you must install the
required software.
You must install the following software:
v Tivoli Storage Manager FastBack Version 6.1
v Tivoli Storage Manager client V6.1.3.x (where x is 1 or higher) or V6.2 or later
v Tivoli Storage Manager server V6.1.3 or higher
v Tivoli Storage Manager Administration Center V6.1.3
– Required only if you want to use integrated Tivoli Storage Manager FastBack
- administration.
Starting with V7.1, the Administration Center component is no longer
included in Tivoli Storage Manager or IBM Spectrum Protect distributions.
FastBack users who have an Administration Center from a previous server
release, can continue to use it to create and modify FastBack schedules. If you
do not already have an Administration Center installed, you can download
the previously-released version from ftp://public.dhe.ibm.com/storage/tivolistorage-management/maintenance/admincenter/v6r3/. If you do not already
have an Administration Center installed, you must create and modify
FastBack schedules on the IBM Spectrum Protect server. For information
about creating schedules on the server, see the IBM Spectrum Protect server
documentation.
The Tivoli Storage Manager FastBack environment must be running. For
information about installing and setting up Tivoli Storage Manager FastBack, see
the product information at Tivoli Storage Manager FastBack.
For information about integrating IBM Spectrum Protect and Tivoli Storage
Manager FastBack, see Integrating Tivoli Storage Manager FastBack and IBM
Spectrum Protect.
You can install the IBM Spectrum Protect client in one of the following ways:
v Install the backup-archive client on a workstation where the FastBack server is
installed. In this case, the prerequisites are: the FastBack server, the FastBack
shell, and the FastBack mount.
v Install the backup-archive client on a workstation where the FastBack Disaster
Recovery Hub is installed. In this case, the prerequisites are: the FastBack
Disaster Recovery Hub setup, the FastBack shell, and the FastBack mount.
v Install the backup-archive client on a workstation where neither the FastBack
server or the FastBack Disaster Recovery Hub is installed. In this case, ensure
that the FastBack shell and the FastBack mount are installed.
Related concepts:
“Configuring the client to back up and archive Tivoli Storage Manager FastBack
data” on page 63
Chapter 1. Installing the IBM Spectrum Protect backup-archive clients
5
Client configuration wizard for Tivoli Storage Manager FastBack
The backup-archive client provides a wizard to configure the backup-archive client
for Tivoli Storage Manager FastBack.
The wizard is available in a remote application (the web client) and in a local
application (the Java GUI). The wizard helps you set the options to send FastBack
client data to the IBM Spectrum Protect server on a scheduled basis.
Related concepts:
“Configuring the backup-archive client to protect FastBack client data” on page 64
Windows backup-archive client installation overview
You can install the IBM Spectrum Protect Windows backup-archive client from the
installation media.
Before you begin
Before you begin a Windows client installation, ensure that the system that you
want to install the client on meets the client requirements. Then, determine the
type of installation that you need to perform, and follow the steps in the
appropriate procedure.
For the hardware and software requirements for the Windows client, see technote
1197133.
Related concepts:
“Automatic backup-archive client deployment” on page 1
Related tasks:
“Creating and modifying the client options file” on page 23
“Starting a web client session” on page 117
Windows client installation might require a reboot
As part of the Windows client installation process, one or more Microsoft C++
redistributable packages are installed, if they are not already installed on the
Windows workstation. These packages can also be automatically updated by the
Windows Update service. If the packages are updated, the update can cause the
system to reboot when you start the Windows client installation program.
The reboot that is triggered if the C++ redistributable packages are updated can
occur, even under any of the following conditions:
v An automatic client deployment pushes a client upgrade to a node, and the
client or the scheduler sets the AUTODEPLOY=NOREBOOT option.
v A manual installation or upgrade of the client is started.
v A client silent installation is started, even if the options to suppress reboot
prompts, and the client reboot itself, are set.
Additionally, because the Microsoft Visual Studio C++ redistributable package is a
shared Windows component, other applications that have dependencies on the
package might be stopped or restarted by Windows as part of the installation or
upgrade of the C++ redistributable package. Schedule client installations and
upgrades during a maintenance window when other applications will not be
adversely affected if they are stopped or restarted when the C++ redistributable
6
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
package is installed. Monitor other applications after the client is installed to see
whether there are any applications that were stopped and not restarted.
Installation procedures
The procedure that you follow to install the IBM Spectrum Protect Windows
backup-archive client depends on the type of installation that you want to perform.
Procedures are provided for each of the following installation types:
Installation type
Installation description
Installing the Windows client for the first
time
Describes how to install the Windows
backup-archive client for the first time. This
procedure presumes that the Windows
computer that you are installing the client
on has never had a previous version of the
client installed on it before.
Upgrading the Windows client
Describes how to upgrade an earlier version
of the Windows backup-archive client to this
latest version.
Reinstalling the Windows client
Describes how to reinstall the Windows
backup-archive client, if you uninstalled it.
Silent installation
Describes how to install the Windows
backup-archive client silently, without user
interaction during the installation procedure.
Repairing, modifying, or uninstalling the
Windows client
Describes how to add or remove features
from an installed backup-archive client
(modify), replace damaged files or missing
registry keys (repair), or uninstall the
Windows backup-archive client.
Installing the Windows client for the first time
Complete this procedure to install the Windows backup-archive client for the first
time.
Before you begin
If you have an earlier version of the Windows backup-archive client that is already
installed on a node and you want to upgrade it to Version 8.1.2, see “Upgrading
the Windows client” on page 11.
Important: You must know the host name or IP address of the IBM Spectrum
Protect server, the port number that the server listens on for client
communications, and the communications method to use when the client
communicates with the server. Obtain this information from your IBM Spectrum
Protect server administrator before you start this procedure.
Procedure
1. Download the appropriate package file from one of the following websites.
v Download the client package from Passport Advantage or Fix Central.
v For the latest information, updates, and maintenance fixes, go to the IBM
Support Portal.
2. Install the product by using the compressed installation file that you
download from Passport Advantage®.
Chapter 1. Installing the IBM Spectrum Protect backup-archive clients
7
a. Copy the downloaded compressed installation package to a local disk or to
a network-accessible share. Be sure to extract the installation files to an
empty directory.
b. To extract the installation files to the same directory, double-click the
compressed installation package.
c. By default, the uncompressed files are stored in the current disk drive, in
the download_directory\TSMClient directory. If the installation program
detects files from another client installation attempt in this directory, you
are prompted about whether to overwrite the old files. If you receive this
prompt, enter A to overwrite the existing files; this selection ensures that
only the files from the current installation are used.
d. Double-click the spinstall.exe file to start the client installation program.
3. Select a language to use for this installation and click OK.
4. If the installation wizard indicates that one or more Microsoft C++
redistributable files must be installed, click Install. These files are needed to
run the Windows client.
5. On the IBM Spectrum Protect client welcome screen, click Next to begin
installing the client software.
6. Accept the default installation directory by clicking Next, or specify a different
installation directory. The default installation directory is C:\Program
Files\Tivoli\TSM.
7. Select the installation type: Typical or Custom.
Option
Description
Typical
A typical installation installs the following
components:
v The backup-archive client GUI files
(needed to use the Java GUI)
v The backup-archive client web files
(needed to use the web client)
v The client API files (as needed by your
client and operating system)
Custom
A custom installation installs the same files
as a typical installation. However, you can
choose to install the following optional
components:
v The API SDK files (only needed if you are
developing applications that work with
the backup-archive client
v The Administrative Client command-line
files (required to remotely run
administrator functions on the IBM
Spectrum Protect server
8. Click Next, then click Install.
9. When the installer completes the installation, click Finish.
10. Verify the installation. Click Start > All Programs > IBM Spectrum Protect.
The client components that you installed are shown in the list of IBM
Spectrum Protect startable programs. The administrative command-line client,
backup-archive command-line client, and the backup-archive GUI are the only
components that are displayed in this list. The administrative command-line
client is only shown if you perform a custom installation and you include the
8
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
administrative command-line client. If you installed other components, such
as the API Runtime and SDK, they are not shown in this list.
11. Click Backup-Archive GUI to start the client GUI. The Client Options File
Configuration Wizard starts. Click Next to start the wizard.
12. On the Options File Task screen, select Create a new options file and click
Next.
13. On the Client Node Name screen, specify a node name. A node name
uniquely identifies your node to the IBM Spectrum Protect server. The default
node name is the short host name of the Windows computer that you are
installing the client on. Accept the default node name or specify a new node
name. Click Next.
14. On the IBM Spectrum Protect Client/Server Communications screen, specify
the communications method to use when the client communicates with the
server and click Next. This information must be provided to you by your IBM
Spectrum Protect server administrator. If you are not sure what to select,
accept the default setting (TCP/IP). If the default setting does not work when
the client attempts to connect to the server, contact the server administrator to
determine which communications method to specify.
15. On the TCP/IP Options screen, specify the server address and port
information that your IBM Spectrum Protect administrator provided to you. In
the Server Address field, specify the IP address or fully qualified domain
name of the IBM Spectrum Protect server. In the Port Number field, specify
the port number that the server listens on for client communications. The
default port number is 1500. Click Next.
16. The Recommended Include/Exclude List screen contains a list of system files
and directories that are typically included, or excluded from client operations.
The excluded files are typically not required to restore your system. You can
select or clear all default selections. Alternatively, you can use the Shift and
Ctrl keys to selectively include objects. To facilitate the installation process,
click Select All; you can add or remove files from this list later, if you want
to. Click Next.
17. The Common File Exclusion Selection screen provides a default list of file
extensions that you can exclude from client operations. The file extensions that
are provided in this list are typically large files, like graphics or multimedia
extension. These files consume server disk space but they might not be
required to restore critical data. Click Select All to exclude all of the default
file extensions. Alternatively, you can use the Shift and Ctrl keys to selectively
choose which extensions to exclude from client operations. Click Clear All to
clear any extensions that you selected. You can modify these extensions later if
you want to. Click Next.
18. The Domains for Backup screen specifies the default file systems and objects
to include in client operations for incremental and image backups.
a. To configure the default file systems for incremental backups, in the
Backup Type field, select Incremental. By default, Back up all local file
systems is selected. If you do not want to back up all local file systems as
the default action during incremental backups, clear this option and
individually select the file systems to include. You can override the default
selection when you initiate an incremental backup operation.
b. To configure the default file systems for image backups, in the Backup
Type field, select Image. By default, Back up all local file systems is
selected. If you do not want to back up all local file systems as the default
Chapter 1. Installing the IBM Spectrum Protect backup-archive clients
9
action during image backups, clear this option and individually select the
file systems to include. You can override the default selection when you
initiate an image backup operation.
c. Click Next.
19. On the Confirm and apply your configuration screen, click Apply. You might
be prompted to enter a user ID and password to log on to the IBM Spectrum
Protect server. The user ID defaults to the node name that you specified in
step 13 on page 9.
20. You can accept the default user ID or specify a different user ID. Specify the
password that you will use when you log on to the server. Click Login. What
happens next depends on whether the IBM Spectrum Protect server is
configured for open or closed registration.
Option
Description
Server is configured for open registration
(IBM Spectrum Protect server V8.1.1,
V8.1.0, V7.1.7 or earlier)
The Register New Node screen prompts you
for contact information and it prompts you
again for the password.
Adding text to the Contact Information field
is optional, but suggested; specify your
name.
Re-enter your password, twice, in the two
Password fields. If the password that you
enter and confirm in these Password fields
does not match what you previously
specified in the Login into an IBM Spectrum
Protect server screen, the password that you
specify and confirm here becomes the
password that is required to log on to the
server.
Click Register to register this node on the
server.
Click Finish. The graphical user interface
opens and is ready for use. You can also
start any of the other installed client
components from the Start menu.
Server uses closed registration
Click Finish. Provide the information that
you specified in the client configuration
wizard to your IBM Spectrum Protect server
administrator. Provide the administrator
with the following information:
v The node name that you specified.
v The user ID and password that you
entered.
v Your contact information, such as your
name, email address, and phone number,
so the administrator can contact you after
your node and user information is
registered on the server.
After the administrator registers your node,
you can start any of the installed client
components from the Start menu.
Related concepts:
10
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
“Troubleshooting problems during installation” on page 19
Upgrading the Windows client
You can upgrade an earlier version of the IBM Spectrum Protect Windows
backup-archive client to Version 8.1.2. Your previous configuration settings are
preserved, where it is possible to do so. However, enhancements that are in the
latest version of the client can deprecate or prohibit the use of options that were
available in earlier versions of the client.
Before you begin
Wait for any in-progress backup-archive client tasks (backup, restore, archive,
retrieve) to complete before you upgrade a client node.
About this task
To upgrade to the Version 8.1.2 Windows client, install the Version 8.1.2 Windows
client; you do not need to uninstall previously installed client software first. The
Version 8.1.2 client installation program preserves your current client options and
settings (in dsm.opt), and it does not overwrite or delete the dsmerror.log,
dsmsched.log, and dsmwebcl.log files, if you install the new client into the same
directory that was used by the previous installation.
The Logical Volume Snapshot Agent (LVSA) component was deprecated in IBM
Spectrum Protect Version 6.4. If you previously had LVSA configured as your
snapshot provider, install the Version 8.1.2 client, and then configure it to use the
Microsoft Volume Shadow Copy Service (VSS) as the snapshot provider in the new
installation. If LVSA was installed, your client reboots after the upgrade installation
completes, to allow for the removal of LVSA entries from the registry.
The installation program stops any client services that are running before it
upgrades the client software. If you prefer, you can manually stop the services by
using the control panel or command line. Table 3 shows the stoppable services, and
the names to look for in the Control Panel > Administrative Tools > Services list,
so you can stop them with the Control Panel. The table also provides the
commands to stop them from a command prompt or a script.
Note: The service names that are shown in the table are the default names that are
set by the installation program. You can change some of these service names when
you configure the services by using one of the configuration wizards on the
Utilities > Setup Wizard menus. If you change the service name, record the name
that you specify and use that name to stop the services.
Table 3. Stoppable services
Control panel display name
Command-line procedure
TSM Journal Service
net stop "tsm journal service"
TSM Client Acceptor
net stop "tsm client acceptor"
TSM Client Scheduler
net stop "tsm client scheduler"
Remote Client Agent
net stop "tsm remote client agent"
Complete the following steps to upgrade an earlier version of the Windows
backup-archive client to Version 8.1.2:
Chapter 1. Installing the IBM Spectrum Protect backup-archive clients
11
Procedure
1. Download the appropriate package file from one of the following websites.
v Download the client package from Passport Advantage or Fix Central.
v For the latest information, updates, and maintenance fixes, go to the IBM
Support Portal.
2. Install the product by using the compressed installation file that you
download from Passport Advantage.
a. Copy the downloaded compressed installation package to a local disk or to
a network-accessible share. Be sure to extract the installation files to an
empty directory.
b. To extract the installation files to the same directory, double-click the
compressed installation package.
c. By default, the uncompressed files are stored in the current disk drive, in
the download_directory\TSMClient directory. If the installation program
detects files from another client installation attempt in this directory, you
are prompted about whether to overwrite the old files. If you receive this
prompt, enter A to overwrite the existing files; this selection ensures that
only the files from the current installation are used.
d. Double-click the spinstall.exe file to start the client installation program.
3. Select a language to use for this installation and click OK.
4. If you are prompted to install one, or more, Microsoft C++ redistributable
files, the prompt indicates that your node does not have the C++ files that are
required by the Windows backup-archive client. Click Install to install the
files and continue with the client installation; or, click Cancel to end the
installation process.
5. The backup-archive client installation program starts. On the Welcome screen,
click Next to begin installing the new client software.
6. Accept or change the default installation directory.
7. Select the installation type: Typical or Custom.
Option
Description
Typical
A typical installation installs the following
components:
v The backup-archive client GUI files
(required to use the Java GUI)
v The backup-archive client web files
(required to use the web client)
v The client API files (as needed by your
client and operating system)
Custom
A custom installation installs the same files
as a typical installation. However, you can
choose to install the following optional
components:
v The API SDK files. These files are only
needed if you are developing applications
that work with the backup-archive client.
v The administrative client command line
files. These files are needed if you want to
run administrator functions on the IBM
Spectrum Protect server.
8. Click Next, then click Install.
12
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
9. When the installer completes the installation, click Finish.
10. Verify the installation. Click Start > All Programs > IBM Spectrum Protect.
The client components that you installed are shown in the list of IBM
Spectrum Protect startable programs. This list includes only the administrative
command-line client, backup-archive command-line client, or the
backup-archive GUI. The other installable components (the API Runtime and
SDK files) do not display in this list.
11. Click the Backup-Archive GUI entry in the startable programs list.
a. When prompted, type your user ID and password and click Login.
b. After the GUI starts, click Help > About IBM Spectrum Protect. Verify
that the version shown is Version 8.1.2.
What to do next
Your previous configuration settings are preserved in the dsm.opt file. If you
previously used LVSA as the snapshot provider, warning messages are displayed
when the command-line client is started. The messages provide instructions to edit
the dsm.opt file and remove the LVSA options. Removing the unused options is
not required, but removing options that have no affect or are not used, can
facilitate troubleshooting. If you are using the GUI, the messages are not displayed,
but they are logged in the dsmerror.log file, which is in the client installation
directory, in the baclient directory. Messages are issued when any of the following
options are included in dsm.opt. Some of these options are valid for VSS, and if
they are, the messages are displayed and logged only if they contain parameters
that are specific to LVSA.
v snapshotcachelocation
v snapshotfsidleretries
v snapshotproviderimage
v snapshotproviderfs
v snapshotcachesize
You can set VSS options on the Snapshot tab in the Preferences Editor. They can
also be set by running the online image support and open file support
configuration wizards. To use the wizards, start the GUI and click Utilities > Setup
Wizard. Select the wizards that you want to run, click Next, and follow the
prompts to make your selections.
Related concepts:
“Troubleshooting problems during installation” on page 19
Reinstalling the Windows client
If you uninstall the Version 8.1.2 Windows client, you can reinstall it if you need
to.
About this task
If you reinstall the Windows client into the same directory that it was installed in
before, the previous configuration information is detected by the installation
program. Because the previous configuration information is detected, the
installation process is the same as an upgrade installation; follow the steps in
“Upgrading the Windows client” on page 11 to reinstall the Windows client.
Chapter 1. Installing the IBM Spectrum Protect backup-archive clients
13
If you do not want to preserve the old configuration information, you can remove
it. For information about thoroughly removing client settings and files, see the IBM
developerWorks® article, .How to completely remove the Backup-Archive client
from Microsoft Windows
If you do completely remove all configuration settings and later decide to reinstall
the Windows client, follow the steps in “Installing the Windows client for the first
time” on page 7. That procedure is the appropriate installation procedure to follow
if you reinstall the software into a different directory, or if you reinstall the
software on a system that contains no previous configuration information.
Silent installation
The backup-archive client installation program supports silent, unattended
installations.
Note: The Microsoft Visual C++ 2010 and 2012 redistributable packages are
required to use the backup-archive client. The graphical installation program
installs these packages for you. If you are silently installing the client by using
MSIEXEC, you must separately install the Microsoft Visual C++ 2010 and 2012
redistributable packages. The packages can be installed before or after the silent
installation of the client is completed, but they must be installed before you use the
backup-archive client.
Use the following executable files to install the C++ 2010 and 2012 redistributable
packages. In the paths that are shown, the dir text string represents the drive and
directory where you saved the files when you extracted them from the installation
package.
Windows executable files for installing C++ redistributable packages
dir\ISSetupPrerequisites\{270b0954-35ca-4324-bbc6-ba5db9072dad}
(contains MS 2010 x86 C++ Runtime - vcredist_x86.exe)
dir\ISSetupPrerequisites\{BF2F04CD-3D1F-444e-8960-D08EBD285C3F}
(contains MS 2012 x86 C++ Runtime - vcredist_x86.exe)
dir\ISSetupPrerequisites\{7f66a156-bc3b-479d-9703-65db354235cc}
(contains MS 2010 x64 C++ Runtime - vcredist_x64.exe)
dir\ISSetupPrerequisites\{3A3AF437-A9CD-472f-9BC9-8EEDD7505A02}
(contains MS 2012 x64 C++ Runtime - vcredist_x64.exe)
To install a predefined (custom) dsm.opt file, use the following instructions before
you begin the silent installation.
v Place the customized copy of the dsm.opt file in the ...\CONFIG directory that is
located within the installation image, for example:
C:\tsm_images\TSMClient\Program Files 64\Tivoli\TSM\config
The file must be named dsm.opt.
v The installation program copies the predefined dsm.opt file to the ..\BACLIENT
directory when BOTH of the following conditions are met:
– dsm.opt does NOT exist in the ..\BACLIENT directory. The installation
program does not copy over an existing dsm.opt file.
– dsm.opt exists in the ..\CONFIG directory of the installation image, as
described earlier.
To silently install the C++ redistributables or the backup-archive client, you must
turn off User Account Control (UAC).
14
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
To turn off UAC, use either the Windows Control Panel or the MSCONFIG utility.
v To turn off UAC by using the Control Panel, go to the Control Panel and find
User Account Control settings, then set the notification level to Never Notify.
v To turn off UAC by using the MSCONFIG utility, open a command prompt
window and enter msconfig. Select the User Account Control settings tool, and
set the notification level to Never Notify.
After you install the C++ redistributables and the Windows client, remember to
turn on UAC.
The C++ redistributables require elevated privileges to install them. Open a
command prompt window as follows:
1. Click Start Menu > All Programs > Accessories > Command Prompt.
2. Right-click the Command Prompt icon to view the properties.
3. Click Run as administrator.
4. Click Continue in the permission window.
5. Start the product installation by using the command prompt window.
Silently installing C++ redistributables
Run the following command twice. Run it first from the directory where
the C++ 2010 vcredist_x86.exe file is stored. Then, run it again from the
directory where the C++ 2012 vcredist_x86.exe file is stored.
vcredist_x86.exe /install /quiet /norestart /log logfilename
For more information about the vcredist_x86.exe command, run the
following command:
vcredist_x86.exe /?
Run the following command twice. Run it first from the directory where
the C++ 2010 vcredist_x64.exe file is stored. Then, run it again from the
directory where the C++ 2012 vcredist_x64.exe file is stored.
vcredist_x64.exe /install /quiet /norestart /log logfilename
For more information about the vcredist_x86.exe command, run the
following command:
vcredist_x64.exe /?
Install the Windows backup-archive client. UAC must still be turned off. If it is not
turned off, turn off UAC now. Open a command prompt that has elevated
privileges.
1. Click Start Menu > All Programs > Accessories > Command Prompt.
2. Right-click the Command Prompt icon to view the properties.
3. Click Run as administrator.
4. Click Continue in the permission window.
5. Start the Windows backup-archive client silent installation by using the
command prompt window. Use the following instructions to silently install the
Windows client and API.
Silent installation of the Windows client
When you place a customized version of the msiexec command (which
calls the Microsoft Software Installer) in a script or batch file, you can
perform installations on multiple Windows systems. The following
example is a sample command to install the backup-archive command-line
Chapter 1. Installing the IBM Spectrum Protect backup-archive clients
15
client, client GUI, web client, API, and Administrative command-line client.
You might need to customize this example to run correctly on your system.
Although the command is physically spread across multiple lines in the
following example, enter it on a single command line.
msiexec /i "Z:\tsm_images\TSMClient\IBM Tivoli Storage Manager
Client.msi" RebootYesNo="No" REBOOT="Suppress" ALLUSERS=1
INSTALLDIR="C:\Program Files\Tivoli\Tsm"
ADDLOCAL="BackupArchiveGUI,BackupArchiveWeb,Api64Runtime,
AdministrativeCmd" TRANSFORMS=1033.mst /qn /l*v "C:\log.txt"
The descriptions of the silent installation parameters are as follows:
msiexec
Starts the Microsoft Software Installer (MSI) program.
/i
Installs the specified source package (replace with /x to uninstall the
package).
"Z:\tsm_images\TSMClient\IBM Tivoli Storage Manager Client.msi"
Specifies the complete path to the source package. The Z drive is shown in
this example. Specify the drive letter for the disk drive, in your
configuration, that contains the installation image.
RebootYesNo="No" REBOOT="Suppress"
Under certain conditions, a system reboot might be necessary for the
installation to complete successfully. This option causes the installation
program to not reboot the system if circumstances would otherwise cause
the reboot to occur. While this option is convenient, use it with caution
because suppressing the reboot might cause the program to behave in an
unpredictable manner. The most common reason that a reboot is required
is if the installation was an upgrade to an existing backup-archive client,
and the installation was performed while the client programs were
running. Therefore, shut down all backup-archive client programs and
services before you begin the installation.
ALLUSERS=1
Specifies that the package is for all users. This option is required.
INSTALLDIR="C:\Program Files\Tivoli\TSM"
Specifies the destination path. If you already installed this product or a
previous version of this product on your workstation, use the current
installation directory as the destination path for this package.
ADDLOCAL="BackupArchiveGUI,BackupArchiveWeb,Api64Runtime"
Specifies the features to install. Specify all the components on a single line
within quotation marks, separated by commas, with no spaces before or
after the commas. The installable client features are shown in the following
table:
16
Windows client features
Feature description
BackupArchiveGUI
Graphical user interface
BackupArchiveWeb
Backup-archive web client
Api64Runtime
API Runtime
ApiSdk
API SDK
AdministrativeCmd
Administrative Command Line
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
TRANSFORMS=1033.mst
Specifies which language transform to use. The following language
transforms are available:
Transform
Language
1028.mst
CHT Traditional Chinese
1029.mst
CSY Czech
1031.mst
DEU German
1033.mst
ENG English
1034.mst
ESP Spanish
1036.mst
FRA French
1038.mst
HUN Hungarian
1040.mst
ITA Italian
1041.mst
JPN Japanese
1042.mst
KOR Korean
1045.mst
PLK Polish
1046.mst
PTB Portuguese
1049.mst
RUS Russian
2052.mst
CHS Simplified Chinese
/qn
Specifies to install the product silently.
/l*v "C:\log.txt"
Specifies verbose logging and the name and location of the log file.
The installation process creates the IBM Spectrum Protect folder in the programs
folder of the Windows Start menu. You can start the backup-archive client by
clicking one of the icons in this folder.
Related concepts:
“Troubleshooting problems during installation” on page 19
Modifying, repairing, or uninstalling the Windows client
You can modify, repair, or uninstall an existing Windows client.
About this task
Use the Windows control panel to modify, repair, or uninstall the Windows client.
Procedure
1. Click Start > Control Panel > Uninstall a program.
2. Select IBM Spectrum Protect Client in the list of installed programs.
3. Select the function that you want to perform: Repair, Change, or Uninstall.
Chapter 1. Installing the IBM Spectrum Protect backup-archive clients
17
Option
Description
Repair
Wait for any in-progress backup-archive client tasks to completed before you
repair the Windows client.
This option repairs an existing Windows client installation. If you select
Repair, the files installed by the installation program are examined to
determine whether they have somehow become corrupted. If a file is
determined to be corrupted, the repair option attempts to replace it from the
saved installation image. The repair option also repairs missing program
short cuts and icons, missing files, and registry keys.
Change
Wait for any in-progress backup-archive client tasks to completed before you
modify the Windows client.
This option modifies an existing installation. If you select Change, the next
screen that is displayed shows Modify as the option for changing installed
programs. If you already installed the client and you need to add or remove
components, click Change, and select Modify. Choose the icon next to the
feature that you want to install or remove and select the appropriate action
from the drop-down list. For example, if you selected a typical installation
when you installed the client, the administrative client command line
interface files are not installed. If you decide that a node needs this
interface, select the icon next to Administrative Client Command Line Files
and click the This feature will be installed on local hard drive option.
Note: This option achieves the same effect as upgrading the client. The
difference is that you bypass the initial steps and the installation process
begins with the last installation type that you selected. If you want to
change the installation type, you can click Back, and select the new
installation type; then complete the information as you are prompted for it.
Use the information that is provided in “Upgrading the Windows client” on
page 11 (start at step 7 on page 12) if you have questions about a prompt.
18
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Option
Description
Uninstall
Wait for any in-progress backup-archive client tasks to completed before you
uninstall the Windows client.
This option uninstalls the Windows client program. It does not remove any
client services. It also does not remove log files, or other items that were
created when you configured or used the client. Most of these artifacts
remain in the installation directory (Program Files\Tivoli\TSM directory),
but they can exist anywhere on the disk, depending on what you chose for
the installation directory and other options. This option also does not
remove files that were copied to the local disk if you extracted the
installation files from a compressed distribution file.
Leaving these artifacts on disk is not a problem if you want to reinstall the
client in the future. However, if you want to more thoroughly remove the
client and related files and settings, see the wiki article How to completely
remove the Backup-Archive client from Microsoft Windows.
The installation program stops any client services that are running before it
uninstalls the software. If you want to stop the services yourself, type the
following commands at a command prompt window:
net stop "tsm journal service"
net stop "tsm client acceptor"
net stop "tsm client scheduler"
net stop "tsm remote client agent"
You can also use the Control Panel to stop these services. Their display
names match the name used on the command line.
Note: The service names shown here are the default names that are set by
the installation program. You can change some of these service names when
you configure the services using one of the configuration wizards on the
Utilities > Setup Wizard menus. If you change the service name, record the
name that you specify and use that name to stop the services.
If you want to remove any of these services without uninstalling the client,
perform the following steps:
1. Click Start > All Programs > IBM Spectrum Protect > Backup-Archive
GUI.
2. Click Utilities > Setup Wizard.
3. Select and run the wizard for each service that you want to remove. The
setup wizard options can also remove the configuration information for
online image support and open file support.
Troubleshooting problems during installation
If you are upgrading from a previous version of the backup-archive client and
there are client services running (for example, Client Acceptor or Scheduler), you
might see an error during the installation.
If there are other IBM Spectrum Protect client services running on any account (for
example, Client Acceptor or Scheduler), you might see a request to reboot the
system during installation. You must stop all instances of the IBM Spectrum
Protect client on all accounts before starting the installation.
You might see the following error during installation:
Error 1303. The installer has insufficient privileges to access this directory:
(Install Drive):\Program Files\Tivoli\TSM\baclient\plugins. The installation
cannot continue. Log on as an administrator or contact your system administrator.
Chapter 1. Installing the IBM Spectrum Protect backup-archive clients
19
When this error occurs, you must stop the installation. After stopping the
installation process, the previous version is no longer installed. Stop the client
services and retry the installation process.
Software updates
Software updates might periodically be made available by IBM for download.
For the latest information, updates, and maintenance fixes, see the IBM Support
Portal for IBM Spectrum Protect.
Installing the client management service to collect diagnostic
information
You can install IBM Spectrum Protect client management services to collect
diagnostic information about the backup-archive client. The client management
service makes the information available to the IBM Spectrum Protect Operations
Center for basic monitoring capability.
About this task
After you install the backup-archive client, install the client management service on
the same computer so that the IBM Spectrum Protect server administrator can view
diagnostic information from the Operations Center.
For installation instructions and more information about the client management
service, see Collecting diagnostic information with IBM Spectrum Protect client
management services.
20
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chapter 2. Configure the IBM Spectrum Protect client
After installing the backup-archive client, you must configure it before performing
any operations.
If you are upgrading the backup-archive client, it is unnecessary to reconfigure the
scheduler, web client, or other configuration settings. If the dsm.opt file used by
the previous client installation is available in the default installation directory or
the directory or file pointed to by the DSM_CONFIG and DSM_DIR environment
variables, the client accesses this file for configuration information.
Some configuration tasks are required, while other tasks are optional. The
following configuration tasks are required:
v “Creating and modifying the client options file” on page 23
v “Register your workstation with a server” on page 87
The following configuration tasks are optional:
v “Create a shared directory options file” on page 25
v “Creating multiple client options files” on page 25
v “Environment variables” on page 26
v “Configuring the language for displaying the Java GUI” on page 27
v “Configuring the web client on Windows systems” on page 28
v “Configuring the scheduler” on page 30
v “Configuring the journal engine service” on page 41
v “Configuring online-image backup support” on page 78
v “Configuring Open File Support” on page 78
v “Creating an include-exclude list” on page 88
v Configuring parallel backups of VMware virtual machines. See “Parallel backups
of virtual machines” on page 173
Client options file overview
You set (specify) client options and values in a client options file. Client options
can also be set on the server in a client option set. Client options that are set on the
server in a client option set override client options that are set in the client options
file.
On Windows systems, the default client options file is named dsm.opt.
You can create multiple client options files. If your client options file is not named
dsm.opt, or if dsm.opt is not in the default directory, use the OPTFILE client option
to tell the backup-archive client which file to read the options and parameters from
when the backup-archive client is started.
You can use a text editor application to directly edit the client options file. You can
also set options by using the backup-archive client GUI. In the GUI, select Edit >
Preferences and use the Preferences Editor to set client options. Options that you
set in the Preferences Editor are stored in the client options file. Not all client
options can be set by using the Preferences Editor.
© Copyright IBM Corp. 1993, 2017
21
You can use the query options command to display all or part of your options and
their current settings. This command accepts an argument to specify a subset of
options. The default is to display all options.
Some options consist of only the option name, such as verbose and quiet. You can
enter the entire option name, or its abbreviation. For example, you can specify the
verbose option in either of the following ways:
verbose
ve
Follow these rules when you add options to your options files:
v You can annotate option settings by adding comments to the options file. Begin
each comment with an asterisk (*) as the first character on the line.
v Do not specify options on a line that contains a comment.
v You can optionally indent options with spaces or tabs, to make it easier to view
the options and values that you specify in the file.
v Enter each option on a separate line and enter all parameters for an option on
the same line, as shown in the following examples:
domain="c: d:"
domain="ALL-LOCAL -c: -systemstate"
v To set an option in this file, enter the option name and one or more blank
spaces, followed by the option value.
v Enter one or more blank spaces between parameters.
v The lengths of file and path names in the client options files cannot exceed the
following limits:
– On Windows, a file name cannot exceed 255 bytes. Directory names,
including the directory delimiter, are also limited to 255 bytes. The maximum
combined length for a file name and path name is 5192 bytes. The Unicode
representation of a character can occupy several bytes, so the maximum
number of characters that a file name might contain can vary.
File path and file name limits are shown in Table 4.
– For archive or retrieve operations, the maximum length that you can specify
for a path and file name, combined, is 1024 bytes.
Table 4. File path and name limits
MBCS encoding
Path name length limits
File name length limits
1
5192 bytes
255 bytes
2
4092 bytes
127 bytes
3
2728 bytes
85 bytes
In the table, MBCS encoding has these meanings:
Basic Latin
Standard US English characters, numbers, symbols, and control characters
that are traditionally represented in 7-bit ASCII have a 1:1 ratio of bytes to
characters.
Latin extensions
Latin characters that have tildes, grave or acute accents, and so on, as well
as Greek, Coptic, Cyrillic, Armenian, Hebrew, and Arabic characters,
typically have a 2:1 ratio of bytes to characters.
22
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chinese, Japanese, Korean, Vietnamese
These characters and other East Asian language characters typically have a
3:1 ratio of bytes to characters.
If you update the client options file while a session is active, you must restart the
session to pick up the changes. If you use the client GUI setup wizard to make
changes, the changes are effective immediately. If you are not using the client
acceptor to manage the scheduler, you must also restart the scheduler.
Related reference:
“Optfile” on page 474
“Query Options” on page 723
Creating and modifying the client options file
The client options file is an editable text file that contains configuration
information for the backup-archive client.
About this task
The first time that you start the Windows backup-archive client GUI, the
installation program searches for an existing client options file, called dsm.opt. If
this file is not detected, a client options file configuration wizard starts and
prompts you to specify initial client configuration settings. When the wizard
completes, it saves the information that you specified in the dsm.opt file. By
default, the dsm.opt file is saved to C:\Program Files\Tivoli\TSM\baclient.
The options file must contain the following information to communicate with the
server:
v The host name or IP address of the IBM Spectrum Protect server.
v The port number that the server listens on for client communications. A default
port number is configured by the client options file configuration wizard. You
do not need to override this default port number unless your server is
configured to listen on a different port.
v Your client node name. The node name is a name that uniquely identifies your
client node. The node name defaults to the short host name of the computer that
the client is installed on.
Additional client options can be specified, as needed.
Note: Client options can also be set on the server in a client option set. Client
options that are defined on the server in a client option set override client options
that are set in the client options file.
A sample options file is copied to your disk when you install the backup-archive
client. The file is called dsm.smp. By default, the dsm.smp file is copied to
C:\Program Files\Tivoli\TSM\config\. You can view the contents of this file to see
examples of different options and how they are specified. The file also contains
comments that explain syntax conventions for include lists, exclude lists, and
wildcard use. You can also use this file as a template for your client options file by
editing it and saving it as dsm.opt in the C:\Program Files\Tivoli\TSM\baclient
directory.
After the initial client options file is created, you can modify the client options by
adding or changing the options as needed. You can modify the dsm.opt file in any
of the following ways:
Chapter 2. Configure the IBM Spectrum Protect client
23
v By running the client options file configuration setup wizard
v By using the client preferences editor
v By editing the dsm.opt file with a text editor program, such as Notepad
Perform the following steps to modify the client options:
Procedure
1. Select a method to modify the file.
Option
Description
Setup wizard
1. Click Start > All Programs > IBM
Spectrum Protect > Backup-Archive
GUI.
2. Select Utilities > Setup Wizard > Help
me configure the Client Options File.
On-screen text and online help is
available to provide guidance as you
navigate through the wizard panels. This
client options file configuration wizard
offers limited choices and configures
only the most basic options.
Preferences editor
1. Click Start > All Programs > IBM
Spectrum Protect > Backup-Archive
GUI.
2. Select Edit > Client Preferences. Select
the tabs in the preferences editor to set
client options. Specify the options in the
dialog boxes, drop down lists, and other
controls. Online help is provided. Click
the question mark (?) icon to display the
help topics for the online help for the tab
that you are editing. You can set more
options in the preferences editor than
you can set in the setup wizard.
Edit the dsm.opt file
1. Edit the dsm.opt file by using a plain text
editor. Each of the options is described in
detail in the documentation in “Client
options reference” on page 317. This
method is the most versatile way to set
client options because not all options can
be set in the client options file
configuration wizard or in the
preferences editor.
2. To comment out a setting, insert an
asterisk (*) as the first character on the
line that you want to comment out.
Remove the asterisk to make the
commented option active.
2. Save the changes.
a. Changes made in the client options file configuration wizard and in the
preferences editor are saved and recognized by the client when the wizard
completes, or when you exit the preferences editor.
b. If you edit the client options file with a text editor while the client is
running, you must save the file and restart the client so the changes are
detected.
24
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Related concepts:
“Client options reference” on page 317
“Communication options” on page 292
Chapter 11, “Processing options,” on page 291
“Register your workstation with a server” on page 87
Related reference:
“Passwordaccess” on page 476
Create a shared directory options file
The IBM Spectrum Protect server administrator can generate client options files in
a shared directory.
Windows clients can access the shared directory, and use the files there to create
their own client options file.
Creating a shared directory options file is an optional root user or authorized user
task.
Creating multiple client options files
You can create multiple client options files if you must work with multiple servers,
or find that you need multiple sets of parameters to do back up or archive tasks.
About this task
Suppose you want to back up your files to one server (server a), and archive files
to another (server b). Instead of editing the dsm.opt file each time you want to
connect to a different server, create two options files. For example, create the
options files a.opt for server a, and b.opt for server b.
Procedure
Use one of the following methods to specify or use a different client options file:
v Replace the dsm.opt file with the appropriate options file before you start the
backup-archive client.
For example, issue the following commands to copy the a.opt file to dsm.opt
and then start the backup-archive client GUI:
copy a.opt dsm.opt
dsm
v Start the backup-archive client from the command line and use the optfile
option to specify the options file that you want to use.
For example:
dsm -optfile=b.opt
v Define the DSM_CONFIG environment variable to specify the options file to use
before you start a backup-archive client session.
For example:
SET DSM_CONFIG=C:\Program Files\Tivoli\TSM\baclient\b.opt
What to do next
If you are running the backup-achive client from the command line, the DSM_DIR
and DSM_LOG environment variables might also need to be configured as follows:
Chapter 2. Configure the IBM Spectrum Protect client
25
v Define the DSM_DIR environment variable to point to the directory where all
other executable files reside:
SET DSM_DIR=C:\Program Files\Tivoli\TSM\baclient
v Define the DSM_LOG environment variable to point to the directory where
dsmerror.log resides:
SET DSM_LOG=C:\Program Files\Tivoli\TSM\baclient
Note: The directory path where the client executable files are located must be
included in the PATH environment variable or you must enter a fully qualified
path.
Environment variables
Generally, setting the environment variables is an optional task. Setting them
makes it more convenient for you to use the command line.
About this task
You must set the environment variables if you need to run in either of the
following environments:
v You want to invoke the backup-archive client from a directory other than the
directory where the backup-archive client is installed.
v You want to specify a different options file for the backup-archive client, the
administrative client, or both.
Note: You can also specify an alternate client options file for the command-line
client (not the administrative client) using the optfile option.
You need to set four environment variables:
PATH This is the default search path the operating system uses to locate
executable files. Set this to include the fully qualified paths of the client
installation directories.
DSM_CONFIG
Set this environment variable to the fully qualified path and file name of
the client options file.
DSM_DIR
Set this environment variable to the directory where the client message file
dsc*.txt is located.
DSM_LOG
Set this environment variable to the directory where the log files should
reside.
Ensure that the environment variables meet the following guidelines:
v Include the directory where the executable files (for example, dsm.exe) reside in
the current PATH environment variable. If you accepted the default installation
directory using the C: drive, you can set this from a command prompt by
typing:
SET PATH=C:\Program Files\Tivoli\TSM\baclient
v Specify the fully-qualified path name of your client options file (dsm.opt) using
the DSM_CONFIG environment variable:
SET DSM_CONFIG=C:\Program Files\Tivoli\TSM\baclient\dsm.opt
26
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
v Define the DSM_DIR environment variable to point to the directory where the
client message file dsc*.txt is located:
SET DSM_DIR=C:\Program Files\Tivoli\TSM\baclient
Related reference:
“Optfile” on page 474
Configuring the language for displaying the Java GUI
You can select the language to use for displaying the backup-archive client Java
GUI.
About this task
The language that is displayed by the backup-archive client Java GUI is defined by
the Windows display locale and not the Windows system locale. For example, if
the Windows system and input locale is French, but the display locale is Russian,
the language that is displayed by the Java GUI is Russian by default, if the
language option is not used.
If you want to display the Java GUI in US English or another language, you can
override the default display language by specifying the language option.
Tip: The language option does not affect the web client. The web client displays in
the language that is associated with the locale of the browser. If the browser is
running in a locale that client does not support, the web client is displayed in US
English.
Procedure
Use one of the following methods to configure the language for displaying the Java
GUI:
v Add the language language option to the client options file (dsm.opt). For
example, to set the display language to US English, add the following statement:
language enu
v Complete the following steps in the backup-archive client Java GUI:
1. In the main window of the Java GUI, click Edit > Client Preferences.
2. Click the Regional Settings tab.
3. Click the Language drop-down list and select a language.
4. Click OK.
Related reference:
“Language” on page 451
Web client configuration overview
The IBM Spectrum Protect web client provides remote management of a client
node from a web browser. The procedures to configure the web client vary
depending on which operating system is on the client node.
|
|
|
|
|
Beginning with IBM Spectrum Protect Version 8.1.2, you can no longer use the web
client to connect to the IBM Spectrum Protect V8.1.2 or later server. However, you
can still use the web client to connect to IBM Spectrum Protect V8.1.1, V8.1.0, or
V7.1.7 and earlier servers. For more information, see “Using the web client in the
new security environment” on page 117.
Chapter 2. Configure the IBM Spectrum Protect client
27
Backup-archive client options are used to configure web client settings. These
options include httpport, managedservices, webports, and revokeremoteaccess.
On Windows client nodes, a web client setup wizard is provided in the
backup-archive client GUI. You can use the setup wizard to configure the web
client. The options that you select in the wizard are copied to the client-user
options file (dsm.opt). You can also add the options directly to the dsm.opt file by
editing the file and adding the web client options to it.
To use the web client from the IBM Spectrum Protect Operations Center interface,
specify the web client address in the URL parameter of the REGISTER NODE or
UPDATE NODE command. The web address must include the DNS name or IP
address of the node, and the port number that the web client uses. For example,
http://node.example.com:1581. Replace this example host name with the IP
address or host name of your client node. When you access the web client by
using a web browser, enter the same URL syntax in the browser address bar.
All web client messages are written to the web client log file, which is named
dsmwebcl.log. By default, the dsmwebcl.log file and the backup-archive client error
log file (dsmerror.log) are created in the client installation directory. You can use
the DSM_LOG environment variable to override the default locations for the error
logs. If you do set the DSM_LOG environment variable, do not specify the root
directory as location for the error logs. You can also use the backup-archive client
errorlogname option, to change the location of the error log files. If you specify this
option, it overrides the DSM_LOG environment variable setting.
Related concepts:
“Web client options” on page 309
Related tasks:
“Configuring the web client on Windows systems”
Configuring the web client on Windows systems
On Windows systems, you can configure and start the web client by using a
wizard that is available in the backup-archive client GUI, or by using both IBM
Spectrum Protect and Windows commands.
Procedure
Choose one of the following methods to configure the Windows web client:
Setup method
Procedure
Setup wizard
1. Start the backup-archive client GUI.
2. Click Utilities > Setup Wizard.
3. Select the Help me configure the Web Client check
box.
4. Click NEXT and follow the wizard instructions to
configure the web client options.
28
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Setup method
Procedure
Command prompt
1. Set the following options in the dsm.opt file:
managedservices webclient schedule and
passwordaccess generate.
2. Install the client acceptor service by entering the
following command:
dsmcutil install cad /name:"TSM CAD" /node:nodename
/password:password /autostart:yes
where:
TSM CAD a name for the service. The default name is
TSM Client Acceptor.
nodename is the name of the client node.
password is the IBM Spectrum Protect password.
/autostart:yes indicates that the client acceptor service
is started when the operating system starts.
Start the service by using the Windows net start
command.
3. Install the IBM Spectrum Protect remote-client-agent
service by entering the following command:
dsmcutil install remoteagent /name:"TSM
AGENT" /node:nodename /password:password
/partnername:"TSM CAD"
where:
v TSM AGENT is a name for the remote-client-agent
service. The default service name is TSM Remote
Client Agent.
v nodename is the name of the client node.
v password is the IBM Spectrum Protect password.
v TSM CAD is the service-partner name. This name
must match the service name that you specified when
you installed the client acceptor service. The default
name is TSM Client Acceptor.
Do not start the TSM Remote Client Agent service from
the Control Panel > Administrative Tools > Services
view, or by using the net start command. The client
acceptor service starts the remote client agent when it is
needed.
What to do next
After you configure the web client, you can use the IBM Spectrum Protect
Operations Center or a browser to backup or restore, or archive or retrieve, data on
a node.
Related concepts:
“Scheduling options” on page 305
“Web client options” on page 309
Related tasks:
“Starting a web client session” on page 117
Related reference:
“Httpport” on page 419
“Passwordaccess” on page 476
Chapter 2. Configure the IBM Spectrum Protect client
29
Configuring the scheduler
Your IBM Spectrum Protect administrator can schedule the client to perform tasks
automatically. For scheduled events to occur on the client, you must configure the
client scheduler to communicate with the IBM Spectrum Protect server.
About this task
For example, you can automatically back up files at the end of each day or archive
some of your files every Friday. This procedure, which is known as central
scheduling, is a cooperative effort between the server and your client node. Your
administrator associates clients with one or more schedules that are part of the
policy domain that is maintained in the server database. The IBM Spectrum Protect
administrator defines central scheduling on the server and you start the client
scheduler on your workstation. After you start the client scheduler, no further
intervention is required.
With client scheduling, you can perform the following tasks:
v Display information about available schedules.
v Display information about work that the schedule completed.
v Modify scheduling options in the client options file (dsm.opt).
The most effective way to manage the client scheduler is to use the client acceptor
service. You can read about a comparison between using the client acceptor and
traditional scheduler services to manage the scheduler. You can also learn how to
configure the client to use the client acceptor to manage the scheduler.
Comparison between client acceptor-managed services and
traditional scheduler services
You can use either the client acceptor service or the traditional scheduler service to
manage the IBM Spectrum Protect scheduler. A comparison of these methods is
provided.
The following table shows the differences between the client acceptor-managed
services and the default traditional scheduler services methods.
Table 5. Client acceptor-managed services versus traditional scheduler services
Client acceptor-managed services
Defined by using the managedservices
schedule option and started with client
acceptor services.
IBM Spectrum Protect traditional scheduler
services
Started with command dsmc sched
command.
The client acceptor service is started as a
Windows service
30
The client acceptor service starts and stops
the scheduler process as needed for each
scheduled action.
Remains active, even after scheduled backup
is complete.
Requires fewer system resources when idle.
Requires higher use of system resources
when idle.
Client options and IBM Spectrum Protect
server override options are refreshed each
time the client acceptor services start a
scheduled backup.
Client options and IBM Spectrum Protect
server override options are only processed
after dsmc sched is started.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 5. Client acceptor-managed services versus traditional scheduler services (continued)
IBM Spectrum Protect traditional scheduler
services
Client acceptor-managed services
Cannot be used with
SESSIONINITiation=SERVEROnly backups.
You must restart the scheduler process for
updated client options to take effect.
Important: If you run the client scheduler
on the command line, the scheduler does not
run as a background service.
Tip: Restart the traditional scheduler
periodically to free system resources
previously used by system calls.
Configuring the client to use the client acceptor service to
manage the scheduler
One of the most effective ways of managing the client scheduler is to use the client
acceptor. You must configure the client to use the client acceptor to manage the
scheduler.
Before you begin
v If you include files for encryption, ensure that the encryptkey option is set to
save in the options file. This option is set by selecting Save Encryption Key
Password Locally on the Authorization tab in the preference editor. Setting this
option enables unattended scheduled services. If the encryption key was not
previously saved, you must run an attended backup of at least one file so that
you get the encryption prompt to save the key.
v You cannot use the client acceptor for scheduling when the sessioninitiation
option is set to serveronly.
About this task
The client acceptor serves as an external timer for the scheduler. When the
scheduler is started, it queries the server for the next scheduled event. The event is
either run immediately or the scheduler exits. The client acceptor restarts the
scheduler when it is time to run the scheduled event. This action reduces the
number of background processes on your workstation and resolves memory
retention problems that can occur when the scheduler is run without client
acceptor management.
The client acceptor service is also known as the client acceptor daemon.
Procedure
Complete the following steps to use the client acceptor to manage the scheduler on
the Windows client:
1. In the backup-archive client GUI, click Utilities > Setup Wizard > Help me
configure the Client Scheduler and click Next.
2. Read the information in the Scheduler Wizard page and click Next.
3. In the Scheduler Task page, select Install a new or additional scheduler and
click Next.
4. In the Scheduler Name and Location page, specify a name for the client
acceptor service that you want to manage the scheduler. Then, select Use the
client acceptor to manage the scheduler and click Next.
Chapter 2. Configure the IBM Spectrum Protect client
31
5. If the client acceptor is already installed for use by the web client, select that
name of the client acceptor from the drop-down list in the Web Service Name
page. Otherwise, type the name that you want to assign to this client acceptor.
The default name is TSM Client Acceptor. Click Next.
6. Follow the instructions on the remaining screens to complete the configuration.
Use the following information to help you complete the wizard pages:
v If the sessioninitiation option is set to serveronly in the client options file
(dsm.opt), the client configuration wizard and scheduler service might be
unable to initiate authentication with the IBM Spectrum Protect server. To
avoid this problem, ensure that the Contact the IBM Spectrum Protect
Server to validate password check box on the IBM Spectrum Protect
Authentication page is cleared.
v For the client acceptor-managed scheduler, select Manually when I explicitly
start the service in the Service login options page.
7. Start the client acceptor service from the Services Control Panel, but do not
start the scheduler service. The scheduler service is started and stopped
automatically by the client acceptor service as needed.
Tip:
v You can also use the managedservices option in the client options file (dsm.opt)
to specify whether the client acceptor manages the scheduler.
v If you need the client acceptor to manage the scheduler in polling mode without
opening a listening port, use the cadlistenonport option in the dsm.opt file.
v If you do not use the client acceptor to manage the scheduler, select
Automatically when Windows boots in the Service login options window. This
setting starts the service automatically when Windows starts so that your
schedules are run automatically. Alternatively, you can use the Services Control
Panel or the net start command to start the Scheduler service.
v You can also use the Scheduler Service Configuration utility (dsmcutil.exe) to
configure the scheduler. The Scheduler Service Configuration utility must be run
from an account that belongs to the Administrator/Domain Administrator
group. You can start multiple client scheduler services on your system.
Related concepts:
“Web client configuration overview” on page 27
“Enable or disable scheduled commands” on page 254
“Scheduling options” on page 305
Related tasks:
“Setting the client scheduler process to run as a background task and start
automatically at startup” on page 246
Related reference:
“Cadlistenonport” on page 334
“Managedservices” on page 454
“Sessioninitiation” on page 520
Starting the client scheduler
To start the client scheduler, use the Services Control Panel or the net start
command.
32
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
About this task
To avoid problems, do not run the client scheduler on the command line. The
command line does not run the scheduler as a background service.
When you start the client scheduler, it runs continuously until you close the
window, shut down your system, or log out of your system. If you are running the
Scheduler Service, the scheduler runs until the system is shutdown or you
explicitly stop it using the services control panel.
Related concepts:
Chapter 11, “Processing options,” on page 291
Scheduling events using the GUI
This task guides you through the steps to schedule events using the GUI.
Procedure
1. From the backup-archive client GUI main window, click Utilities > Setup
Wizard. The Client Configuration Assistant appears.
2. Select the Help me configure the Client Scheduler and click the OK button.
The Scheduler Wizard panel appears.
3. Select the task that you want to perform. You can install a new client scheduler,
update the settings for a scheduler, or remove a scheduler.
4. Complete each panel and click the right arrow to continue. To go back to a
previous panel, click the left arrow.
What to do next
You can run scheduling services by using the command-line client.
|
|
Configuring IBM Spectrum Protect client/server communication across
a firewall
|
|
In most cases, the IBM Spectrum Protect server and clients can work across a
firewall.
|
About this task
|
|
Every firewall is different, so the firewall administrator might need to consult the
instructions for the firewall software or hardware in use.
|
There are two methods for enabling client and server operations through a firewall:
|
|
|
|
Method 1:
To allow clients to communicate with a server across a firewall, the
following ports must be opened in the firewall by the firewall
administrator:
|
|
|
|
|
|
|
TCP/IP port
To enable the backup-archive client, command-line admin client,
and the scheduler to run outside a firewall, the port specified by
the server option tcpport (default 1500) must be opened by the
firewall administrator. This port is set on the client and the server
using the tcpport option. The setting must be the same on the
client and server. This allows IBM Spectrum Protect scheduler
Chapter 2. Configure the IBM Spectrum Protect client
33
|
|
|
communications in both polling and prompted mode, client
acceptor-managed schedulers, and regular backup-archive client
operations.
|
|
|
Note: The client cannot use the port specified by the tcpadminport
option (on the server) for a client session. That port can be used for
administrative sessions only.
|
|
|
|
|
|
HTTP port
To allow the web client to communicate with remote workstations
across a firewall, the HTTP port for the remote workstation must
be opened. Use the httpport option in the remote workstation
client options file to specify this port. The default HTTP port is
1581.
|
|
|
|
|
|
TCP/IP ports for the remote workstation
The two TCP/IP ports for the remote workstation client must be
opened. Use the webports option in the remote workstation client
options file to specify these ports. If you do not specify the values
for the webports option, the default zero (0) causes TCP/IP to
randomly assign two free port numbers.
|
|
|
|
TCP/IP port for administrative sessions
Specifies a separate TCP/IP port number on which the server is
waiting for requests for administrative client sessions, allowing
secure administrative sessions within a private network.
Method 2:
For the client scheduler in prompted mode, it is unnecessary to open any
ports on the firewall. If you set the sessioninitiation option to serveronly,
the client will not attempt to contact the server. All sessions are initiated by
server prompted scheduling on the port defined on the client with the
tcpclientport option. The sessioninitiation option only affects the behavior
of the client scheduler running in the prompted mode.
|
|
|
|
|
|
|
|
|
|
|
|
The IBM Spectrum Protect server must set the SESSIONINITiation
parameter on the register node and update node commands for each
node. If the server specifies SESSIONINITiation=clientorserver, the default,
the client can decide which method to use. If the server specifies
SESSIONINITiation=serveronly, all sessions are initiated by the server.
|
Note:
|
|
|
|
|
|
1. If sessioninitiation is set to serveronly, the value for the tcpclientaddress
client option must be the same as the value for the HLAddress option
of the update node or register node server command. The value for the
tcpclientport client option must be the same as the value for the
LLAddress option of the update node or register node server
command.
|
|
|
|
|
|
|
|
|
|
2. If you set the sessioninitiation option to serveronly, with the exception
of client acceptor-managed schedulers, the command-line client,
backup-archive client GUI, and web client GUI still attempts to initiate
sessions, but are blocked by the IBM Spectrum Protect server for nodes
that have the sessioninitiation option set to serveronly.
3. When installing the scheduler using the setup wizard or dsmcutil, and
the IBM Spectrum Protect server is behind a firewall, the node
password will not get stored on the client workstation. As a result, the
scheduler service might be unable to authenticate to the server when
the server contacts the client to run a schedule. In this case, you can
34
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
|
|
|
|
|
|
|
|
|
|
|
|
run the scheduler from the command line (dsmc schedule), wait until a
scheduled operation starts, and enter the password for your node when
prompted. After you enter the password for your node, restart the
scheduler service. You can also use the following dsmcutil command to
save the password:
|
|
|
|
|
A similar problem can occur if an encryption key is required for backup
operations. In this case, you can run the scheduler from the command
line (dsmc schedule), wait until a scheduled backup starts, and enter
the encryption key when prompted. After the password and encryption
key are updated, you must restart the scheduler.
dsmcutil updatepw /node:nnn /password:ppp /validate:no
If sessioninitiation option is set to serveronly in your client options file
(dsm.opt), the client setup wizard and scheduler service is unable to
initiate authentication with the IBM Spectrum Protect server. To avoid
this problem, when configuring the client scheduler using the setup
wizard, ensure that the Contact the IBM Spectrum Protect Server to
validate password check box on the IBM Spectrum Protect
Authentication page is unchecked.
|
|
|
|
|
|
|
|
|
4. When configuring the scheduler on a client workstation for the first
time, the scheduler service might be unable to authenticate to the
server when the server contacts the client scheduler to run a schedule.
This can happen when the passwordaccess is set to generate and the
IBM Spectrum Protect server is behind a firewall and the encrypted
password cannot be locally stored before the scheduler is started. To
correct this problem, you need to run the scheduler from the command
line (dsmc schedule), wait until a scheduled operation starts, and enter
the password for your node when prompted.
|
|
|
|
|
|
|
5. The client cannot prompt for the encryption key password in scheduler
mode. If you are using IBM Spectrum Protect data encryption, you
must run an initial interactive backup once to set up the encryption key
by opening the TCP/IP connection from the client workstation to the
server workstation. See Method 1 for more information about setting
up this communication. After the encryption key is set, you can use
server-initiated sessions to back up the files using encryption.
|
|
|
|
If you set the sessioninitiation option to client, the client initiates sessions
with the server (Method 1) by communicating on the TCP/IP port defined
with the server option tcpport. This is the default. Server prompted
scheduling can be used to prompt the client to connect to the server.
|
|
|
|
|
|
|
|
|
|
When using IBM Spectrum Protect across a firewall in prompted mode, the IBM
Spectrum Protect server needs to contact the client. In order to complete this
action, some software might need to be installed on the IBM Spectrum Protect
server to route the request through the firewall. This software routes the server
request through a socks port on the firewall. This method is typically called
socksifying a system. Proxies are not supported, because they only route a few types
of communication protocols (HTTP, FTP, GOPHER). IBM Spectrum Protect
communications are not routed by proxies. It is important to note that the client
creates a new connection to the IBM Spectrum Protect server when prompted. This
means that the firewall configuration discussed above must be in place.
|
Related tasks:
|
“Configuring the scheduler” on page 30
|
Related reference:
|
“Sessioninitiation” on page 520
Chapter 2. Configure the IBM Spectrum Protect client
35
|
|
“Tcpadminport” on page 553
“Tcpport” on page 558
|
“Webports” on page 631
|
|
Configuring IBM Spectrum Protect client/server communication with
Secure Sockets Layer
|
|
Secure Sockets Layer (SSL) allows industry standard SSL-based secure
communications between the IBM Spectrum Protect client and server.
|
About this task
|
The following client components support SSL:
|
v Command-line client
|
v Administrative command-line client
|
v Client GUI
|
v Client API
|
|
|
|
|
|
Only outgoing client/server connections support SSL. A V8.1.2 client
communicating with a down-level servers supports SSL. A V8.1.2 client
communicating with a V8.1.2 server must use SSL. Incoming connections (for
example, client acceptor, server-initiated schedule connections) do not support SSL.
Client-to-client communications do support SSL. Web GUI does not support SSL.
The Web GUI is no longer supported when communicating with a V8.1.2 server.
|
|
Each IBM Spectrum Protect server that is enabled for SSL must have a unique
certificate. The certificate can be one of the following types:
|
v A certificate that is self-signed by IBM Spectrum Protect.
|
|
|
v A certificate that is issued by a certificate authority (CA). The CA can be from a
company such as VeriSign or Thawte, or an internal CA, maintained within your
company.
|
Follow these steps to enable SSL communication with a self-signed certificate:
|
|
|
|
1. Obtain the IBM Spectrum Protect server self-signed certificate (cert256.arm)
Use the cert.arm certificate file when the server is not setup to use Transport
Layer Security (TLS) 1.2; otherwise, use the cert256.arm file. The client
certificate file must be the same as the certificate file that the server uses.
|
|
2. Configure the clients. To use SSL, each client must import the self-signed server
certificate.
Use the dsmcert utility to import the certificate.
|
|
|
|
3. For a disaster recovery of the IBM Spectrum Protect server, if the certificate has
been lost, a new one is automatically generated by the server. Each client must
obtain and import the new certificate.
|
|
|
|
For fast path details for communication between a V8.1.2 client and a V8.1.2 server,
you can use the SSLACCEPTCERTFROMSERV option to automatically accept a
self-signed certificate. See “Default security settings for the client (fast path)” on
page 101 for details.
|
Follow these steps to enable SSL communication with a CA-signed certificate:
|
1. Obtain the CA root certificate.
36
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
|
|
2. Configure the clients. To use SSL, each client must import the self-signed server
certificate.
Use the dsmcert utility to import the certificate.
|
|
|
|
|
|
|
Tip: After you complete this step, if the server gets a new certificate that is
signed by the same CA, the client does not need to import the root certificate
again.
3. If you are recovering the backup-archive client as part of disaster recovery, you
must install the SSL certificate on the server again. If the certificate was lost,
you must get a new one. You do not need to reconfigure the client if the new
certificate has been signed by a CA.
|
|
The dsmcert utility is provided by the backup-archive client and automatically
installs it in C:\Program Files\Tivoli\TSM\baclient.
|
Before you set up the server certificate on the client, follow these steps:
|
|
|
|
|
|
|
|
1. Open a command prompt and change the directory to the backup-archive client
directory, for example: cd "C:\Program Files\Tivoli\TSM\baclient"
2. Append the GSKit binary path and library path to the PATH environment
variable, for example:
|
Next, you must import the server certificate, or the CA root certificate.
|
|
|
|
|
|
|
|
|
|
|
|
If you use a self-signed certificate
Each IBM Spectrum Protect server generates its own certificate. The
certificate has a fixed file name of either cert.arm or cert256.arm. The
certificate file is stored on the server workstation in the server instance
directory, for example, C:\Program Files\tivoli\tsm\server1\cert256.arm.
If the certificate file does not exist and you specify the SSLTCPPORT or
SSLTCPADMINPORT server option, the certificate file is created when you
restart the server with these options set. IBM Spectrum Protect V6.3 servers
(and newer versions) generate files named cert256.arm and cert.arm. IBM
Spectrum Protect servers older than V6.3 generate only certificate files
named cert.arm. You must choose the certificate that is set as the default
on the server.
set PATH=C:\Program Files\Common Files\Tivoli\TSM\api64\gsk8\bin\;
C:\Program Files\Common Files\Tivoli\TSM\api64\gsk8\lib64;%PATH%
See Creating a symbolic link to access the latest GSKit library and IBM Global
Security Kit return codes for details on GSkit libraries.
|
Follow these steps to set up the SSL connection to a server:
|
1. Obtain the certificate from the server administrator.
|
|
|
2. Import the certificate into the client key database by using the
following command:
dsmcert -add -server <servername> -file <path_to_cert256.arm>
|
|
|
If you use a certificate from a certificate authority
If the certificate was issued by a certificate authority (CA) such as VeriSign
or Thawte, the client is ready for SSL and you can skip the following steps.
|
|
|
|
For the list of preinstalled root certificates from external certificate
authorities, see “Certificate Authorities root certificates” on page 40.
If the certificate was not issued by one of the well-known certificate
authorities, follow these steps:
|
1. Obtain the root certificate of the signing CA.
Chapter 2. Configure the IBM Spectrum Protect client
37
2. Import the certificate into the client key database by using the
following command:
|
|
|
dsmcert -add -server <servername> -file <path_to_cert256.arm>
|
|
|
|
Important:
1. A pseudo random password is used to encrypt the key database. The password
is automatically stored encrypted in the stash file (dsmcert.sth). The stash file
is used by the backup-archive client to retrieve the key database password.
|
|
|
2. More than one server certificate can be added to the client key database file so
that the client can connect to different servers. Also, more than one CA root
certificate can be added to the client key database.
|
|
3. If you do not run the preceding commands from the backup-archive client
directory, you must copy dsmcert.kdb and dsmcert.sth into that directory.
|
|
|
|
|
|
|
|
|
|
|
4. For performance reasons, use SSL only for sessions where it is needed. A V8.1.2
client communicating with a V8.1.2 server must use SSL. SSL No (the default
value) indicates that encryption is not used when data is transferred between
the client and a server earlier than V8.1.2. When the client connects to a V8.1.2
or later server, the default value No indicates that object data is not encrypted.
All other information is encrypted, when the client communicates with the
server. When the client connects to a V8.1.2 or later server, the value Yes
indicates that SSL is used to encrypt all information, including object data,
when the client communicates with the server. Consider adding more processor
resources on the IBM Spectrum Protect server system to manage the increased
requirements.
|
|
|
|
|
|
5. In order for a client to connect to a server that is using Transport Layer
Security (TLS) Version 1.2, the certificate's signature algorithm must be SHA-1
or stronger. If you are using a self-signed certificate, you must use the
cert256.arm certificate. Your IBM Spectrum Protect administrator might need to
change the default certificate on the IBM Spectrum Protect server. See the
SSLTLS12 server option topic for details.
|
|
|
|
|
|
|
Additional details for a V8.1.2 client communicating with a server V8.1.1 and
earlier V8 levels, and V7.1.7 and earlier levels.
After the server certificate is added to the client key database, add the SSL
Yes option to the client options file, and update the value of the TCPPORT
option. It is important to understand that the server is normally set up for
SSL connections on a different port. In other words, two ports are opened
on the server:
|
1. One port accepts regular non-SSL client connections
|
2. Another port accepts SSL connections only
|
|
You cannot connect to a non-SSL port with an SSL-enabled client, and vice
versa.
|
|
If the value of tcpport is incorrect, the client cannot connect to the server.
Specify the correct port number on the tcpport option.
|
|
|
|
|
To disable security protocols that are less secure than TLS 1.2, add the
SSLDISABLELEGACYtls yes option to the client options file, or within the
Java GUI select the Require TLS 1.2 or above checkbox on the
Communication tab of the Preferences editor. Requiring TLS 1.2 or above
helps prevent attacks by malicious programs.
|
Related reference:
|
“Ssl” on page 542
|
“Sslfipsmode” on page 545
38
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
Creating a symbolic link to access the latest GSKit library
|
|
You can create a symbolic link to point the directory where the older version of
GSKit is installed to the location of the latest GSKit libraries on the system.
|
About this task
|
|
|
|
When you install DB2 for Linux, UNIX, and Windows, on UNIX and Linux, local
GSKit libraries are also installed. Those libraries are stored in <db2_install_path>/
lib64/gskit_db2 or <db2_install_path>/lib32/gskit_db2. On Windows, the
default location is C:\Program Files\ibm\gsk8.
|
|
|
|
|
|
|
|
During the installation of other IBM products, such as IBM Spectrum Protect,
another copy of the GSKit libraries might be installed. Depending on the product,
these libraries might be either local GSKit libraries or global GSKit libraries. When
DB2 for Linux, UNIX, and Windows and another IBM product that includes GSKit
libraries are both installed on the same system, some interoperability issues might
arise. These interoperability issues might occur because GSKit allows only libraries
from a single GSKit source to exist in any single process. The interoperability
issues might lead to unpredictable behavior and runtime errors.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
To ensure that a single source of GSKit libraries is used, the symbolic link
approach can be used. During an initial DB2 for Linux, UNIX, and Windows
installation, the installer creates a symbolic link <db2_install_path>/lib64/gskit
or <db2_install_path>/lib32/gskit to <db2_install_path>/lib64/gskit_db2 or
<db2_install_path>/lib32/gskit_db2. These symbolic links are the default
locations from where GSKit libraries are loaded. Products that bundle DB2 for
Linux, UNIX, and Windows, and change the symbolic link from the default
directory to the library directory of another copy of GSKit must ensure that the
newly installed GSKit is at the same or a newer level. This restriction applies
whether the libraries are global or local. During an upgrade or update of DB2 for
Linux, UNIX, and Windows, the symbolic link is preserved. If the newly installed
copy has a symbolic link to the default location, the symbolic link that is associated
with the older installation copy is preserved. If the newly installed copy does not
have a symbolic link to the default location, the symbolic link that is associated
with the newer installation copy is preserved.
|
|
|
|
Some limitations exist since the symbolic link <db2_install_path>/lib64/gskit or
<db2_install_path>/lib32/gskit is in the path of the DB2 for Linux, UNIX, and
Windows installation copy. For example, if two or more instances are created for
any DB2 copy, the symbolic link changes affect all the instances.
|
|
|
|
|
You can also modify a Domino Server GSKit in a similar manner. A Domino server
does not have a GSKit folder, but it has folders C and N, and a library
libgsk8iccs_64.so. You can first create soft links for these folders, and files to
point to the corresponding folders on the GSKit package, where the IBM Spectrum
Protect backup-archive client V8.1.2 is installed, as follows:
|
v ln -s /usr/local/ibm/gsk8_64/lib64/C /opt/ibm/lotus/notes/90010/zlinux
|
v ln -s /usr/local/ibm/gsk8_64/lib64/N /opt/ibm/lotus/notes/90010/zlinux
|
|
v ln -s /usr/local/ibm/gsk8_64/lib64/libgsk8iccs_64.so /opt/ibm/lotus/
notes/90010/zlinux
|
|
|
Next, change the DPD node's password to domdsmc CHANGEADSMPwd
tvt1054_domnote2 tvt1054_domnote2 tvt1054_domnote2. Finally, run domdsmc query
adsm.
Chapter 2. Configure the IBM Spectrum Protect client
39
Procedure
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. Create a symbolic link on Windows, if you have administrator privileges.
Rename the DB2 GSKit copy of the lib64 directory that is located in the default
location, C:\Program Files\ibm\gsk8. Start a DOS shell, navigate to the DB2
GSKit location, and rename the directory as follows:
cd C:\Program Files\ibm\gsk8
rename lib64 lib64-db2
2. Create a symbolic link in the location of the DB2 GSKit copy and point to the
location of the TSM GSKit copy by running the following commands in the
DOS shell. Navigate to the location of the DB2 GSkit copy and then create the
symbolic link as follows:
cd C:\Program Files\ibm\gsk8
mklink /d lib64 "c:\Program Files\Common Files\Tivoli\TSM\api64\gsk8\lib64"
3. Restart DB2 for changes to take effect. On startup, DB2 loads GSKit from the
new location, which points to the IBM Spectrum Protect copy of GSKit. In the
DB2 command prompt, enter these commands as follows:
db2stop
db2start
Certificate Authorities root certificates
|
|
|
The backup-archive client includes a list of root certificates for a number of
common Certificate Authorities.
|
|
The following is a list of root certificates for a number of common Certificate
Authorities that are delivered with the client:
|
|
v Entrust.net Global Secure Server Certification Authority
v Entrust.net Global Client Certification Authority
|
v Entrust.net Client Certification Authority
|
v Entrust.net Certification Authority (2048)
|
v Entrust.net Secure Server Certification Authority
|
v VeriSign Class 3 Public Primary Certification Authority
|
v VeriSign Class 2 Public Primary Certification Authority
|
v VeriSign Class 1 Public Primary Certification Authority
|
v VeriSign Class 4 Public Primary Certification Authority - G2
|
v VeriSign Class 3 Public Primary Certification Authority - G2
|
v VeriSign Class 2 Public Primary Certification Authority - G2
|
v VeriSign Class 1 Public Primary Certification Authority - G2
|
v VeriSign Class 4 Public Primary Certification Authority - G3
|
v VeriSign Class 3 Public Primary Certification Authority - G3
|
|
v VeriSign Class 2 Public Primary Certification Authority - G3
v VeriSign Class 1 Public Primary Certification Authority - G3
|
v Thawte Personal Premium CA
|
v Thawte Personal Freemail CA
|
v Thawte Personal Basic CA
|
v Thawte Premium Server CA
|
v Thawte Server CA
|
v RSA Secure Server Certification Authority
40
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
|
|
To use certificates issued by any other Certificate Authority you must install the
root certificate of the Certificate Authority on all clients as part of the client
configuration.
Configure your system for journal-based backup
You must install and configure the journal daemon (Linux) or journal engine
service (Windows) before you can perform journal-based backups.
Configuring the journal engine service
Journal-based backup can be used for all Windows clients. If you install the journal
engine service and it is running, then by default the incremental command
automatically performs a journal-based backup on selected file systems that are
being monitored by the journal engine service.
About this task
Journal-based backup is enabled by installing and configuring the IBM Spectrum
Protect journal service. You can install the journal service with the GUI Setup
wizard or with the dsmcutil command. Basic journal service configuration can be
done with the GUI Setup wizard, more advanced configuration can be done by
editing the journal service configuration file, tsmjbbd.ini.
Tip: The default location for journal service configuration file is C:\Program
Files\Tivoli\TSM\baclient\tsmjbbd.ini. If this is the first time you are
configuring the journal engine service and a copy of tsmjbbd.ini does not already
exist, copy the sample file C:\Program Files\Tivoli\TSM\config\tsmjbbd.ini.smp
to C:\Program Files\Tivoli\TSM\baclient\tsmjbbd.ini.
To install and configure this service using the client Java GUI setup wizard,
perform the following steps:
Procedure
1. From the main window, open the Utilities menu and select Setup Wizard.
2. Select the Help me configure the Journal Engine check box.
3. Select the task you want to perform. You can install a new journal engine,
update a previously installed journal engine, or remove a previously installed
journal engine from your system.
4. Complete each panel in the wizard and click the Next button to continue. To
return to a previous panel, click the Back button. To display help information
for a panel, click the Help button.
Results
Journal service configuration settings are stored in the journal configuration file
tsmjbbd.ini. This file can be installed and configured with the GUI setup wizard
or be manually edited.
Follow these steps to set up multiple journal services:
1. Create and set up a separate journal configuration file (tsmjbbd.ini) for each
journal service to be installed. Each configuration file must specify a different
JournalPipe value, and must also specify different drives to journal, so that the
two services do not interfere with each other. Multiple journal services
journaling the same drive causes problems. The different services attempts to
Chapter 2. Configure the IBM Spectrum Protect client
41
write to the same journal database unless this is specifically overridden by
specifying different journal directories in the different configuration files.
2. Install the multiple journal services using the dsmcutil.exe tool. Use distinct
names for each service, and specify the /JBBCONFIGFILE option to identify the
tsmjbbd.ini to be used for that particular journal instance. For example:
dsmcutil install journal /name:"TSM Journal Service 1"
/JBBCONFIGFILE:c:\journalconfig\tsmjbbd1.ini
dsmcutil install journal /name:"TSM Journal Service 2"
/JBBCONFIGFILE:d:\journalconfig\tsmjbbd2.ini
Note: In Uniform Naming Convention (UNC) format, the jbbconfigfile path
must contain a drive letter. In the following UNC format example, the path
contains the drive letter D$: \\computer7\D$\journalconfig\tsmjbbd1.ini
3. Different backup clients (based on the distinct dsm.opt file used) can now
connect to the desired journal service by specifying the appropriate
JournalPipe option in the appropriate dsm.opt, which corresponds to the
JournalPipe journal service setting.
Note:
1. Each journal service instance is associated to only one backup-archive client
node name. Changing the association requires a restart of the journal service to
recognize the new association.
2. You cannot use network and removable file systems.
Configuration settings that you apply when the journal service is started and any
changes you make while the journal service is running are applied without having
to restart the service. This also applies to the journal exclude list. However, some
settings for journaled file systems do not take effect until the file system is brought
offline and then back online.
File systems can be taken online (added) or offline (removed) without stopping
and restarting the journal service. You can bring a file system offline by removing
it from the list of journaled file systems in the journal configuration file
tsmjbbd.ini, or by shutting down the journal service. You can bring a file system
back online by adding it to the list of journaled file systems in the journal
configuration file tsmjbbd.ini or by starting (restarting) the journal service.
Attention: If you take a file system offline without setting the PreserveDbOnExit
value of 1, the journaled file system journal database is deleted.
PreserveDbOnExit=1 specifies that the journaled file system journal database is not
deleted when the journal file system goes offline. The database is also valid when
the journal file system comes back online.
The following is the syntax for stanza and stanza settings:
Syntax for stanzas:
[StanzaName]
Syntax for stanza settings:
stanzaSetting=value
Note:
1. You can specify comments in the file by beginning the line with a semicolon.
2. Stanza and value names are not case sensitive.
42
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
3. Numeric values can be specified in hexadecimal by preceding the value with 0x
otherwise they are interpreted as decimal.
4. There is no correlation between these settings and any settings in the
backup-archive client options file. The journal service is a completely
independent process and does not process backup-archive client options.
Related concepts:
“Journal-based backup” on page 141
JournalSettings stanza (Windows)
Settings under this stanza are global and apply to the entire journal service.
The following is the syntax for the JournalSettings stanza:
Syntax for JournalSettings stanza:
[JournalSettings]
Syntax for stanza settings:
JournalSettings=value
You can specify the following JournalSettings values:
JournalPipe=pipename
Specifies the pipe name of the journal service session manager to which
backup clients initially connect, when establishing a journal-based backup
session. This setting is used in conjunction with the backup client option of
the same name. The default pipe name is \\.\pipe\jnlSessionMgr1. For
example, in dsm.opt:
JournalPipe \\.\pipe\jnlSessionMgr1
Under tsmjbbd.ini [JournalSettings] stanza:
JournalPipe=\\.\pipe\jnlSessionMgr1
Note: The same pipe name must be specified by the client using the
JournalPipe option.
NlsRepos
Specifies the National Language Support repository the journal service uses
for generating messages. Since the journal service is non-interactive, this
only applies to messages written to the journal error log. The default value
is dscameng.txt. For example:
NlsRepos=dscenu.txt
ErrorLog
Specifies the log file where detailed error messages generated by the
journal service are written. Note that less detailed error and informational
messages are written to the Windows application event log as well. The
default value is jbberror.log. For example:
ErrorLog=jbberror.log
In Uniform Naming Convention (UNC) format, the path must contain a
drive letter. In the following UNC format example, the path contains the
drive letter D$: \\computer7\D$\temp\jbberror.log.
JournalDir
Specifies the directory where journal database files are stored and written.
The default directory is the journal service installation directory. You can
specify different journal locations for each file system being journaled. This
is useful when running in a clustered environment because the location of
Chapter 2. Configure the IBM Spectrum Protect client
43
the journal must be accessible by each workstation in the cluster running
the journal service. Typically the journal for local resources being journaled
resides in the same location and the journal for shared cluster resources
(which can move from workstation to workstation) is located on the shared
resource to ensure that it is accessible to both workstations.
By default, this setting applies to all journaled file systems but can be
overridden by an override stanza for each journal file system. If the default
value is a fully qualified path (for example c:\tsmjournal), all journal
database files are written to the specified directory. If the default value
does not specify a drive letter, (for example \tsmjournal) the journal
database files for each journal file system are written to the specified
directory on each journal file system.
In Uniform Naming Convention (UNC) format, the path must contain a
drive letter. In the following UNC format example, the path contains the
drive letter D$: \\computer7\D$\temp\tsmjournal.
The following is an example configuration stanza:
[JournalSettings]
;
; Store all resources in one location unless overridden
; by an override stanza
;
JournalDir=c:\tsmjournal
;
;
[JournaledFileSystemSettings.D:\]
;
; Journal for d: only is in location specified below
;
JournalDir=d:\tsmjournal
Note: Changes to this setting do not take effect until the journaled file
systems are brought online.
JournalExcludeList stanza
This list of exclude statements filters changes from being recorded in the journal
database. Changes to objects which match statements in this stanza are ignored
and are not recorded in the journal database.
Note:
1. Excluding files from the journal has no bearing on those files being excluded
by the backup client, other than preventing the files from being sent to the
backup client to be processed during journal-based backup. A file that is not
excluded from the journal should still be excluded by the backup-archive client,
if there is a matching exclude statement in the client options file.
2. The journal service only provides a subset of the INCLUDE/EXCLUDE
function provided by the backup-archive client. The journal service does not
support INCLUDE statements and it does not support the exclude.dir option.
There is no correlation between the journal exclude list and the backup-archive
client exclude list.
The following are examples of equivalent journal exclude statements:
dsm.opt: tsmjbbd.ini
EXCLUDE c:\testdir\...\* c:\testdir\*
EXCLUDE.DIR c:\testdir\test* c:\testdir\test*\*
44
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
The following pattern matching meta characters are supported:
%
Matches exactly one character.
*
Matches zero or more characters.
%EnvVar%
Expands environment variable.
The following is an exclude statement syntax example:
[JournalExcludeList]
%SystemRoot%\System32\Config\*
C:\Program Files\Tivoli\TSM\baclient\adsm.sys\*
%TEMP%\*
%TMP%\*
c:\excludedir\*
c:\dir1\excludefile
*.:\*.tmp
Note: The c:\excludedir\* statement matches the entire tree including
subdirectories and files.
JournaledFileSystemSettings stanza
Settings under this stanza apply to each specified journaled file system unless they
are overridden for individual file systems in an override stanza.
The following is the syntax for the JournaledFileSystemSettings stanza:
Syntax for JournaledFileSystemSettings stanza:
[JournaledFileSystemSettings]
Syntax for stanza settings:
JournaledFileSystemSetting=value
You can specify the following JournaledFileSystemSettings values:
DirNotifyBufferSize
Specifies the size of the buffer to record change notifications for a
particular journal file system. You might need to increase this value for
journaled file systems that generate a very large volume of change activity.
The buffer size is limited by memory. The default value is 16 KB.
JournaledFileSystems
Specifies a space delimited list of file systems to journal. Full file system
specifications and Windows junctions are supported. There is no default
value. You must specify at least one journaled file system for the journal
service to run. Journaled file systems can be added or removed online
without having to restart the service. For example:
JournaledFileSystems=c: d:
JournalDbSize
Specifies the maximum size the journal database can grow. The journal
database size is expressed in bytes. A value of zero (0) indicates that the
database size is limited only by the capacity of the file system containing
the journal database. The default is 0 (unlimited). For example:
JournalDBSize=0x10000000
NotifyBufferSize
Specifies the size of the memory buffer receiving file system change
notifications for a particular journal file system. You might need to increase
Chapter 2. Configure the IBM Spectrum Protect client
45
this value for journaled file systems that generate a very large volume of
change activity. The buffer size is limited by memory. The default value is
32 KB. For example:
NotifyBufferSize=0x00008000
NotifyFilter
Specifies what file system change actions generate notifications to the
journal service. NotifyFilter applies to file changes and directory
modifications. Directory name changes, such as deletions and creations, are
always tracked regardless of the filter value. Multiple actions can be
monitored by combining (adding) values together. The default value is
0x11F (File and Dir Name, Attrib, Size, Last Write, and security Changes).
You can also use the IBM Spectrum Protect Journal Engine Wizard to
specify that any or all of these actions are monitored. Supported values are:
Value type
Decimal
Hex
File Name
1
0x001
Dir Name
2
0x002
Attribute
4
0x004
File size*
8
0x008
Last Write Time*
16
0x010
Last Access Time
32
0x020
Create Time
64
0x040
Security (ACL)
256
0x100
The asterisk (*) indicates that notification might be deferred until disk write cache
is flushed. Name changes are object creations, deletions, or renames.
Example:
NotifyFilter=0x107
PreserveDbOnExit setting
This setting allows a journal to remain valid when a journaled file system
goes offline and comes back online. This is useful for preserving the
journal during system reboots, cluster failovers, and resource movement.
File systems go offline when the journal service stops or when the file
system is removed from the configuration file. File systems come back
online when the journal service is started or when the file system is added
to the configuration file.
This setting allows a journal-based backup to continue processing when
the service is restarted (or the file system comes back online) without
performing a full incremental backup.
Note: Any change activity which occurs while the journal service is not
running (or the file system is offline) is not recorded in the journal.
In a clustered environment, shared resources can move to different
workstations in the cluster. The journal service running on each
workstation in the cluster must include these shared resources in the list of
journaled file systems. The journal service running on the workstation
which currently owns the resource actively journals the shared resource
while other journal services on workstations in the cluster which do not
own the resource must defer journaling until the resource becomes
46
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
available (or is moved to that workstation). The configuration settings
deferFSMonStart, deferRetryInterval, and logFSErrors allows deferment for a
file system until the file system is available and accessible.
A value of 1 specifies that the journaled file system journal database is not
deleted when the journal file system goes offline. The database is also valid
when the journal file system comes back online. This value should be used
with caution because any file system change activity which occurs while
the journaled file system is offline is not reflected in the journal database.
The default setting of 0 deletes the journaled file system journal database.
Note: The journal is only preserved when a journaled file system comes
offline normally or is brought offline when the resource is no longer
available and you specify the deferFsMonStart setting. If a file system
comes offline due to an error such as a notification buffer overrun, the
journal is not preserved.
An example for not deleting the journal database upon exit is:
[JournaledFileSystemSettings.D:\]
;
; Do not delete the journal when D:\ goes offline
;
PreserveDbOnExit=1
deferFSMonStart setting
This setting defers an attempt to begin monitoring a file system in the
following cases:
v When the specified journaled file system is not valid or available
v The journal directory for the specified journaled file system cannot be
accessed or created
Resources are checked at the interval you specify using the
deferRetryInterval setting.
The deferFSMonStart setting is most commonly used in a cluster
environment where shared resources might move to different workstations
in the cluster.
A value of 1 indicates that the setting is on. A value of 0 indicates that the
setting is off. The default value is off (set to 0) .
deferRetryInterval setting
This setting specifies the value in seconds that a deferred file systems with
the deferRetryInterval setting enabled are checked for availability and
brought online. The default value is 1 second.
logFSErrors setting
This setting specifies whether errors encountered while accessing a
journaled file system or journal directory are logged in the
jbberror.logand the event log.
Use the logFSErrors setting with the deferFSMonStart setting to prevent
excessive File System unavailable messages from being logged when
bringing a journaled file system online is deferred. The first error which
causes the file system to be deferred is logged. Subsequent errors are not
logged. A value of 1 indicates that the setting is on. A value of 0 indicates
that the setting is off.
An example to defer journaling until the file system journal directories are
valid is:
Chapter 2. Configure the IBM Spectrum Protect client
47
[JournalSettings]
;
; Place journal files in directory on each journaled file system
;
journalDir=\tsmjournal
[JournaledFileSystemSettings]
;
;journal c:, d:, and f:
;
JournaledFileSystems=c: d: d:\mountpoint f:
;
; Override stanza to defer starting journaling for f:\
; until it is a valid file system
[JournalFileSystemSettings.f:\]
;
; Keep database valid if file system goes offline
;
PreserveDBOnExit=1
;
; Defer journaling until file system and journal directory
; are valid
;
deferFSMonStart=1
;
; Attempt to start journaling every 120 seconds when deferred
;
deferRetryInterval=120
;
;Do not log excessive resource unavailable messages
;
logFsErrors=0
Related concepts:
“Overriding stanzas”
Overriding stanzas
Any setting in the JournaledFileSystemSettings stanza, except for the buffer sizes,
can be overridden for a particular journaled file system by creating an override
stanza.
The following is the syntax for the JournaledFileSystemSettings stanza:
Syntax for JournaledFileSystemSettings stanza:
[JournaledFileSystemSettings.fs]
Syntax for stanza settings:
JournaledFileSystemSetting=override value
Example:
[JournalFileSystemSettings.C:\]
NotifyBuffer=0x0020000
NotifyFilter=0x107
Client-side data deduplication
Data deduplication is a method of reducing storage needs by eliminating redundant
data.
48
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Overview
Two types of data deduplication are available: client-side data deduplication and
server-side data deduplication.
Client-side data deduplication is a data deduplication technique that is used on the
backup-archive client to remove redundant data during backup and archive
processing before the data is transferred to the IBM Spectrum Protect server. Using
client-side data deduplication can reduce the amount of data that is sent over a
local area network.
Server-side data deduplication is a data deduplication technique that is done by the
server. The IBM Spectrum Protect administrator can specify the data deduplication
location (client or server) to use with the DEDUP parameter on the REGISTER
NODE or UPDATE NODE server command.
Enhancements
With client-side data deduplication, you can:
v Exclude specific files on a client from data deduplication.
v Enable a data deduplication cache that reduces network traffic between the
client and the server. The cache contains extents that were sent to the server in
previous incremental backup operations. Instead of querying the server for the
existence of an extent, the client queries its cache.
Specify a size and location for a client cache. If an inconsistency between the
server and the local cache is detected, the local cache is removed and
repopulated.
Note: For applications that use the IBM Spectrum Protect API, the data
deduplication cache must not be used because of the potential for backup
failures caused by the cache being out of sync with the IBM Spectrum Protect
server. If multiple, concurrent backup-archive client sessions are configured,
there must be a separate cache configured for each session.
v Enable both client-side data deduplication and compression to reduce the
amount of data that is stored by the server. Each extent is compressed before it
is sent to the server. The trade-off is between storage savings and the processing
power that is required to compress client data. In general, if you compress and
deduplicate data on the client system, you are using approximately twice as
much processing power as data deduplication alone.
The server can work with deduplicated, compressed data. In addition,
backup-archive clients earlier than V6.2 can restore deduplicated, compressed
data.
Client-side data deduplication uses the following process:
v The client creates extents. Extents are parts of files that are compared with other
file extents to identify duplicates.
v The client and server work together to identify duplicate extents. The client
sends non-duplicate extents to the server.
v Subsequent client data-deduplication operations create new extents. Some or all
of those extents might match the extents that were created in previous
data-deduplication operations and sent to the server. Matching extents are not
sent to the server again.
Chapter 2. Configure the IBM Spectrum Protect client
49
Benefits
Client-side data deduplication provides several advantages:
v It can reduce the amount of data that is sent over the local area network (LAN).
v The processing power that is required to identify duplicate data is offloaded
from the server to client nodes. Server-side data deduplication is always enabled
for deduplication-enabled storage pools. However, files that are in the
deduplication-enabled storage pools and that were deduplicated by the client,
do not require additional processing.
v The processing power that is required to remove duplicate data on the server is
eliminated, allowing space savings on the server to occur immediately.
Client-side data deduplication has a possible disadvantage. The server does not
have whole copies of client files until you back up the primary storage pools that
contain client extents to a non-deduplicated copy storage pool. (Extents are parts of
a file that are created during the data-deduplication process.) During storage pool
backup to a non-deduplicated storage pool, client extents are reassembled into
contiguous files.
By default, primary sequential-access storage pools that are set up for data
deduplication must be backed up to non-deduplicated copy storage pools before
they can be reclaimed and before duplicate data can be removed. The default
ensures that the server has copies of whole files at all times, in either a primary
storage pool or a copy storage pool.
Important: For further data reduction, you can enable client-side data
deduplication and compression together. Each extent is compressed before it is sent
to the server. Compression saves space, but it increases the processing time on the
client workstation.
In a data deduplication-enabled storage pool (file pool) only one instance of a data
extent is retained. Other instances of the same data extent are replaced with a
pointer to the retained instance.
When client-side data deduplication is enabled, and the server has run out of
storage in the destination pool, but there is a next pool defined, the server will
stop the transaction. The backup-archive client retries the transaction without
client-side data deduplication. To recover, the IBM Spectrum Protect administrator
must add more scratch volumes to the original file pool, or retry the operation
with deduplication disabled.
For client-side data deduplication, the IBM Spectrum Protect server must be
Version 6.2 or higher.
Prerequisites
When configuring client-side data deduplication, the following requirements must
be met:
v The client and server must be at version 6.2.0 or later. The latest maintenance
version should always be used.
v When a client backs up or archives a file, the data is written to the primary
storage pool that is specified by the copy group of the management class that is
bound to the data. To deduplicate the client data, the primary storage pool must
be a sequential-access disk (FILE) storage pool that is enabled for data
deduplication.
50
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
v The value of the DEDUPLICATION option on the client must be set to YES. You can
set the DEDUPLICATION option in the client options file, in the preference editor of
the backup-archive client GUI, or in the client option set on the IBM Spectrum
Protect server. Use the DEFINE CLIENTOPT command to set the DEDUPLICATION
option in a client option set. To prevent the client from overriding the value in
the client option set, specify FORCE=YES.
v Client-side data deduplication must be enabled on the server. To enable
client-side data deduplication, use the DEDUPLICATION parameter on the
REGISTER NODE or UPDATE NODE server command. Set the value of the
parameter to CLIENTORSERVER.
v Ensure files on the client are not excluded from client-side data deduplication
processing. By default, all files are included. You can optionally exclude specific
files from client-side data deduplication with the exclude.dedup client option.
v Files on the client must not be encrypted. Encrypted files and files from
encrypted file systems cannot be deduplicated.
v Files must be larger than 2 KB and transactions must be below the value that is
specified by the CLIENTDEDUPTXNLIMIT option. Files that are 2 KB or smaller are
not deduplicated.
The server can limit the maximum transaction size for data deduplication by
setting the CLIENTDEDUPTXNLIMIT option on the server. For more information about
this option, see the IBM Spectrum Protect server documentation.
The following operations take precedence over client-side data deduplication:
v LAN-free data movement
v Simultaneous-write operations
v Data encryption
Important: Do not schedule or enable any of those operations during client-side
data deduplication. If any of those operations occur during client-side data
deduplication, client-side data deduplication is turned off, and a message is written
to the error log.
The setting on the server ultimately determines whether client-side data
deduplication is enabled. See Table 6.
Table 6. Data deduplication settings: Client and server
Value of the client
DEDUPLICATION
option
Setting on the server
Data deduplication
location
Yes
On either the server or the client
Client
Yes
On the server only
Server
No
On either the server or the client
Server
No
On the server only
Server
Encrypted files
The IBM Spectrum Protect server and the backup-archive client cannot deduplicate
encrypted files. If an encrypted file is encountered during data deduplication
processing, the file is not deduplicated, and a message is logged.
Chapter 2. Configure the IBM Spectrum Protect client
51
Tip: You do not have to process encrypted files separately from files that are
eligible for client-side data deduplication. Both types of files can be processed in
the same operation. However, they are sent to the server in different transactions.
As a security precaution, you can take one or more of the following steps:
v Enable storage-device encryption together with client-side data deduplication.
v Use client-side data deduplication only for nodes that are secure.
v If you are uncertain about network security, enable Secure Sockets Layer (SSL).
v If you do not want certain objects (for example, image objects) to be processed
by client-side data deduplication, you can exclude them on the client. If an
object is excluded from client-side data deduplication and it is sent to a storage
pool that is set up for data deduplication, the object is deduplicated on server.
v Use the SET DEDUPVERIFICATIONLEVEL command to detect possible
security attacks on the server during client-side data deduplication. Using this
command, you can specify a percentage of client extents for the server to verify.
If the server detects a possible security attack, a message is displayed.
Related tasks:
“Configuring the client for data deduplication”
Related reference:
“Deduplication” on page 356
“Exclude options” on page 395
“Dedupcachepath” on page 355
“Dedupcachesize” on page 355
“Enablededupcache” on page 384
“Ieobjtype” on page 421
Configuring the client for data deduplication
Configure the client so that you can use data deduplication to back up or archive
your files.
Before you begin
Before you configure your client to use data deduplication, ensure that the
requirements listed in “Client-side data deduplication” on page 48 are met:
v The server must enable the client for client-side data deduplication with the
DEDUP=CLIENTORSERVER parameter on either the REGISTER NODE or UPDATE
NODE command.
v The storage pool destination for the data must be a data deduplication-enabled
storage pool.
v Ensure that your files are bound to the correct management class.
v Files must be larger than 2 KB.
A file can be excluded from client-side data deduplication processing. By default,
all files are included. Refer to the exclude.dedup option for details.
The server can limit the maximum transaction size for data deduplication by
setting the CLIENTDEDUPTXNLIMIT option on the server.
52
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Procedure
Use one of the following methods to enable data deduplication on the client:
Option
Description
Edit the client options file
v Add the deduplication yes option to the
dsm.opt file.
Preferences editor
1. From the IBM Spectrum Protect window,
click Edit > Client Preferences.
2. Click Deduplication.
3. Select the Enable Deduplication check
box.
4. Click OK to save your selections and
close the Preferences Editor.
Results
After you have configured the client for data deduplication, start a backup or
archive operation. When the operation completes, the backup or archive report
shows the amount of data that was deduplicated in this operation, and how many
files were processed by client-side data deduplication.
If you do not have enough disk space for the backup or archive operation, you can
enable client-side data deduplication without local data deduplication cache on the
client by using these steps:
1. Add the deduplication yes option to the client options file.
v Add the deduplication yes option to the dsm.opt file. You can also set this
option in the GUI.
2. Turn off the local data deduplication cache by completing one of the following
steps:
v Add the ENABLEDEDUPCACHE NO option to the dsm.opt file.
You can also set this option in the backup-archive client preferences editor by
clearing the Enable Deduplication Cache check box.
Example
The following example uses the query session command to show the type of data
that was processed for data deduplication:
Protect> q sess
IBM Spectrum Protect Server Connection Information
Server Name.............:
Server Type.............:
Archive Retain Protect..:
Server Version..........:
Last Access Date........:
Delete Backup Files.....:
Delete Archive Files....:
Deduplication...........:
SERVER1
Windows
"No"
Ver. 6, Rel. 2, Lev. 0.0
08/25/2009 13:38:18
"No"
"Yes"
"Client Or Server"
Node Name...............: AVI
User Name...............:
The following example uses the query management class command to show the
type of data that was processed for data deduplication:
Chapter 2. Configure the IBM Spectrum Protect client
53
Protect> q mgmt -det
Domain Name : DEDUP
Activated Policy Set Name : DEDUP
Activation date/time : 08/24/2009 07:26:09
Default Mgmt Class Name : DEDUP
Grace Period Backup Retn. : 30 day(s)
Grace Period Archive Retn.: 365 day(s)
MgmtClass Name : DEDUP
Description : dedup - values like standard
Space Management Technique : None
Auto Migrate on Non-Usage : 0
Backup Required Before Migration: YES
Destination for Migrated Files : SPACEMGPOOL
Copy Group
Copy Group Name........: STANDARD
Copy Type..............: Backup
Copy Frequency.........: 0 day(s)
Versions Data Exists...: 2 version(s)
Versions Data Deleted..: 1 version(s)
Retain Extra Versions..: 30 day(s)
Retain Only Version....: 60 day(s)
Copy Serialization.....: Shared Static
Copy Mode..............: Modified
Copy Destination.......: AVIFILEPOOL
Lan Free Destination...: NO
Deduplicate Data.......: YES
Copy Group Name........:
Copy Type..............:
Copy Frequency.........:
Retain Version.........:
Copy Serialization.....:
Copy Mode..............:
Retain Initiation......:
Retain Minimum.........:
Copy Destination.......:
Lan Free Destination...:
Deduplicate Data.......:
STANDARD
Archive
Cmd
365 day(s)
Shared Static
Absolute
Create
65534 day(s)
FILEPOOL
NO
YES
ANS1900I Return code is 0.
Related concepts:
“Client-side data deduplication” on page 48
Related reference:
“Deduplication” on page 356
“Enablededupcache” on page 384
“Exclude options” on page 395
CLIENTDEDUPTXNLIMIT option
REGISTER NODE command
UPDATE NODE command
Excluding files from data deduplication
You can exclude a file from data deduplication during backup or archive
processing.
54
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
About this task
You can exclude only files for archive data deduplication. You can exclude files,
images, system state objects, and ASR for backup data deduplication.
Procedure
If you do not want certain files to be processed by client-side data deduplication,
you can exclude files from data deduplication processing using the GUI:
1. Click Edit > Client Preferences.
2. Click the Include-Exclude tab.
3. Click Add to open the Define Include-Exclude Options window.
4. Select a category for processing.
v To exclude a file from data deduplication during archive processing, select
Archive in the Category list.
v To exclude a file from data deduplication during backup processing, select
Backup in the Category list.
5. Select Exclude.Dedup in the Type list.
6. Select an item from the Object Type list.
v For archive processing, only the File object type is available.
v For backup processing, select one of the following object types:
– File
– Image
– System state
– ASR
7. Specify a file or pattern in the File or Pattern field. You can use wildcard
characters. If you do not want to type a file or pattern, click Browse to open a
selection window and select a file. For mounted file spaces, you can choose the
directory mount point from the selection window.
For ASR and system state, this field is filled out automatically. When you
specify the image object type, the drive letter must be followed by :\*\* . For
example, to exclude drive E:, enter the following pattern:
E:\*\*
8. Click OK to close the Define Include-Exclude Options window. The exclude
options that you defined are in an exclude statement at the bottom of the
Statements list box in the Include-Exclude Preferences tab.
9. Click OK to save your selections and close the Preferences Editor.
What to do next
You can also exclude files from data deduplication processing by editing the
dsm.opt file:
1. Add the deduplication yes option
2. Exclude client-side data deduplication for image backup of drive. For example,
to exclude drive E:, add the following statement: EXCLUDE.DEDUP E:\*\*
IEOBJTYPE=Image to dsm.opt.
Important: If an object is sent to a data deduplication pool, data deduplication
occurs on the server, even if the object is excluded from client-side data
deduplication.
Related concepts:
Chapter 2. Configure the IBM Spectrum Protect client
55
“Client-side data deduplication” on page 48
Related reference:
“Deduplication” on page 356
“Enablededupcache” on page 384
“Exclude options” on page 395
Automated client failover configuration and use
The backup-archive client can automatically fail over to a secondary server for data
recovery when the IBM Spectrum Protect server is unavailable. You can configure
the client for automated failover or prevent the client from failing over. You can
also determine the replication status of your data on the secondary server before
you restore or retrieve the replicated data.
Related tasks:
“Restoring or retrieving data during a failover” on page 222
Automated client failover overview
When there is an outage on the IBM Spectrum Protect server, the backup-archive
client can automatically fail over to a secondary server for data recovery.
The IBM Spectrum Protect server that the client connects to during normal
production processes is called the primary server. When the primary server and
client nodes are set up for node replication, that server is also known as the source
replication server. The client data on the source replication server can be replicated
to another IBM Spectrum Protect server, which is the target replication server. This
server is also known as the secondary server, and is the server that the client
automatically fails over to when the primary server fails.
For the client to automatically fail over to the secondary server, the connection
information for the secondary server must be made available to the client. During
normal operations, the connection information for the secondary server is
automatically sent to the client from the primary server during the logon process.
The secondary server information is automatically saved to the client options file.
No manual intervention is required by you to add the information for the
secondary server.
Each time the client logs on to the IBM Spectrum Protect server, the client attempts
to contact the primary server. If the primary server is unavailable, the client
automatically fails over to the secondary server, according to the secondary server
information in the client options file. In this failover mode, you can restore or
retrieve any replicated client data. When the primary server is online again, the
client automatically fails back to the primary server the next time the client is
started.
For example, the following sample text is the connection information about the
secondary server that is sent to the client and saved to the client options file
(dsm.opt):
*** These options should not be changed manually
REPLSERVERNAME
TARGET
REPLTCPSERVERADDRESS 192.0.2.9
REPLTCPPORT
1501
REPLSSLPORT
1502
REPLSERVERGUID
60.4a.c3.e1.85.ba.11.e2.af.ce.00.0c.29.2f.07.d3
56
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
MYREPLICATIONServer TARGET
MYPRIMARYServer SERVER1
*** end of automatically updated options
Requirements for automated client failover
Before you configure or use the client for automated client failover, the
backup-archive client and IBM Spectrum Protect server must meet several
requirements.
Ensure that the client meets the following requirements for automated client
failover:
v The primary server, secondary server, and backup-archive client must be
running IBM Spectrum Protect Verson 7.1, or a later version.
v The primary and secondary servers must be set up for node replication.
v The client node must be configured for node replication on the source
replication server by using the REGISTER NODE REPLSTATE=ENABLED or UPDATE NODE
REPLSTATE=ENABLED server commands.
v By default, the client is enabled for automated client failover. However, if the
usereplicationfailover no option is specified in the client options file, either
change the value to yes, or remove the option.
v Valid connection information for the secondary server must exist in the client
options file. During normal operations, this information is automatically sent to
the client from the primary server.
v To save the secondary server connection information that is sent from the
primary server, the client must have write access to the dsm.opt file on Windows
clients, and the dsm.sys file on AIX, Linux, Mac OS X, and Oracle Solaris clients.
If the client does not have write access to these files, the secondary server
information is not saved to the client options file, and an error is added to the
error log.
v Non-root users cannot use the default location for the node replication table. You
must specify a different location by adding the nrtablepath option to the
dsm.sys file. For more information, see “Nrtablepath” on page 471.
v The following processes must occur before the connection information for the
secondary server is sent to the options file:
– The client must be backed up to the source replication server at least one
time.
– The client node must be replicated to the target replication server at least one
time.
v Failover occurs for client nodes that are backed up with client-node proxy
support when both the target and agent nodes are configured for replication to
the target replication server. When the target node is explicitly replicated, the
agent node is implicitly replicated to the target replication server as well, along
with the proxy relationship.
For example, Node_B is granted authority to perform client operations on behalf
of Node_A with the following server command:
grant proxynode target=Node_A agent=Node_B
If both nodes are configured for replication with the replstate=enabled option
in the node definition, when Node_A is replicated, Node_B and the proxy
relationship are replicated as well.
Chapter 2. Configure the IBM Spectrum Protect client
57
Restrictions for automated client failover
Review the following information to better understand the process and the
restrictions that apply to automated client failover.
The following restrictions apply for automated client failover:
v When the client is in failover mode, you cannot use any functions that require
data to be stored on the secondary server, such as backup or archive operations.
You can use only data recovery functions, such as restore, retrieve, or query
operations. You can also edit client options and change the IBM Spectrum
Protect client password.
v Schedules are not replicated to the secondary server. Therefore, schedules are not
run while the primary server server is unavailable.
v After the client connects to the secondary server in failover mode, it does not
attempt to connect to the primary server until the next initial logon to the server.
The client attempts to fail over to the secondary server only when the initial
connection to the primary server fails. The initial connection is the first
connection that the client makes with the server.
If the primary server becomes unavailable during a client operation, the client
does not fail over to the secondary server, and the operation fails. You must
restart the client so that it can fail over to the secondary server, and then run the
client operation again.
Restore operations that are interrupted when the primary server goes down
cannot be restarted after the client fails over. You must run the whole restore
operation again after the client fails over to the secondary server.
v If the IBM Spectrum Protect password is changed before the client node is
replicated, the password will not be synchronized between the primary and
secondary servers. If a failover occurs during this time, you must manually reset
the password on the secondary server and the client. When the primary server is
online again, the password must be reset for the client to connect to the primary
server.
If the password is reset while the client is connected to the secondary server, the
password must be reset on the primary server before the client can log on to the
primary server. This restriction is true if the passwordaccess option is set to
generate or if the password is manually reset.
v If you backed up or archived client data, but the primary server goes down
before it replicates the client node, the most recent backup or archive data is not
replicated to the secondary server. The replication status of the file space is not
current. If you attempt to restore or retrieve the data in failover mode and the
replication status is not current, a message is displayed that indicates that the
data you are about to recover is out-of-date. You can decide whether to proceed
with the recovery or wait until the primary server comes back online.
v If an administrative user ID with client owner authority exists on the source
replication server, and the user ID has the same name as the client node, the
administrative user ID is replicated during the node replication process on the
server. If such a user ID does not exist on the source replication server, the
replication process does not create this administrator definition on the target
replication server.
If other administrative user IDs are assigned to the node, the IBM Spectrum
Protect administrator must manually configure the administrative user IDs on
the target replication server. Otherwise, the administrative user cannot connect
to the target replication server (secondary server) with the IBM Spectrum Protect
web client.
58
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
v If you restore a file from the IBM Spectrum Protect, and the file system is
managed by IBM Spectrum Protect for Space Management, you must not restore
the file as a stub file. You must restore the complete file. Use the
restoremigstate=no option to restore the complete file. If you restore the file as
a stub from the target server, the following consequences can occur:
– You cannot recall the file from the IBM Spectrum Protect source server by
using the IBM Spectrum Protect for Space Management client.
– The IBM Spectrum Protect for Space Management reconciliation process that
runs against the IBM Spectrum Protect source server expires the file. If the file
is expired by a reconciliation process, you can restore the complete file with
the backup-archive client and the restoremigstate=no option.
Failover capabilities of IBM Spectrum Protect components
IBM Spectrum Protect components and products rely on the backup-archive client
or API to back up data to the primary IBM Spectrum Protect server. When the
primary server becomes unavailable, some of these products and components can
fail over to the secondary server, while others are not capable of failover.
To learn more about the failover capabilities of IBM Spectrum Protect components
and products, see technote 1649484.
Related tasks:
“Determining the status of replicated client data” on page 61
Configuring the client for automated failover
You can manually configure the client to automatically fail over to the secondary
server.
Before you begin
Before you begin the configuration:
v Ensure that the client node participates in node replication on the primary
server.
v Ensure that the client meets the requirements for automated client failover.
v Use this procedure only if the connection information for the secondary server is
not current or if it is not in the client options file.
About this task
You might manually configure the client for automated failover in the following
situations:
v The secondary server configuration was changed and the primary server is
down before the client logs on to the server. When you manually add the
connection information, the client is enabled for failover to the secondary server.
v You accidentally erased some or all of the secondary server connection
information in the client options file.
Tip: Instead of manually configuring the client options file, you can run the
dsmc q session command, which prompts you to log on to the primary server.
The connection information for the secondary server is sent automatically to the
client options file.
Chapter 2. Configure the IBM Spectrum Protect client
59
Procedure
To manually configure the client for automated failover, complete the following
steps:
1. Ensure that the client is enabled for automated client failover by verifying that
the usereplicationfailover option is either not in the client options file or is
set to yes. By default, the client is enabled for automated client failover so the
usereplicationfailover is not required in the client options file.
2. Obtain the connection information about the secondary server from the IBM
Spectrum Protect server administrator and add the information to the
beginning of the client options file. Group the statements into a stanza under
the replservername statement.
For example, add the following statements to the dsm.opt file:
REPLSERVERNAME
REPLTCPSERVERADDRESS
REPLTCPPORT
REPLSSLPORT
REPLSERVERGUID
TARGET
192.0.2.9
1501
1502
60.4a.c3.e1.85.ba.11.e2.af.ce.00.0c.29.2f.07.d3
MYREPLICATIONServer TARGET
MYPRIMARYSERVERNAME SERVER1
3. Save and close the client options file.
4. Restart the backup-archive client GUI or log on to the IBM Spectrum Protect
server from the command-line interface. The client is connected to the
secondary server.
Example
After you configured the client for automated client failover, and the client
attempts to log on to the server, the following sample command output is
displayed:
IBM Spectrum Protect
Command Line Backup-Archive Client Interface
Client Version 8, Release 1, Level 0.0
Client date/time: 12/16/2016 12:05:35
(c) Copyright by IBM Corporation and other(s) 1990, 2016. All Rights Reserved.
Node Name: MY_NODE_NAME
ANS2106I Connection to primary IBM Spectrum Protect server 192.0.2.1 failed
ANS2107I Attempting to connect to secondary server TARGET at 192.0.2.9 : 1501
Node Name: MY_NODE_NAME
Session established with server TARGET: Windows
Server Version 8, Release 1, Level 0.0
Server date/time: 12/16/2016 12:05:35 Last access: 12/15/2016 09:55:56
Session established in failover mode to secondary server
ANS2108I Connected to secondary server TARGET.
What to do next
You can restore or retrieve any replicated data in failover mode.
Related concepts:
“Automated client failover overview” on page 56
Related tasks:
“Restoring or retrieving data during a failover” on page 222
60
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Related reference:
“Forcefailover” on page 415
“Myprimaryserver” on page 464
“Myreplicationserver” on page 465
“Nrtablepath” on page 471
“Replserverguid” on page 496
“Replservername” on page 497
“Replsslport” on page 498
“Repltcpport” on page 500
“Repltcpserveraddress” on page 501
“Usereplicationfailover” on page 569
Determining the status of replicated client data
You can verify whether the most recent backup of the client was replicated to the
secondary server before you restore or retrieve client data from the secondary
server.
About this task
You can obtain the status of replicated client data to determine whether the most
recent client backup was replicated to the secondary server.
If the time stamp of the most recent backup operation on the client matches the
time stamp of the backup on the secondary server, the replication status is current.
If the time stamp of the most recent backup operation is different from the time
stamp of the backup on the secondary server, the replication status is not current.
This situation can occur if you backed up the client, but before the client node can
be replicated, the primary server goes down.
Procedure
To determine the status of replicated client data, issue the following command at
the command prompt:
dsmc query filespace -detail
The following sample output shows that the time stamps on the server and the
client match, therefore the replication status is current:
#
--1
Last Incr Date
-------------00/00/0000 00:00:00
Last Store Date
--------------Backup Data :
Archive Data :
Type
------HFS
fsID Unicode
---- ------9 Yes
Server
-----04/22/2013 19:39:17
No Date Available
Replication File Space Name
----------- --------------Current
/
Local
----04/22/2013 19:39:17
No Date Available
The following sample output shows that time stamps on the server and the client
do not match, therefore the replication status is not current:
Chapter 2. Configure the IBM Spectrum Protect client
61
#
--1
Last Incr Date
-------------00/00/0000 00:00:00
Last Store Date
--------------Backup Data :
Archive Data :
Type
------HFS
fsID Unicode
---- ------9 Yes
Server
-----04/22/2013 19:39:17
No Date Available
Replication File Space Name
----------- --------------Not Current /
Local
----04/24/2013 19:35:41
No Date Available
What to do next
If you attempt to restore the data in failover mode and the replication status is not
current, a message is displayed that indicates that the data you are about to restore
is old. You can decide whether to proceed with the restore or wait until the
primary server is online.
Related tasks:
“Restoring or retrieving data during a failover” on page 222
Related reference:
“Nrtablepath” on page 471
Preventing automated client failover
You can configure the client to prevent automated client failover to the secondary
server.
About this task
You might want to prevent automated client failover, for example, if you know
that the data on the client node was not replicated to the secondary server before
the primary server went offline. In this case, you do not want to recover any
replicated data from the secondary server that might be old.
Procedure
To prevent the client node from failing over to the secondary server, add the
following statement to the client options file:
usereplicationfailover no
This setting overrides the configuration that is provided by the IBM Spectrum
Protect server administrator on the primary server.
Results
The client node does not automatically fail over to the secondary server the next
time it tries to connect to the offline primary server.
Related tasks:
“Determining the status of replicated client data” on page 61
Related reference:
“Usereplicationfailover” on page 569
Forcing the client to fail over
The client can immediately fail over to the secondary server even if the primary
server is operational. For example, you can use this technique to verify that the
client is failing over to the expected secondary server.
62
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Procedure
To force the client to immediately fail over to the secondary server, complete the
following steps:
1. Add the forcefailover yes option in the client options file (dsm.opt).
2. Connect to the secondary server by restarting the backup-archive client GUI or
by starting a command session with the dsmc command.
3. Optional: Instead of updating the options file, you can establish a connection
with the secondary server by specifying the -forcefailover=yes option with a
command. For example:
dsmc q sess -forcefailover=yes
What to do next
You can verify that you are connected to the secondary server with one of the
following methods:
v Check the Secondary Server Information field in the Connection Information
window in the backup-archive client GUI.
v Check the command output when you start a command session. The status of
the secondary server is displayed in the output.
Related reference:
“Forcefailover” on page 415
Configuring the client to back up and archive Tivoli Storage Manager
FastBack data
Before you can back up or archive Tivoli Storage Manager FastBack client data,
you must complete configuration tasks.
First ensure that you have configured the backup-archive client and that you
installed the Tivoli Storage Manager FastBack client.
Install the FastBack client by using the information at Tivoli Storage Manager
FastBack.
After you install the FastBack client, complete the following tasks. You can also use
the Client Configuration wizard for Tivoli Storage Manager FastBack.
1. Register a node for each FastBack client where data is backed up or archived.
The node name must be the short host name of the FastBack client.
This is a one-time configuration performed once for each FastBack client whose
volumes need to be backed up or archived.
This registration step must be performed manually only when the
backup-archive client is used as a stand-alone application.
The Administration Center does this node registration automatically when the
user creates schedules for archiving or backing up FastBack data using the
Administration Center. Starting with Version 7.1, the Administration Center
component is no longer included in Tivoli Storage Manager or IBM Spectrum
Protect distributions. FastBack users who have an Administration Center from a
previous server release can continue to use it to create and modify FastBack
schedules. If you do not already have an Administration Center installed, you
can download the previously-released version from ftp://public.dhe.ibm.com/
storage/tivoli-storage-management/maintenance/admincenter/v6r3/. If you do
not have an Administration Center installed, you must create and modify
Chapter 2. Configure the IBM Spectrum Protect client
63
FastBack schedules on the IBM Spectrum Protect server. For information about
creating schedules on the server, see the IBM Spectrum Protect server
documentation.
2. Use the server GRANT PROXY command to grant proxy authority to your
current backup-archive client node on each node representing the FastBack
client created in step 1. The FastBack node should be the target, and the current
client node should be the proxy.
This is a one-time configuration, and is performed by the Administration
Center if the backup or archive is initiated by the Administration Center.
3. Run the set password command to store the credentials of the FastBack
repositories where the backup-archive client connects. Run the set password
-type=fastback command once for each repository where the backup-archive
client is expected to connect.
The credentials that are stored depends on these configurations:
v Backup-archive client on the FastBack server
v Backup-archive client on the FastBack Disaster Recovery Hub
v Backup-archive client on a dedicated proxy workstation
For information about integrating IBM Spectrum Protect and Tivoli Storage
Manager FastBack, see Integrating Tivoli Storage Manager FastBack and IBM
Spectrum Protect.
Related concepts:
“Installation requirements for backing up and archiving Tivoli Storage Manager
FastBack client data” on page 5
“Client configuration wizard for Tivoli Storage Manager FastBack” on page 6
“Configuring the backup-archive client to protect FastBack client data”
Related reference:
“Set Password” on page 784
Configuring the backup-archive client to protect FastBack client data
You can configure the backup-archive client to protect FastBack client data by
using the client configuration wizard.
Before you can use the IBM Spectrum Protect Client Configuration wizard for
FastBack, you must complete the following tasks:
v Ensure that either the FastBack server, or the FastBack Disaster Recovery Hub, is
installed and configured for short-term data retention.
v Also ensure that at least one snapshot has been taken.
v Ensure that the backup-archive client is properly configured with the IBM
Spectrum Protect server. Also make sure that the client acceptor service
(dsmcad.exe) is running. You can use the IBM Spectrum Protect Client
Configuration wizard in the backup-archive client GUI, after you install the
backup-archive client.
v Complete a one-time post-installation setup for these purposes:
– To specify the FastBack user name and password to be used by the wizard, to
query and mount volumes from the FastBack repository
– To run IBM Spectrum Protect scheduler scripts
v Set up the FastBack credentials file. The user ID that you specify must have
Tivoli Storage Manager FastBack administrative authority.
64
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
1.
Configure the user ID and password. Run the following command on the
workstation where the backup-archive client and FastBack server or Disaster
Recovery Hub are installed:
cd <TSM_FastBack_install_location>\FastBack\shell
where <TSM_FastBack_install_location> is the directory location where the
Tivoli Storage Manager FastBack client is installed.
2. If it does not exist, create a folder called FastbackTSMScripts under the
system drive of the workstation, using the following command:
mkdir <machine_system_drive>:\FastbackTSMScripts
3. Run the fastbackshell command:
FastBackShell -c encrypt -u userName -d domain -p password -f
<machine_system_drive>:\FastbackTSMScripts\credential.txt
The following options are used in the preceding command example:
– -u specifies the Tivoli Storage Manager FastBack administrator user name.
– -p specifies the Tivoli Storage Manager FastBack administrator password.
– -d specifies the Tivoli Storage Manager FastBack domain for the user
name.
– -f specifies the output file where the encrypted credentials are to be
written.
Important: The credentials file must be generated with the name
"credential.txt". The credentials file must also be located in the
FastbackTSMScripts directory of the system drive of the workstation, for the
wizard to function properly.
You can use the client configuration wizard in the backup-archive client Java GUI
or the backup-archive web client.
Follow these steps to use the client configuration wizard in the Java GUI:
1. Ensure that the backup-archive client is properly configured with the IBM
Spectrum Protect server.
2. The configuration wizard starts automatically to create the configuration file.
3. Follow the instructions on the panel to complete the wizard.
4. From the backup-archive client GUI main window, select Utilities > Setup
Wizard.
5. From the welcome page, select Help me configure the client to protect
FastBack client data and click Next.
6. Use the wizard to complete the configuration process.
Follow these steps to start the client configuration wizard in the web client:
1. Ensure that the web client is properly configured with the IBM Spectrum
Protect server, and that the IBM Spectrum Protect client acceptor service is
running.
To configure the web client, follow these steps:
a. From the backup-archive client GUI main window in the Java GUI, click
Utilities > Setup Wizard.
b. From the welcome page, select Help me configure the Web Client and click
Next. Follow the instructions on the panel to complete the wizard.
2. Start the web client. In your web browser, specify the client node name and
port number where the client acceptor service is running.
For example: http://<machine_name_or_ip_address>:1585
Chapter 2. Configure the IBM Spectrum Protect client
65
3. From the backup-archive client GUI main window, click Utilities > Setup
Wizard.
4. From the welcome page, select Help me configure the client to protect
FastBack client data, and click Next.
5. Use the wizard to complete the configuration process.
Related concepts:
“Client configuration wizard for Tivoli Storage Manager FastBack” on page 6
Configuring the backup-archive client in a cluster server environment
You can install the backup-archive client software locally on each node of a
Microsoft Cluster Server (MSCS) or Veritas Cluster Server (VCS) environment
cluster.
You can use the backup-archive client in a VCS environment on the supported
Windows Server platforms.
You can also install and configure the Scheduler Service for each cluster node to
manage all local disks and each cluster group containing physical disk resources.
For example, MSCS cluster mscs-cluster contains two nodes: node-1 and node-2,
and two cluster groups containing physical disk resources: group-a and group-b. In
this case, an instance of the IBM Spectrum Protect Backup-Archive Scheduler
Service should be installed for node-1, node-2, group-a, and group-b. This ensures
that proper resources are available to the Backup-Archive client when disks move
(or fail) between cluster nodes.
The clusternode option ensures that the client manages backup data logically,
regardless of which cluster node backs up a cluster disk resource. Use this option
for client nodes that process cluster disk resources, and not local resources.
Note: You must set the clusternode: option to yes for all IBM Spectrum
Protect-managed cluster operations. Inconsistent use of the clusternode option for
a given IBM Spectrum Protect cluster node name can cause the client to invalidate
the cluster node name encrypted password, and prompt the user to reenter the
password during the next backup-archive client program invocation.
Use the optfile option to properly call the correct (cluster) dsm.opt for all client
programs to ensure proper functionality for cluster related operations.
How you install and configure the backup-archive client in a cluster environment
depends on the cluster server technology used (MSCS or VCS) and the operating
system being used by the nodes in the cluster.
Related reference:
“Optfile” on page 474
Protecting data in MSCS clusters (Windows Server clients)
A client configuration wizard is used on nodes in an MSCS cluster environment to
automate and simplify the configuration of the backup-archive client to protect
cluster disk groups. The wizard can only be used on nodes that run supported
Windows Server clients as their operating system.
66
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Configuring cluster protection (Windows Server clients)
Use the IBM Spectrum Protect cluster wizard to configure the backup-archive client
to protect cluster resources. The wizard gathers the information that is needed so
the backup-archive client can protect cluster resources, and log on to the server.
Before you begin
Before you run the cluster configuration wizard, perform the following steps:
v Install the backup-archive client on each node in the cluster. All backup-archive
clients must be the same version of the software and all clients must be installed
in the same directory on each node.
v Register the nodes that you are going to run the cluster configuration wizard on.
On the IBM Spectrum Protect server, use the administrative command-line client
and register the node by using the register node command.
v Make sure that the cluster groups that will be configured are owned by the
system that will run the cluster wizard. This ensures that the backup-archive
client files (options file, error log, schedule log) can be created/updated on the
cluster drives.
About this task
You run the wizard on only one node in the cluster; the wizard creates the
necessary services on all nodes in the cluster.
The wizard can configure only one cluster group at a time. If you have multiple
cluster groups to protect, run the wizard as many times as needed to configure the
client to back up each group.
Procedure
1. Run dsm.exe to start the Java GUI.
2. In the GUI, click Utilities > Setup Wizard > Help me protect my cluster.
3. Choose Configure a new or additional cluster group, the first time you run
the wizard on a node. On subsequent wizard sessions, you can choose to
update a previously configured cluster group or to remove a saved
configuration.
4. Select the name of the cluster group that you want to protect.
5. Select the disks in the cluster group that you want to protect. You cannot use
the wizard to back up the quorum drive.
6. Specify the disk location where you want the wizard to store the client
options file (dsm.opt) that the wizard creates. The client options file must be
on one of the drives in the cluster group that you selected in step 4. If a client
options file exists at this location, you are prompted to overwrite it, or choose
a new directory.
7. Specify a name for the IBM Spectrum Protect Scheduler that will be used to
perform the backups. Select Use the Client Acceptor to manage the scheduler
if you want the client acceptor to manage the scheduler.
8. Specify the node name for the cluster node and the password that is used to
log on to the IBM Spectrum Protect Server. By default, the option to have the
password validated by the server is selected. Clear this option if you do not
want the password validated.
9. Specify the account that the scheduler and client acceptor daemon services log
on as when the services are started. Specify whether you want to start the
service manually, or when the node is booted.
Chapter 2. Configure the IBM Spectrum Protect client
67
10. Specify the names and location of the client schedule log file and error log file.
By default, event logging is enabled. Clear this option if you do not want to
log events.
To ensure that any node can perform backups if any other node fails, the
wizard copies the registry data to all nodes in the cluster.
Configure the web client in a cluster environment
To use the web client in a cluster environment, you must configure the
backup-archive client GUI to run in a cluster environment.
Beginning with IBM Spectrum Protect Version 8.1.2, you can no longer use the web
client to connect to the IBM Spectrum Protect V8.1.2 or later server. However, you
can still use the web client to connect to IBM Spectrum Protect V8.1.1, V8.1.0, or
V7.1.7 and earlier servers. For more information, see “Using the web client in the
new security environment” on page 117.
|
|
|
|
|
See “Configuring cluster protection (Windows Server clients)” on page 67 for
detailed information about installing and configuring the backup-archive client in a
MSCS or VCS environment.
Configure the web client to process cluster disk resources
After installing and configuring the backup-archive client in a MSCS or VCS
environment, there are some steps you must perform to process cluster disk
resources.
Step 1: Identify the cluster groups to manage:
Use the Microsoft Cluster Administrator utility or VCS Configuration editor to
determine which groups contain physical disk resources for the backup-archive
client to process.
Register a unique node name on the backup server for each group.
For example, an MSCS cluster named mscs-cluster contains the following groups
and resources:
v group-a - Contains physical disk q: (quorum), and physical disk r:
Note: VCS does not have quorum disk.
v group-b - Contains physical disk s:, and physical disk t:
In this example, the administrator registers two node names: mscs-cluster-group-a
and mscs-cluster-group-b. For example, to register mscs-cluster-group-a the
administrator can enter the following command:
register node mscs-cluster-group-a password
Step 2: Configure the client options file:
Configure the client options file (dsm.opt) for each cluster group. Locate the option
file on one of the disk drives that are owned by the cluster group.
About this task
For example, the option file for mscs-cluster-group-a resides on either q: or r:.
68
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Procedure
To configure the dsm.opt file for each cluster group, specify the following options:
nodename
Specify a unique name. For example: mscs-cluster-group-a
domain Specify the drive letters for the drives that are managed by the group. For
example: q: r:
See “Frequently asked questions” on page 75 for information on how to
add a cluster drive to an existing IBM Spectrum Protect cluster scheduler
service resource for backup.
clusternode
Specify the Yes value. If you set the clusternode option to Yes, the client
does the following actions:
1. Checks for a cluster environment (MSCS or VCS).
2. Uses the cluster name instead node name for file space naming and
encryption. This action allows the use of one password file for all nodes
in the cluster.
3. Builds a list of shared volumes and works only with shared volumes.
Backing up local volumes is not permitted if the clusternode option set
to yes.
Important: For the VCS, cluster database processing is skipped because
VCS does not have a cluster database. VCS stores all cluster configuration
information in an ASCII configuration file that is called main.cf, which is
in the path pointed by %VCS_HOME%conf/config on each node in the cluster.
If this file is corrupted, the cluster configuration is also corrupted. Be
careful when you handle this file. The VCS_HOME environment variable
points to the directory where VCS is installed on the node.
passwordaccess
Specify the generate value.
managedservices
(Optional). Specifies whether the IBM Spectrum Protect Client Acceptor
service manages the scheduler, the web client, or both. The examples in
this appendix assume that the client acceptor manages both the web client
and the scheduler for each cluster group. To specify that the client acceptor
manages both the web client and the scheduler, enter the following option
in the dsm.opt file for each cluster group:
managedservices webclient schedule
httpport
Specify a unique TCP/IP port number that the web client uses to
communicate with the client acceptor service that is associated with the
cluster group.
errorlogname
Specify a unique error log name.
Note: This file is not the same error log file that the client uses for other
operations. Ideally, this file is stored on a cluster resource, but at minimum
it should be stored in a location other than the client directory.
schedlogname
Specify a unique schedule log name. It is a best practice to specify a
different log file name for each cluster group.
Chapter 2. Configure the IBM Spectrum Protect client
69
Note: This file is not the same schedule log file that the client uses for
other operations. Ideally, this file is stored on a cluster resource, but at
minimum it should be stored in a location other than the client directory.
Related reference:
“Clusternode” on page 341
“Domain” on page 367
“Errorlogname” on page 392
“Managedservices” on page 454
“Nodename” on page 468
“Passwordaccess” on page 476
“Schedlogname” on page 514
Step 3: Install a Client Acceptor Service and Client Agent:
Install a unique client acceptor service and client agent for each cluster group and
generate a password file.
To install the Client Acceptor Service for group-a from workstation node-1, ensure
that node-1 currently owns group-a and issue the following command:
dsmcutil install cad /name:"tsm client acceptor: group-a"
/clientdir:"c:\Program Files\tivoli\tsm\baclient" /optfile:
q:\tsm\dsm.opt /node:mscs-cluster-group-a /password:nodepassword
/validate:yes /autostart:yes /startnow:no httpport:1582 /cadschedname:
"tsm scheduler service:group-a"
This installs the service on node-1.
To install the client agent service for group-a from workstation node-1, ensure that
node-1 currently owns group-a and issue the following command:
dsmcutil install remoteagent /name:"tsm client agent: group-a"
/clientdir:"c:\Program Files\tivoli\tsm\baclient" /optfile:
q:\tsm\dsm.opt /node:mscs-cluster-group-a /password:nodepassword
/validate:yes /startnow:no /partnername:"tsm client acceptor: group-a"
This installs the remote client agent service on node1.
Note:
1. Do not use the /autostart:yes option.
2. Note that because the /clusternode and /clustername options are not allowed
in this command at this level, it is possible that the password in the Windows
Registry might need to be reset. After installing these three services for each
cluster group, generate an IBM Spectrum Protect password for each cluster
group node name. You need to identify the proper dsm.opt file for each cluster
group node name you authenticate. For example: dsmc query session
-optfile="q:\tsm\dsm.opt"
3. See “Frequently asked questions” on page 75 for information on what to do if a
generic service resource for the cluster group fails because the client acceptor
service has been removed.
Using the Microsoft Cluster Administrator utility or VCS Configuration Editor,
move group-a to node-2. From node-2, issue the same commands to install the
services on node-2 and generate a password file. Repeat this procedure for each
cluster group.
70
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Step 4: Create a network name and IP address resource:
Add a network name and IP address resource for each group that is managed by
the client, using the Microsoft Cluster Administrator or VCS Configuration Editor.
MSCS:
You must use the Microsoft Cluster Administrator utility to add an IP address
resource to each cluster group managed by IBM Spectrum Protect.
About this task
Follow these steps to add an IP address resource:
Procedure
1. Select the group-a folder under the MSCS-Cluster\Groups folder and select File
> New > Resource from the dropdown menu.
2. In the New Resource dialog, enter a unique name in the Name field. For
example: IP address for GROUP-A. Enter a description in the Description field.
Change resource type to IP address in the Resource Type field. Enter the
group name in the Group field. Press Enter.
3. In the Possible Owner dialog, ensure that all cluster nodes appear as possible
owners. Press Enter.
4. In the Dependencies dialog add all physical disk resources as Resource
Dependencies. Press Enter.
5. In the TCP/IP Address dialog, enter appropriate values for address,
subnetmask, and network. Press Enter.
6. Select the new resource from the Microsoft Cluster Administrator utility, and
from the dropdown menu click File and then Bring Online.
Results
You must use the Microsoft Cluster Administrator utility to add a network name to
each cluster group managed by IBM Spectrum Protect.
Follow these steps to add a network name:
1. Select the group-a folder under the MSCS-Cluster\Groups folder and select File
> New > Resource from the dropdown menu.
2. In the New Resource dialog, enter a unique name in the Name field. For
example: Network Name for GROUP-A. Enter a description in the Description
field. Change resource type to Network Name in the Resource Type field. Enter
the group name in the Group field. Press Enter.
3. In the Possible Owner dialog, ensure that all cluster nodes appear as possible
owners. Press Enter.
4. In the Dependencies dialog add the IP address resource and all physical disk
resources as Resource Dependencies. Press Enter.
5. In the Network Name Parameters dialog, enter a network name for GROUP-A.
Press Enter.
6. Select the new resource from the Microsoft Cluster Administrator utility, and
from the dropdown menu click File and then Bring Online.
The IP address and network name to backup the disks in the cluster group are
now resources in the same group.
Chapter 2. Configure the IBM Spectrum Protect client
71
Repeat this procedure for each cluster group managed by IBM Spectrum Protect.
VCS:
You must use the VCS Configuration Editor to add a network name and IP
address resource for each group that is managed by the client.
About this task
Follow these steps to add a network name and IP address resource:
Procedure
1. Open the VCS Configuration Editor. You are prompted with the Build a new
configuration or modify existing configuration window which provides the
following options: New Config - If you select this option you are prompted for
the path for the types.cf file, and Open Existing Config - If you select this
option, the configuration window opens. Click on RESOURCE GROUP you
want to modify.
2. Click on the Edit button and select Add resource. The Add Resource window
opens.
3. Enter the name you want to give the resource in Resource Name field.
4. Select the Resource Type as IP. The attributes of the IP resource type are
displayed.
5. Click the Edit button to modify the resource attributes.
a.
b.
c.
Select the MACAddress attribute and enter the MAC address of adapter you
want the IP to be assigned to.
Select the SubNetMask attribute and enter the subnetmask.
Select the Address attribute and enter the IP address you want to make
High-Availability.
6. When you are finished, close the window. The Configuration window prompts
you whether to save the configuration; click Yes.
Step 5: Create a generic service resource for failover:
This topic guides you through the steps to create a generic service resource for
failover.
Microsoft Cluster Server (MSCS):
To add a Generic Service resource to each cluster group managed by IBM
Spectrum Protect, you must use the Microsoft Cluster Administrator utility.
Procedure
1. Select the group-a folder under the MSCS-Cluster\Groups folder and select File
> New > Resource from the dropdown menu.
2. In the New Resource dialog, enter a unique name in the Name field. For
example: TSM CLIENT ACCEPTOR SERVICE for GROUP-A. Enter a description in the
Description field. Change resource type to Generic Service in the Resource
Type field. Enter the group name in the Group field. Press Enter.
3. In the Possible Owner dialog, ensure that all cluster nodes appear as possible
owners. Press Enter.
4. In the Dependencies dialog add all physical disk resources as Resource
Dependencies. Press Enter.
72
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
5. In the Generic Service Parameters dialog, enter the service name you specified
with the dsmcutil command, in the Service Name field. Leave the Startup
Parameters field blank. Press Enter.
6. In the Registry Replication dialog, add the registry key corresponding to the
IBM Spectrum Protect node name and server name. The format for this key is:
HKEY_LOCAL_MACHINE\SOFTWARE\IBM\ADSM\CurrentVersion\Nodes\nodename\
TSM_server_instance_name, where nodename is the name of your IBM Spectrum
Protect node, and TSM_ server_ instance_name is the name of the IBM Spectrum
Protect server that the node connects to. For example, if the node name is
mscs-cluster-group-a and the IBM Spectrum Protect server name is tsmsv1,
then you should enter the following registry key in the Registry Replication
dialog: HKEY_LOCAL_MACHINE\SOFTWARE\IBM\ADSM\CurrentVersion\Nodes\mscscluster-group-a\tsmsv1. This entry should match an existing key in the
Windows registry.
Results
The client acceptor service is now a resource in the same group. If the group is
moved (failed) to the other nodes in the cluster, the service should correctly fail
over between the cluster nodes and notify both cluster nodes of automatic
password changes.
Note:
1. If you manually change the password, you must stop the remote agent and the
client acceptor services, regenerate the password, and restart the client acceptor
service (do not restart the remote agent). You can generate the password by
running this command:
dsmc query session -optfile="q:\tsm\dsm.opt"
2. See “Frequently asked questions” on page 75 for information on what to do if a
generic service resource for the cluster group fails because the client acceptor
service has been removed.
Veritas Cluster Server (VCS):
To add a Generic Service resource to each cluster group managed by the
backup-archive client, you must use the VCS Configuration Editor.
Procedure
1. Open the VCS Configuration Editor. You are prompted with the Build a new
configuration or modify existing configuration window which provides the
following options: New Config - If you select this option you are prompted for
the path for the types.cf file, and Open Existing Config- If you select this
option, the configuration window opens. Click on RESOURCE GROUP you
want to modify.
2. Click on the Edit button and select Add resource. The Add Resource window
opens.
3. Enter the name you want to give the resource in Resource Name field.
4. Select the Resource Type as GenericService. The attributes of the
GenericService resource type are displayed.
5. Click the Edit button to modify the resource attributes.
6. Select the ServiceName attribute and enter the name of scheduler service that
you want to make High-Availability.
Chapter 2. Configure the IBM Spectrum Protect client
73
7. When you are finished, close the window. The Configuration window prompts
you whether to save the configuration; click Yes.
Results
Use the VCS Configuration Editor to configure the registry replication resource, as
follows:
1. Open the VCS Configuration Editor. You are prompted with the Build a new
configuration or modify existing configuration window which provides the
following options: New Config - If you select this option you are prompted for
the path for the types.cf file, and Open Existing Config - If you select this
option, the configuration window opens. Click on RESOURCE GROUP you
want to modify.
2. Click on the Edit button and select Add resource. The Add Resource window
opens.
3. Enter the name you want to give the resource in Resource Name field.
4. Select the Resource Type as RegRep. The attributes of the RegRep resource type
are displayed.
5. Click the Edit button to modify the resource attributes.
6. Select the MountResName attribute and enter the shared disk on which you want
to store the registry keys.
7. When you are finished, close the window. The Configuration window prompts
you whether to save the configuration; click Yes.
The client acceptor service is now a resource in the same group. If the group is
moved (failed) to the other nodes in the cluster, the service should correctly fail
over between the cluster nodes and notify both cluster nodes of automatic
password changes.
Note:
1. If you manually change the password, you must stop the remote agent and the
client acceptor services, regenerate the password, and restart the client acceptor
service (do not restart the remote agent). You can generate the password by
running this command: dsmc query session -optfile="q:\tsm\dsm.opt"
2. See “Frequently asked questions” on page 75 for information on what to do if a
generic service resource for the cluster group fails because the client acceptor
service has been removed.
Step 6: Start the web client:
This topic guides you through the steps to start the web client to use cluster
services.
Procedure
1. Start the Client Acceptor Service for each resource group on each node.
2. To start the web client, point your browser at the IP address and httpport
specified for the Resource Group. For example, if you used an IP address of
9.110.158.205 and specified an httpport value of 1583, open the web address:
http://9.110.158.205:1583.
74
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Results
Alternatively, you can point your browser at the network name and httpport. For
example, if you used a network name of cluster1groupa and specified an http port
value of 1583, open the web address: http://cluster1groupa:1583.
Note that the web client connects to whichever workstation currently owns the
resource group. The web client displays all of the local file spaces on that
workstation, but to ensure that the files are backed up with the correct node name
you should only back up the files for the resource group.
When failing back to the original node after a failover scenario, ensure that the
remote agent service on the original workstation is stopped. The remote agent can
be stopped manually, or it stops automatically after 20 to 25 minutes of inactivity.
Because the remote agent is configured for manual startup, it will not start
automatically if the workstation on which it was running is rebooted.
Frequently asked questions
This section contains some frequently asked questions and answers about using
cluster services.
About this task
Q: How do you configure a shortcut for the backup-archive client GUI in a
cluster environment?
A: To configure a backup-archive client GUI icon (for example on the
Windows desktop) that you can use to manage operations for a cluster
resource group on a Windows cluster, perform the following steps:
Procedure
1. Right-click on the desktop and select New > Shortcut.
2. In the window that appears, find the path to the dsm.exe executable (located by
default in directory C:\program files\tivoli\tsm\baclient\). If you type the
path in, instead of using the Browse button, the path should be enclosed in
double quotation marks. For example: "C:\Program Files\tivoli\tsm\
baclient\dsm.exe"
3. After you enter the path and executable in the text field, add the following
information after the closing double quotation marks (add a space between the
double quotation marks and the following): -optfile="x:\path\to\cluster\
dsm.opt". This identifies the proper IBM Spectrum Protect cluster options file
you want to use. This example assumes that the cluster options file is located in
the folder "x:\path\to\cluster\" and has the file name dsm.opt.
4. The complete line in the text field now should look similar to the following:
"C:\Program Files\tivoli\tsm\baclient\dsm.exe" -optfile="x:\path\to\
cluster\ dsm.opt".
5. Click Next and give this shortcut a meaningful name, such as Backup-Archive
GUI: Cluster Group X.
6. Click Finish. A desktop icon should now be available. The properties of this
icon shows the following correct Target, as noted in step 4: "C:\Program
Files\tivoli\tsm\baclient\dsm.exe" -optfile="x:\path\to\cluster\
dsm.opt".
Chapter 2. Configure the IBM Spectrum Protect client
75
Results
Q: How do you verify that a scheduler service setup in a cluster environment
works?
A: Setting up a scheduler service for a Microsoft clustered resource group
can be time consuming, and can be lengthened by mistakes and errors in
the syntax of the commands used to set them up. Carefully entering the
commands and recording important information about the cluster setup
can minimize setup time. To successfully set up a scheduler service for
Microsoft cluster environments:
1. Carefully read the information in this appendix for correct syntax on
setting up a scheduler service for a cluster group.
2. Ensure that the proper dsm.opt file(s) are used for the cluster. In a
typical normal workstation, only one dsm.opt file is used. In a clustered
environment, additional dsm.opt files are required. Each cluster group
that is backed up must have its own dsm.opt file. A cluster group is
any group listed under the GROUPS folder of the cluster tree within
the Microsoft Cluster Administrator utility or VCS Configuration Editor.
3. Understand what the following dsmcutil.exe options mean, and when
to use them. (1) /clustername:clustername - Specifies the name of the
Microsoft cluster, where clustername is the name at the top level of the
tree within the Microsoft Cluster Administrator utility or VCS
Configuration Editor. Use this option with dsmcutil.exe, only when
installing a scheduler service for a cluster group. Do not specify a
clustername of more than 64 characters. If you specify more than 256
characters and you are using Veritas Storage Foundation with High
Availability or a Microsoft Cluster Server configuration, you might not
be able to install or start the IBM Spectrum Protect scheduler service,
and (2) /clusternode:yes - Specifies that you want to enable support
for cluster resources. Use this option in the dsm.opt file for each cluster
group, and with dsmcutil.exe when installing a scheduler service for a
cluster group.
4. Common mistakes are made in typing the syntax of the dsmcutil.exe
command. An easy way to prevent such syntax problems is to create a
temporary text file which is accessible to the cluster group (for instance,
place it on a cluster drive belonging to that cluster group), and type the
syntax into this file. When needed, cut and paste this syntax from the
file to the DOS prompt and press the Enter key. It guarantees the
consistency of the command syntax regardless of which computer you
enter it on.
5. If the scheduler service is failing to restart after a failover of the cluster
group occurs (using the MOVE GROUP option in Cluster
Administrator, for example), there might be potential password
synchronization problems between the two cluster workstations. To
verify that the passwords are the same, browse to this registry key on
each workstation and compare the encrypted password value:
HKEY_LOCAL_MACHINE\SOFTWARE\IBM\ADSM\CurrentVersion\Nodes\
nodename\servername.
If the encrypted keys for this node do not match between the two
cluster workstations, there is a password mismatch on one or both of
the two workstations. To correct this problem, use the dsmc.exe
program to update the password manually on both workstations.
For example, assume that the Y: drive is part of the cluster group that
is experiencing problems being backed up with a scheduler service. The
Y:\tsm directory contains the dsm.opt file for this cluster group in the
76
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Y:\tsm directory. To update the password manually, enter the following
command on both workstations: dsmc -optfile=Y:\tsm\dsm.opt
-clusternode=yes, and enter the following command to receive the
prompt for the node name and password: dsmc q se
-optfile=Y:\tsm\dsm.opt -clusternode=yes.
Verify that the passwords are synchronized, and restart the scheduler
service to verify if the password remains consistent. If password
mismatching continues, it might be due to a syntax error in the original
dsmcutil.exe command that was used to install the scheduler service.
In this case, uninstall the scheduler service (using the dsmcutil remove
/name:schedule_name command) and reinstall the scheduler service
again (using the shared text file syntax as shown previously).
Q: How do you add a cluster drive to an existing cluster scheduler service
resource for backup?
A: To add an additional cluster drive resource to an existing
backup-archive client cluster scheduler service, the following components
must be modified or updated to properly reflect this change:
1. The cluster drive resource, and any related resource shares, must exist
and reside within the designated cluster group as defined in the
Microsoft Cluster Administrator utility or VCS Configuration Editor.
The designated cluster group must already contain the cluster
scheduler service resource for which this new drive is added.
2. The dsm.opt file used by the designated cluster scheduler service
resource must be modified to include the additional cluster drive
resource on the domain option statement. For example, if you want to
add the R:\ drive, and the domain statement currently identifies cluster
drives Q: and S:, update the domain statement in your dsm.opt file as
follows: domain Q: S: R:.
3. You must modify the cluster scheduler service resource properties to
include this file in the list of dependent resources needed to bring this
resource online. This ensures that the cluster drive resource being
added is included in the new backups, and for backups which run after
a failover occurs.
After the changes above are made, bring the cluster scheduler service
resource offline, and back online. The schedule should now process this
additional resource for backups.
Q: The client acceptor service has been removed and now the generic service
resource for the cluster group is failing. How can this be corrected?
A: The client acceptor can be used to control the scheduler, the web client,
or both for a cluster environment. If the client acceptor is removed without
updating the generic cluster resource, the resource fails. To correct this:
1. Verify which scheduler service was controlled by the client acceptor.
2. Using the Microsoft Cluster Administrator utility or VCS Configuration
Editor, go to the properties window of the service resource, select the
Parameters tab, and enter the name of the correct scheduler service to
use.
3. Repeat steps one and two for each cluster group that was managed by
the specific client acceptor.
4. To test the updated service resource, initiate a failure of the resource. If
the resource comes back online with no failures, the update has worked
properly.
Chapter 2. Configure the IBM Spectrum Protect client
77
Note: To fully disable the client acceptor service, remove the
managedservices option from the cluster group dsm.opt file or comment it
out.
Configuring online-image backup support
If the online image feature is configured, the backup-archive client performs a
snapshot-based image backup, during which the real volume is available to other
system applications.
About this task
A consistent image of the volume is maintained during the online image backup.
To configure online image backup, perform the following steps:
Procedure
1. Select Utilities > Setup Wizard from the backup-archive client GUI main
window. The Client Configuration Wizard panel appears.
2. Select Help me configure Online Image Support and click Next. The Online
Image Support Wizard panel appears.
3. Click Volume Shadowcopy Services (VSS) and then click Next. To disable
online image support, click None (Disable online image support).
4. Click Finish button to complete the setup.
5. Complete each panel in the wizard and click the Next to continue. To return to
a previous panel, click the Back. To display help information for a panel, click
the help icon.
Results
To set preferences for open file support, use the Include-Exclude tab on the IBM
Spectrum Protect Preferences editor. You can set these options for all volumes or
for individual volumes using the include.fs option: snapshotproviderfs,
presnapshotcmd, postsnapshotcmd.
Related concepts:
“Client options reference” on page 317
“Image backup” on page 156
Configuring Open File Support
You configure Open File Support (OFS) after you install the Window client.
About this task
If the Open File Support feature is configured, the backup-archive client performs a
snapshot-based, file-level operation, during which the real volume is available to
other system applications. A consistent image of the volume is maintained during
the operation.
To configure OFS, perform the following steps:
78
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Procedure
1. Start the Windows client Java GUI (run dsm.exe).
2. Select Utilities > Setup Wizard.
3. Select Help me configure Online Image Support and click Next.
4. Click Next again.
5. Select the VSS snapshot provider to enable Open File Support or select None
to perform normal (non-snapshot) backups of the files on your volume; then
click Next.
6. Click Apply and then click Finish.
Results
To set preferences for open file support, use the Include-Exclude tab on the
Preferences editor. You can set these options for all volumes or for individual
volumes using the include.fs option: snapshotproviderfs, presnapshotcmd,
postsnapshotcmd
Related concepts:
“Client options reference” on page 317
Configuring NetApp and IBM Spectrum Protect for snapshot difference
incremental backups
You must configure the NetApp file server connection information to run the
snapshot difference incremental backup command on the backup-archive client.
You must also use the set password command to specify the file server host name,
and the password and user name that is used to access the file server.
Procedure
1. Establish a console session on the NetApp filer and define a new user on the
file server by using the following steps:
a. Add the user ID to a group that permits users to log in to the file server
with http and running API commands.
b. From the file server, enter the following command to list the user ID to
verify the settings and verify that the output is similar:
useradmin user list snapdiff_user
Name: snapdiff_user
Info:
Rid: 131077
Groups: snapdiff_group
Full Name:
For 7-mode NetApp filers:
Allowed Capabilities: login-http-admin,api-*
For clustered-data ONTAP NetApp filers, the only capability that is
required is ontapapi with the admin role.
c. If the security.passwd.firstlogin.enable option for the user ID on the
NetApp server is set to on, ensure that all groups have the login-telnet
and cli–passwd* capabilities.
Tip: When security.passwd.firstlogin.enable option is enabled, the user
ID is set to expired when created. The user cannot run any commands,
Chapter 2. Configure the IBM Spectrum Protect client
79
including snapshot differential incremental, until their password is changed.
Users in groups that do not have these capabilities cannot log in to the
storage system. For information about defining a user ID and a password
on the NetApp file server, see the NetApp documentation.
2. Configure the NetApp Data ONTAP built-in HTTP server to allow remote
administrative sessions to the NetApp filer.
a. If you plan to use a plain HTTP connection for snapshot differential
backups, turn on the httpd.admin.enable option on the NetApp filer.
b. If you plan to use a secure HTTPS connection for snapshot differential
backups (by specifying the -snapdiffhttps option), turn on the
httpd.admin.ssl.enable option on the NetApp filer.
c. From the IBM Spectrum Protect client node, test the connection between the
IBM Spectrum Protect client computer and the NetApp ONTAP server to
ensure that firewalls or other NetApp configuration options do not prevent
you from connecting to the NetApp server.
Tip: See the NetApp ONTAP documentation for instructions on how to test
the connection.
3. Export the NetApp volumes and consider the following settings:
Tip: See the NetApp documentation for details on exporting the NetApp
volumes for use with Windows.
v Map the NetApp volumes by using CIFS.
v Ensure the NetApp volumes have the NTFS security setting.
4. Set the user ID, and password on the backup-archive client for the user ID that
you created in step 1 on page 79 using the following steps:
a. Log on as the user with read/write access to the CIFS share.
b. From the backup-archive client command line, enter the following
command:
dsmc set password –type=filer my_file_server snapdiff_user newPassword
Substitute the following values:
my_file_server
This value is the fully qualified host name of your NetApp file
server.
snapdiff_user
This value is the user ID that you created in step 1 on page 79.
newPassword
This value is the password for the user ID that you created in step 1
on page 79.
Related tasks:
“Protecting clustered-data ONTAP NetApp file server volumes” on page 81
Related reference:
“Snapdiff” on page 528
“Snapdiffhttps” on page 534
“Createnewbase” on page 350
80
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Protecting clustered-data ONTAP NetApp file server volumes
You can create a snapshot differential incremental backup of a volume on a
NetApp file server that is part of a clustered-data ONTAP configuration (c-mode
file server).
Before you begin
v Complete the procedure in “Configuring NetApp and IBM Spectrum Protect for
snapshot difference incremental backups” on page 79.
v Ensure that the clustered-data ONTAP environment is correctly set up by the
NetApp storage virtual machine administrator.
Restriction: IBM Spectrum Protect support for snapshot differential incremental
backups of clustered-data ONTAP volumes is supported only on NetApp ONTAP
8.2.1 and later versions.
About this task
In a clustered-data ONTAP environment, storage virtual machines (also referred to
as data vServers) contain data volumes that can be protected by the
backup-archive client.
A storage virtual machine consists of a single infinite volume or one or more flex
volumes. Volumes are accessed remotely using file sharing (CIFS on Windows
operating systems, NFS on Linux operating systems).
The storage virtual machines are managed by the cluster management filer, which
is the physical filer (the c-mode filer) on which the storage virtual machines reside.
The backup client is installed on the remote machine that accesses the volumes.
The backup-archive client must be configured with credentials for the NetApp
c-mode filers that are being accessed for backup operations.
Requirements:
v The following information is required for this procedure:
– The host name or IP address of the cluster management filer.
– The host name or IP address of the storage virtual machine.
– The storage virtual machine name.
– The cluster management filer credentials (user name and password).
v The cluster management filer user that is configured by the client must be
assigned the ontapapi capability with the role of admin.
The ontapapi capability does not allow interactive access to the filer with
methods such as telnet, ssh, or http/https. No other user capabilities are
required to run snapshot differential incremental backups.
Procedure
Complete the following steps on the remote machine where the backup-archive
client is installed:
1. Configure the backup-archive client with the cluster management filer
credentials. Use the dsmc set password command to store the credentials of the
management filer that is associated with the storage virtual machine. For
example, enter the following command:
Chapter 2. Configure the IBM Spectrum Protect client
81
dsmc set password –type=filer management_filer_hostname
management_filer_username management_filer_password
Where:
management_filer_hostname
The host name or IP address of the cluster management filer.
management_filer_username
The user name of the cluster management filer.
management_filer_password
The password for user of the management filer.
Tip: The cluster management filer password is encrypted when it is stored by
the backup-archive client.
2. Associate each storage virtual machine with the management filer with the
dsmc set netappsvm command. For example, enter the following command:
|
|
|
dsmc set netappsvm storage_virtual_machine_hostname
management_filer_hostname storage_virtual_machine_name
|
|
|
storage_virtual_machine_hostname
The host name or IP address of the storage virtual machine that is used
to mount volumes to back up.
|
|
management_filer_hostname
The host name or IP address of the cluster management filer.
|
|
storage_virtual_machine_name
The name of the storage virtual machine.
Where:
Note: The host name or IP address of the storage virtual machine that is used
to mount volumes must be consistent with what is specified in the dsmc set
commands. For example, if the volumes are mounted with a storage virtual
machine IP address, the IP address (not the host name) must be used in the
dsmc set commands. Otherwise, client authentication with the cluster
management filer fails.
You need only to specify the dsmc set netappsvm command once for each
storage virtual machine. If the storage virtual machine is moved to a different
cluster management filer, you must use the command to update the associated
cluster management filer host name.
3. Map the volumes to drive letters. For example, enter the following command
for each storage virtual machine:
net use y: \\storage_virtual_machine_hostname domain_name\CIFS_share_name
Where:
y:
The drive to map the volume to.
storage_virtual_machine_hostname
The host name or IP address of the storage virtual machine.
domain_name\CIFS_share_name
The CIFS share that is defined on the filer on the volume being backed
up.
4. Start a full progressive incremental backup of a flex or infinite volume.
By default, HTTP access to the NetApp file server is not enabled. If you did not
configure your file server to allow access by using HTTP, use the
82
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
backup-archive client snapdiffhttps option to enable access to the cluster
management server with the HTTPS protocol.
For example, on Windows clients, enter the following command:
dsmc incr y: -snapdiff -snapdiffhttps
Tip: You need only to run the full progressive incremental backup once. After
this backup is successfully completed, run differential backups in future backup
operations.
5. Start a snapshot differential backup of the flex or infinite volume.
For example, on Windows clients, enter the following command:
dsmc incr y: -snapdiff -snapdiffhttps
Example
A backup-archive client user wants to complete a snapshot differential incremental
backup of the volumes on a c-mode file server. The user is using a Windows
backup-archive client to complete the backup and the volumes are mounted as
CIFS shares. The c-mode filer configuration is as follows:
ONTAP 8.31 management filer
Hostname: netapp1mgmt.example.com
User: netapp1mgmt_user
Password: pass4netapp1mgmt
CIFS Domain Controller: WINDC
Domain User: domainuser
Flex volume storage virtual machine
Hostname: netapp1-v1.example.com
Storage virtual machine name: netapp1-client1
CIFS share: demovol
Volume name: demovol
Infinite volume storage virtual machine
Hostname: netapp1-v4.example.com
Storage virtual machine name: netapp1-infiniteVolume1
CIFS Share: InfiniteVol
The user completes the following steps on the backup-archive client:
1. Configure the client with the management filer credentials by issuing the
following command:
dsmc set password –type=filer netapp1mgmt.example.com netapp1mgmt_user
pass4netapp1mgmt
2. Define storage virtual machine associations for each storage virtual machine
with the following commands:
|
|
dsmc set netappsvm netapp1-v1.example.com netapp1mgmt.example.com
netapp1-client1
|
|
dsmc set netappsvm netapp1-v4.example.com netapp1mgmt.example.com
netapp1-infiniteVolume1
3. Map remote volumes to drive letters for each storage virtual machine:
net use y: \\netapp1-v1.example.com\demovol WINDC\domainuser
net use z: \\netapp1-v4.example.com\InfiniteVol WINDC\domainuser
4. Run a full progressive incremental backup of the flex volume and infinite
volume:
dsmc incr y: -snapdiff -snapdiffhttps
dsmc incr z: -snapdiff -snapdiffhttps
Chapter 2. Configure the IBM Spectrum Protect client
83
You need only to run the full progressive incremental backup once. After this
backup is successfully completed, run differential backups in future backup
operations.
5. Run a snapshot differential backup of the flex volume and infinite volume:
dsmc incr y: -snapdiff -snapdiffhttps
dsmc incr z: -snapdiff -snapdiffhttps
SnapMirror support for NetApp snapshot-assisted progressive
incremental backup (snapdiff)
You can use NetApp's SnapDiff backup processing in conjunction with NetApp's
SnapMirror replication to back up NetApp source or destination filer volumes.
In a NetApp SnapMirror environment, data that is on volumes attached to the
primary data center are mirrored to volumes attached to a remote server at a
disaster recovery site. The NetApp filer in the primary data center is called the
source filer; the NetApp filer at the disaster recovery site is called the destination
filer. You can use the backup-archive client to create snapshot differential backups
of the source or destination filer volumes.
Scenario: Back up data on a source filer volume
You can configure the backup archive client to back up data from the source filer
volumes. This scenario requires you to configure a backup-archive client node such
that it has access to the NetApp source filer volumes by using CIFS shares to
mount the filer volumes.
For example, assume a configuration where the source filer is named ProdFiler.
Assume that a volume named UserDataVol exists on ProdFiler filer and that the
volume is accessible by using CIFS from a backup-archive client node. Assume that
the share is mounted as UserDataVol_Share.
When you initiate a snapshot differential backup, the NetApp filer creates a new
differential snapshot on the volume that is being backed up. That differential
snapshot is compared with the base (previous) snapshot. The base snapshot name
was registered on the IBM Spectrum Protect server when the previous backup was
completed. The contents of that base snapshot are compared to the differential
snapshot that is created on the source filer volume. Differences between the two
snapshots are backed up to the server.
The following command is used to initiate the snapshot differential backup. The
command is entered on the console of a client node that is configured to access
and protect the source filer volumes. Because this command is issued to back up
volumes on a source filer, a new snapshot (the differential snapshot) is created and
the snapshot registered on the IBM Spectrum Protect server is used as the base
snapshot. Creating both the differential and base snapshots is the default behavior;
the -diffsnapshot=create option is a default value, and it does not need to be
explicitly specified on this command.
dsmc incr \\ProdFiler\UserDataVol_Share -snapdiff -diffsnapshot=create
Back up data on a destination filer
A more typical configuration is to offload the backups from the source filer by
creating backups of the source volumes by using the replicated volume snapshots
stored on the destination filer. Ordinarily, backing up a destination filer presents a
84
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
problem because creating a snapshot differential backup requires that a new
snapshot must be created on the volume that you are backing up. The destination
filer volumes that mirror the contents of the source volumes are read only
volumes, so snapshots cannot be created on them.
To overcome this read-only restriction, client configuration options are provided to
allow you to use the existing base and differential snapshots on the read-only
destination volume to back up changes to the IBM Spectrum Protect server.
Like in the source filer scenario, the destination filer volumes are accessed by using
CIFS shares.
Snapshot differential options summary
The useexistingbase option causes the most recent snapshot on the volume to be
used as the base snapshot, when a base snapshot must be established. A new base
snapshot is established when any of the following conditions are true:
v When this backup is the initial backup.
v When createnewbase=yes is specified.
v When the base snapshot that was registered by a previous differential snapshot
no longer exists, and an existing snapshot that is older than the missing base
snapshot does not exist.
If this option is not specified, a new snapshot is created on the volume that is
being backed up. Because destination filer volumes are read-only volumes,
useexistingbase must be specified when creating snapshot differential backups of
destination filer volumes. If useexistingbase is not specified, snapshot differential
backups of a destination filer volume fail because the new snapshot cannot be
created on the read-only volume.
When backing up destination filer volumes, use both the useexistingbase option
and the diffsnapshot=latest option to ensure that the most recent base and most
recent differential snapshots are used during the volume backup.
You use the basesnapshotname option to specify which snapshot, on the destination
filer volume, to use as the base snapshot. If you do not specify this option, the
most recent snapshot on the destination filer volume is used as the base snapshot.
You can use wildcards to specify the name of the base snapshot.
You use the diffsnapshotname option to specify which differential snapshot, on the
destination filer volume, to use during a snapshot differential backup. This option
is only specified if you also specify diffsnapshot=latest. You can use wildcards to
specify the name of the differential snapshot.
The diffsnapshot=latest option specifies that you want to use the latest snapshot
that is found on the file server as the source snapshot.
Additional information about each of these options is provided in the Client options
reference topics.
Snapshot differential backup command examples
In the examples that follow, assume that volumes on a source filer are replicated,
by using NetApp’s SnapMirror technology, to a disaster recovery filer (host name
is DRFiler). Because the DRFiler volumes are read only, you use the options to
Chapter 2. Configure the IBM Spectrum Protect client
85
specify which of the replicated snapshots that you want to use as the base
snapshot, and which of the snapshots you want to use as the differential snapshot.
By specifying the snapshots to use when creating a snapshot differential backup of
a destination filer, no attempt is made to create a snapshot on the read-only
volumes.
The following commands are used to initiate snapshot differential backups. Most
of these commands create snapshot differential backups by using snapshots stored
on the destination filer volumes. When backing up from a destination filer volume,
be sure to include the -useexistingbase option, because that option prevents
attempts to create a new snapshot on the read-only destination filer volumes.
Example 1: Back up a destination filer by using default nightly backups that
were created by the NetApp snapshot scheduler
dsmc incr \\DRFiler\UserDataVol_Share -snapdiff -useexistingbase
-diffsnappshot=latest -basesnapshotname=”nightly.?”
You can use a question mark (?) to match a single character. In this
example, -basesnapshotname=nightly.? uses the latest base snapshot that
is named “nightly.”, followed by a single character (for example: nightly.0,
nightly.1, and so on).
Example 2. Back up a destination filer volume by using snapshots created
manually (not created by the NetApp snapshot scheduler)
dsmc incr \\DRFiler\UserDataVol_Share –snapdiff –useexistingbase
–diffsnapshot=latest –basesnapshotname=”share_vol_base?”
–diffsnapshotname=”share_vol_diff?”
This example also uses the question mark (?) wildcard to illustrate the
syntax if the base and differential snapshot names have different numbers
as part of the name.
Example 3. Back up a destination filer volume, and specify which snapshots to
use for the base and differential snapshots
dsmc incr \\DRFiler\UserDataVol_Share -snapdiff -useexistingbase
-diffsnapshot=latest -basesnapshotname=”share_vol_base”
–diffsnapshotname=”share_vol_diff_snap”
Example 4: Back up script-generated snapshots that use a naming convention
In this example, a script that is running on the NetApp filer adds a date
and time stamp to the snapshot names. For example, a snapshot created on
November 3, 2012 at 11:36:33 PM is named
UserDataVol_20121103233633_snapshot. You can use wildcards with the
options to select the most recent base and differential snapshots. For
example:
dsmc incr \\DRFiler\UserDataVol_Share -snapdiff -useexistingbase
-basesnapshotname=”UserDataVol_Share_*_snapshot” –diffsnapshot=latest
-diffnsnapshotname=”UserDataVol_Share_*snapshot
-useexistingbase selects the most recent base snapshot. Adding an asterisk
(*) wildcard to -basesnapshotname selects the most recent base snapshot
that follows the script-naming convention. The -diffsnapshot=latest
option suppresses the creating of a new differential snapshot and
-diffsnapshotname= selects the most recent existing differential snapshot
that follows the script-naming convention. (The asterisks wildcards match
any string).
Example 5: Perform a snapshot differential backup by using an existing
differential snapshot that exists on the source filer
To use an existing differential snapshot that exists on the source filer, use
86
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
the -diffsnapshot=latest to prevent the creation of a new differential
snapshot. Also use the -diffsnapshotname option to specify which existing
differential snapshot to use. The snapshot you specify is compared to the
base snapshot, which was registered in the IBM Spectrum Protect server
database when the last backup was created. For example:
dsmc incr \\ProdFiler\UserDataVol_Share -snapdiff -diffsnapshot=latest
-diffsnapshotname=”share_vol_diff_snap”
Register your workstation with a server
Before you can use IBM Spectrum Protect, you must set up a node name and
password and your node must be registered with the server.
The process of setting up a node name and password is called registration. Two
types of registration are available, open and closed.
Your IBM Spectrum Protect server administrator chooses the type of registration
for your site.
|
|
|
|
Restriction: Beginning with the IBM Spectrum Protect Version 8.1.2 server, open
registration is no longer available. You must use closed registration. Open
registration is available only for the IBM Spectrum Protect V8.1.1, V8.1.0, V7.1.7 or
earlier server.
If you plan to use the web client, you must have an administrative user ID with
system privilege, policy privilege, client access authority, or client owner authority.
When a new node is registered, the server administrator must create an
administrative user ID that matches the node name. By default, this node has client
owner authority.
The IBM Spectrum Protect server administrator must specify the userid parameter
with the REGISTER NODE server command:
REGISTER NODE node_name password userid=user_id
where the node name and the administrative user ID must be the same. For
example:
REGISTER NODE node_a mypassw0rd userid=node_a
Closed registration
With closed registration, the IBM Spectrum Protect administrator must register
your workstation as a client node with the server. If your enterprise uses closed
registration, you must provide some information to your IBM Spectrum Protect
administrator.
About this task
You must provide the following items to your IBM Spectrum Protect administrator:
v Your node name (the value returned by the hostname command, the name of
your workstation, or the node name you specified with the nodename option). If
you do not specify a node name with the nodename option, the default login ID
is the name that the hostname command returns.
v The initial password you want to use, if required.
v Contact information, such as your name, user ID, and phone number.
Your IBM Spectrum Protect administrator defines the following for you:
Chapter 2. Configure the IBM Spectrum Protect client
87
v The policy domain to which your client node belongs. A policy domain contains
policy sets and management classes that control how IBM Spectrum Protect
manages the files you back up and archive.
v Whether you can compress files before sending them to the server.
v Whether you can delete backup and archive data from server storage.
Open registration
With open registration, a system administrator can register your workstation as a
client node with the IBM Spectrum Protect Version 8.1.1, V8.1.0, V7.1.7 or earlier
server.
|
|
|
About this task
The first time you start a session, you are prompted for information necessary to
register your workstation with the IBM Spectrum Protect server that is identified in
your client options file. You need to supply your node name, a password, and
contact information.
When you use open registration:
v Your client node is assigned to a policy domain named standard.
v You can delete archived copies of files from server storage, but not backup
versions of files.
If necessary, your IBM Spectrum Protect administrator can change these defaults
later.
Creating an include-exclude list
If you do not create an include-exclude list, the backup-archive client considers all
files for backup services and uses the default management class for backup and
archive services.
About this task
This is an optional task, but an important one.
You can create an include-exclude list to exclude a specific file or groups of files
from backup services, and to assign specific management classes to files. The client
backs up any file that is not explicitly excluded. You should exclude IBM Spectrum
Protect client directories from backup services. You can use the query inclexcl
command to display a list of include and exclude statements in the order they are
examined when determining whether an object is to be included.
Specify your include-exclude list in your client options file (dsm.opt). The
include-exclude list can also go into a separate file, which is referred to by the
inclexcl option. The include-exclude statements are not case-sensitive.
The client options file, dsm.opt, must be in a non-Unicode format. However, if you
are using a separate include-exclude file, it can be in Unicode or non-Unicode
format.
When the client processes include-exclude statements, the include-exclude
statements within the include-exclude file are placed at the position occupied by
the inclexcl option in dsm.opt, in the same order, and processed accordingly.
88
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Procedure
You can use the following methods to create an include-exclude list or specify an
include-exclude file:
v You can add include-exclude statements in the backup-archive client GUI or web
client directory tree. The online help provides detailed instructions.
1. Open the Edit menu and select Client Preferences. In the Preferences dialog,
select the Include/Exclude tab. You can specify an INCLEXCL file using the
Preferences editor. However, you cannot create the INCLEXCL file using the
Preferences editor.
2. Create the include-exclude list manually, following the steps listed.
v You can create an include-exclude list manually by performing the following
steps:
1. Determine your include and exclude requirements.
2. Locate the client options file
3. Important: Group your include-exclude options together in your client
options file.
4. Enter your include and exclude statements. The client evaluates all
exclude.dir statements first (regardless of their position within the
include-exclude list), and removes the excluded directories and files from the
list of objects available for processing. All other include-exclude statements
are processed from the bottom of the list up. Therefore, it is important to
enter all your include-exclude statements in the proper order. For example, in
the following include-exclude list the includefile.txt file is not backed up:
include c:\test\includefile.txt
exclude c:\test\...\*
However, in the following include-exclude list the includefile.txt file is
backed up:
exclude c:\test\...\*
include c:\test\includefile.txt
5. Save the file and close it.
6. Restart the client and the scheduler and client acceptor services to enable
your include-exclude list.
Related concepts:
“System files to exclude” on page 92
Chapter 9, “Storage management policies,” on page 261
Related reference:
“Inclexcl” on page 425
Include-exclude options
This topic provides brief descriptions of the include and exclude options that you
can specify in your client options file, a minimum include-exclude list that
excludes system files, a list of supported wildcard characters, and examples of how
you might use wildcard characters with include and exclude patterns.
Exclude file spaces and directories
Use exclude.dir statements to exclude all files and subdirectories in the specified
directory from processing.
The backup-archive client evaluates all exclude.dir statements first (regardless of
their position within the include-exclude list), and removes the excluded directories
Chapter 2. Configure the IBM Spectrum Protect client
89
and files from the list of objects available for processing. The exclude.dir
statements override all include statements that match the pattern.
Table 7 lists the options you can use to exclude file spaces and directories from
processing.
Table 7. Options for excluding file spaces and directories
Option
Description
exclude.dir
Excludes a directory, its files, and all its subdirectories and their files
“Exclude options” from backup processing. For example, the statement exclude.dir
on page 395
c:\test\dan\data1 excludes the c:\test\dan\data1 directory, its files,
and all its subdirectories and their files. Using the exclude.dir option is
preferable over the standard exclude option to exclude large directories
containing many files that you do not want to back up. You cannot use
include options to override an exclude.dir statement. Only use
exclude.dir when excluding an entire directory branch.
If you define an exclude statement without using a drive letter, such as
exclude.dir dirname, this excludes from processing any directory
named dirname on any drive.
v The following examples illustrate valid exclude.dir statements:
Exclude directory C:\MyPrograms\Traverse and its files and
subdirectories:
exclude.dir c:\MyPrograms\Traverse
Exclude all directories below c:\MyPrograms\Traverse. Note that
directory C:\MyPrograms\Traverse and the files immediately below
C:\MyPrograms\Traverse is eligible for backup.
exclude.dir c:\MyPrograms\Traverse\*
Exclude all directories whose names begin with temp, and are located
within directory x:\documents and settings and its subdirectories,
where x: is any drive.
exclude.dir "*:\documents and settings\...\temp*"
Exclude all directories whose names begin with temp, regardless of
the drive or directory in which they reside:
exclude.dir temp*
The following example is invalid because it ends with a directory
delimiter:
exclude.dir c:\MyPrograms\Traverse\
v Use the following statements to exclude drive x: altogether from
backup processing. Note that the drive root (x:\) is backed up, but
all other files and directories on x: is excluded.
exclude x:\*
exclude.dir x:\*
v An alternative method for excluding an entire drive from domain
incremental backup is to use a domain statement to exclude the
drive. For example:
domain -x:
This alternative still permits selective and explicit incremental backup
processing of files on x:. For example:
dsmc s x:\ -subdir=yes
dsmc i x:
dsmc i x:\MyPrograms\ -subdir=yes
90
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Include-exclude statements for networked file systems
Include-exclude statements that involve networked file systems (remote drives)
must be written in the UNC format.
In the following example Z: is a mapped drive to a remote file system on
vista.example.com.
The old format would be to exclude \dir\dir2 on the remote file system, as in this
example:
EXCLUDE.DIR "Z:\dir1\dir2"
Here is an example of the new format using UNC:
EXCLUDE.DIR "\\vista.example.com\d$\dir1\dir2"
The include-exclude statements written in the old format will not be recognized by
the client.
Exclude files and directories from a journal-based backup
There are two methods of excluding files and directories from a journal-based
backup.
v One method is to add exclude statements to the client options file to prevent the
files or directories from being backed up during backup processing.
v The other method is to add exclude statements to the journal configuration file
tsmjbbd.ini, to prevent journal entries from being added for the files or
directories, which prevents them from being processed during a journal-based
backup.
Note: There is no correlation between the two exclude statements. The preferred
place for exclude statements in tsmjbbd.ini to prevent them from entering the
journal database and being processed during a journal-based backup.
Control processing with exclude statements
After the client evaluates all exclude statements, the following options are
evaluated against the remaining list of objects available for processing.
Table 8 lists the options that you can use to control processing with include and
exclude statements.
Table 8. Options for controlling processing using include and exclude statements
Option
Description
Page
Back up processing
exclude
exclude.backup
exclude.file
exclude.file.backup
include
include.backup
include.file
include.fs
These options are equivalent. Use these options to exclude
a file or group of files from backup services and space
management services (if the HSM client is installed).
The exclude.backup option only excludes files from
normal backup, but not from HSM.
“Exclude
options”
on page
395
Use these options to include files or assign
management classes for backup processing.
“Include
options”
on page
426
Use this option to set options on a file space-by-file
space basis.
“Include
options”
on page
426
Chapter 2. Configure the IBM Spectrum Protect client
91
Table 8. Options for controlling processing using include and exclude statements (continued)
Option
Description
Page
Archive processing
exclude.archive
Excludes a file or group of files from archive services.
“Exclude
options”
on page
395
include
include.archive
These options are equivalent. Use these options to include
files or assign management classes for archive
processing.
“Include
options”
on page
426
Image processing
exclude.fs.nas
Excludes file systems on the NAS file server from an
image backup when used with the backup nas
command. If you do not specify a NAS node name, the
file system identified applies to all NAS file servers.
The backup nas command ignores all other exclude
statements including exclude.dir statements. This
option is for all Windows clients.
“Exclude
options”
on page
395
exclude.image
Excludes mounted file systems and raw logical
volumes that match the specified pattern from full
image backup operations. Incremental image backup
operations are unaffected by exclude.image. This
option is valid for all Windows clients.
“Exclude
options”
on page
395
include.fs.nas
Use the include.fs.nas option to bind a management
class to Network Attached Storage (NAS) file systems.
To specify whether the client saves Table of Contents
(TOC) information during a NAS file system image
backup, use the toc option with the include.fs.nas
option in your client options file (dsm.opt). See “Toc”
on page 562 for more information. This option is valid
for all Windows clients.
“Include
options”
on page
426
include.image
Includes a file space or logical volume, assigns a
management class, or allows you to assign one of
several image backup processing options to a specific
logical volume when used with the backup image
command. The backup image command ignores all
other include options. This option is valid for all
Windows clients.
“Include
options”
on page
426
System state processing
include.systemstate
Assigns management classes for backup of the
Windows system state. The default is to bind the
system state object to the default management class.
“Include
options”
on page
426
System files to exclude
There are some system files that should be placed in the client options file so that
they are excluded.
Attention: These system files are either locked by the operating system or they
can cause problems during restore. These are system files that cannot be recovered
without the possibility of corrupting the operating system, or temporary files with
data that you can easily recreate.
92
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
The implicitly generated statements can be seen in the lines of output of the query
inclexcl command with the source "operating system".
Use the sample include-exclude list in the dsm.smp file as a starting point for your
include-exclude list. This is the minimum include-exclude list that you should
have. The dsm.smp file is located in the config folder in the installation directory. If
you accepted the defaults, the path to this file is C:\Program Files\Tivoli\TSM\
config\dsm.smp
There are exclude statements generated from a list defined by the Windows
operating system in the Windows Registry. Those implicitly generated statements
can be seen in the lines of output of the query inclexcl command with the source
"operating system".
Exclude files with UNC names
You can exclude remotely accessed files by specifying their universal naming
convention (UNC) names in your exclude statement.
The following example assumes that local drive letter g is mapped to the remote
share point:
\\remote\books
You would like to exclude from backups all files at the root of this share point that
have an extension of .txt. You could use either of the following commands:
exclude g:\*.txt
exclude \\remote\books\*.txt
You cannot specify UNC names for removable drives such as DVD, ZIP, or
diskette. For example, the following command is not valid:
exclude \\ocean\a$\winnt\system32\...\*
Include and exclude files that contain wildcard characters
You must use special escape characters when including or excluding files and
directories that contain wildcard characters.
The backup-archive client treats wildcard characters in different ways on different
platforms.
The names of directories and files can contain different symbols. The types of
symbols that are allowed depend on the operating system.
For example, on Windows, the names of directories and files should not contain
the following symbols:
? * < > " / \ : |
However, they can contain the following symbols:
[ ]
To specify files and directories in include and exclude statements, you must use
the escape character "\" to specify the wildcards. However, the escape character
can only be used inside the character classes "[]".
The following examples illustrate how to specify files and directories that contain
wildcard characters using the escape character and character classes in
include-exclude statements.
Chapter 2. Configure the IBM Spectrum Protect client
93
To exclude the single directory C:\[dir2] from backup processing, enter the
following in the dsm.opt file:
exclude.dir "C:\[\[]dir2[\]]"
To exclude the single file C:\file[.txt from backup processing, enter the
following in the dsm.opt file:
exclude.dir "C:\file[\[].txt"
Tip: If you use the Preferences Editor to include or exclude a single file or
directory that contains wildcard characters, you must manually edit the include or
exclude statement to escape the wildcard characters. The Preferences Editor does
not automatically escape the wildcard characters. Follow the previous examples to
edit the include or exclude statements in the dsm.opt file or the include-exclude
file.
Related concepts:
“Wildcard characters” on page 642
Include and exclude groups of files with wildcard characters
You can use wildcard characters to include or exclude groups of files.
To specify groups of files that you want to include or exclude, use the wildcard
characters listed in the following table. This table applies to include and exclude
statements only.
A very large include-exclude list can decrease backup performance. Use wildcards
and eliminate unnecessary include statements to keep the list as short as possible.
Table 9. Wildcard and other special characters
Character
Function
?
The match one character matches any single character except the directory
separator; it does not match the end of the string. For example:
v The pattern ab?, matches abc, but does not match ab, abab, or abzzz.
v The pattern ab?rs, matches abfrs, but does not match abrs, or abllrs.
v The pattern ab?ef?rs, matches abdefjrs, but does not match abefrs, abdefrs,
or abefjrs.
v The pattern ab??rs, matches abcdrs, abzzrs, but does not match abrs, abjrs,
or abkkkrs.
*
The match-all character. For example:
v The pattern ab*, matches ab, abb, abxxx, but does not match a, b, aa, bb.
v The pattern ab*rs, matches abrs, abtrs, abrsrs, but does not match ars, or
aabrs, abrss.
v The pattern ab*ef*rs, matches abefrs, abefghrs, but does not match abefr,
abers.
v The pattern abcd.*, matches abcd.c, abcd.txt, but does not match abcd,
abcdc, or abcdtxt.
\...
The match-n character matches zero or more directories.
The following pattern specifies all files in the root directory of the C drive:
c:\*
The following pattern specifies all files and all directories on the C drive:
c:\...\*
94
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 9. Wildcard and other special characters (continued)
Character
Function
[
The open character-class character begins the enumeration of a character
class. For example:
xxx[abc] matches xxxa, xxxb, or xxxc.
–
The character-class range includes characters from the first character to the
last character specified. For example:
xxx[a-z] matches xxxa, xxxb, xxxc, ... xxxz.
This format should not be used to specify remote drives in an exclude
statement.
\
The literal escape character. When used within a character class, it treats the
next character literally. When used outside of a character class, it is not
treated in this way. For example, if you want to include the ']' in a character
class, enter [...\]...]. The escape character removes the usual meaning of ']' as
the close character-class character.
]
The close character-class character ends the enumeration of a character class.
:
The drive separator character separates a file specification. The character
before the colon identifies a drive letter. The characters after the colon identify
file specification or pattern. For example:
d:\direct\file.nam
Note: Because a drive specification can consist of only one letter, you should not
use more than one wildcard or a combination of a wildcards with a letter to
designate a drive specification. The following patterns are not allowed, and if
specified in the client options file (dsm.opt), stops the client program immediately
after it starts:
?*:\test.txt
*?:\...\pagefile.sys
H*:\test.*
*H:\test.txt
myvolume*:\
myvolume?*:\
If you are using UNC names, Table 10 shows how to correctly specify shared
drives.
Table 10. Specifying a drive specification using wildcards
Incorrect
Correct
\\remote\*:\...\*.*
\\remote\*$\...\*.*
\\remote\?:\...\*.*
\\remote\?$\...\*.*
\\remote\*:\...\pagefile.sys
\\remote\*$\...\pagefile.sys
Related concepts:
“Wildcard characters” on page 642
Examples using wildcards with include and exclude patterns
The backup-archive client accepts the exclude.dir option, which can be used to
exclude directory entries. However, the include and exclude.dir options cannot be
used together.
Chapter 2. Configure the IBM Spectrum Protect client
95
Table 11 shows how to use wildcard characters to include or exclude files.
Table 11. Using wildcard characters with include and exclude patterns
Task
Pattern
Exclude all files during backup with an extension exclude ?:\*.bak
of bak, except those found on the d: drive in the include d:\dev\*.bak
dev directory.
Exclude all files in any directory named "tmp"
and its subdirectories, except for the file
d:\tmp\save.fil.
exclude ?:\...\tmp\...\*
include d:\tmp\save.fil
Exclude any .obj file for backup in any directory exclude [ce-g]:\...\*.obj
on the c: e: f: and g: drives.
The c: e: f: and g: drives are local or
removable.
Exclude the .obj files found in the root directory
in the d: drive only.
exclude d:\*.obj
Exclude any file that resides under the tmp
directory found on any drive.
exclude ?:\tmp\...\*
Exclude the c:\mydir\test1 directory and any
files and subdirectories under it.
exclude.dir c:\mydir\test1
Exclude all directories under the \mydir directory exclude.dir c:\mydir\test*
with names beginning with test.
Exclude all directories directly under the \mydir
directory with names beginning with test, on
any drive.
exclude.dir ?:\mydir\test*
Exclude the raw logical volume from image
backup.
exclude.image c:\*
Exclude all directories and files on the local
drives, except the c: drive.
exclude
[abd-z]:\...\*
exclude.dir [abd-z]:\...\*
Related concepts:
“Examples using wildcards with include and exclude patterns” on page 95
Related reference:
“Exclude options” on page 395
Determine compression and encryption processing
The backup-archive client evaluates exclude.dir and any other include-exclude
options controlling backup and archive processing, and then determines which files
undergo compression and encryption processing.
The following options determine which files undergo compression and encryption
processing.
Table 12. Options for controlling compression and encryption processing
Option
Description
Page
Compression processing
exclude.compression
96
Excludes files from compression processing if
compression=yes is specified. This option applies to
backups and archives.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
“Exclude
options”
on page
395
Table 12. Options for controlling compression and encryption processing (continued)
Option
Description
Page
include.compression
Includes files for compression processing if
compression=yes is specified. This option applies to
backups and archives.
“Include
options”
on page
426
Encryption processing
exclude.encrypt
Excludes files from encryption processing.
“Exclude
options”
on page
395
include.encrypt
Includes files for encryption processing.
“Include
options”
on page
426
The data that you include is stored in encrypted
form, and encryption does not affect the amount of
data sent or received.
Important: The include.encrypt option is the only
way to enable encryption on the Backup-Archive
client. If no include.encrypt statements are used
encryption will not occur.
Preview include-exclude list files
You can preview the list of objects to be backed up or archived according to the
include-exclude list, prior to sending any data to the server.
The backup-archive client GUI directory tree shows detailed information of
included and excluded objects. The directory tree windows in the backup-archive
client GUI allow you to select files and directories to include or exclude. You
should use this preview command to make sure that you include and exclude the
correct files. The following is a sample scenario for using the include-exclude
preview function.
For example, follow these steps to back up the files on your /Users/home file space:
1. Start the backup-archive client GUI and open the Backup tree. You can see all
of the directories and files that have been excluded by your options file and
other sources.
2. Scroll down the tree and notice that all of the *.o files in your
/Volumes/home/mary/myobjdir are backed up.
3. You do not want to back up all of the *.o files, so you right click a .o file, and
choose "View File Details" from the popup menu.
4. The dialog shows that these files are included, so click the "Advanced" button
and create a rule to exclude all .o files from the DATA:\home file space.
5. A rule is created at the bottom of your options file. The current directory is
refreshed in the Backup tree, and the .o files have the red ’X’, meaning they
are excluded.
6. When you look at other directories, they show the new excludes that you have
added. Press "Backup" and back up the files on your /home file space.
Related reference:
“Preview Archive” on page 701
“Preview Backup” on page 702
Chapter 2. Configure the IBM Spectrum Protect client
97
Include and exclude option processing
The IBM Spectrum Protect server can define include-exclude options using the
inclexcl parameter in a client option set.
The include-exclude statements specified by the server are evaluated along with
those in the client options file. The server include-exclude statements are always
enforced and placed at the bottom of the include-exclude list and evaluated before
the client include-exclude statements.
If the client options file include-exclude list contains one or more inclexcl options
that specify include-exclude files, the include-exclude statements in these files are
placed in the list position occupied by the inclexcl option and processed
accordingly.
A very large include-exclude list can decrease backup performance. Use wildcards
and eliminate unnecessary include statements to keep the list as short as possible.
When performing an incremental backup, the client evaluates all exclude.dir
statements first, and removes the excluded directories and files from the list of
objects available for processing.
After evaluating all exclude.dir statements, the client evaluates the
include-exclude list from the bottom up and stops when it finds an include or
exclude statement that matches the file it is processing. The order in which the
include and exclude options are entered therefore affects which files are included
and excluded.
To display a list of all include-exclude statements in effect on your client
workstation in the actual order they are processed, use the query inclexcl
command.
The client program processes the list of include-exclude statements according to
the following rules:
1. Files are checked; directories are only checked if the exclude.dir option is
specified.
2. File names are compared to the patterns in the include-exclude list from the
bottom up. When a match is found, the processing stops and checks whether
the option is include or exclude. If the option is include, the file is backed up.
If the option is exclude, the file is not backed up.
Note: If a match is not found, files are implicitly included and backed up.
3. When a file is backed up, it is bound to the default management class unless it
matched an include statement that specified a different management class
name, in which case the file is bound to that management class.
The following examples demonstrate bottom up processing.
Example 1
Assume that you defined the following statements for the include and
exclude options:
exclude ?:\*.obj
include c:\foo\...\*.obj
exclude c:\foo\junk\*.obj
98
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
The file being processed is: c:\foo\dev\test.obj. Processing follows these
steps:
1. Rule 3 (the last statement defined) is checked first because of
bottom-up processing. The pattern c:\foo\junk\*.obj does not match
the file name that is being processed.
2. Processing moves to Rule 2 and checks. This time, pattern
c:\foo\...\*.obj matches the file name that is being processed.
Processing stops, the option is checked, and it is included.
3. File c:\foo\dev\test.obj is backed up.
Example 2
Assume that you defined the following statements for the include and
exclude options:
exclude ?:\*.obj
include c:\foo\...\*.obj
exclude c:\foo\junk\*.obj
The file being processed is: c:\widg\copyit.bat. Processing follows these
steps:
1. Rule 3 is checked and finds no match.
2. Rule 2 is checked and finds no match.
3. Rule 1 is checked and finds no match.
4. Because a match is not found, file c:\widg\copyit.bat is implicitly
included and backed up.
Example 3
Assume that you defined the following statements for the include and
exclude options:
exclude ?:\...\*.obj
include c:\foo\...\*.obj
exclude c:\foo\junk\*.obj
The current file being processed is: c:\lib\objs\printf.obj. Processing
follows these steps:
1. Rule 3 is checked and finds no match.
2. Rule 2 is checked and finds no match.
3. Rule 1 is checked and a match is found.
4. Processing stops, the option is checked, and it is excluded.
5. File c:\lib\objs\printf.obj is not backed up.
Related concepts:
“Exclude file spaces and directories” on page 89
Chapter 11, “Processing options,” on page 291
Related reference:
“Exclude options” on page 395
“Query Inclexcl” on page 719
Processing rules when using UNC names
When processing files with UNC names, there are rules that must be followed.
The backup-archive client uses the rules that are described in “Include and exclude
option processing” on page 98. The rules in “Explicit use of UNC names for
remote drives” on page 100 also apply.
Chapter 2. Configure the IBM Spectrum Protect client
99
Explicit use of UNC names for remote drives
The backup-archive client recognizes explicit use of UNC names for remote drives.
For example, as shown in Table 13, the UNC name pattern can be substituted for
the DOS pattern.
Assume local drive letter r: is mapped to remote share point \\remote\c$, s: is
mapped to \\remote\share4, and t: is mapped to \\remote\share2.
Table 13. UNC name patterns and DOS patterns
UNC name pattern
DOS pattern
\\remote\c$\include\file.out
r:\include\file.out
\\remote\c$\...\file.out
r:\...\file.out
\\remote\share4\exclude\*
s:\exclude\*
\\remote\share2\...\?.out
t:\...\?.out
Conversion of DOS pathnames for fixed and remote drives
The backup-archive client converts DOS path names that are mapped to remote
share points.
For example, a remote share point that is mapped from r:\test\...\exclude.out
to \\remote\share\test\...\exclude.out is converted. Remote share points that
are not mapped are not converted. Files on removable media are not converted.
Character-class matching examples
This topic shows examples of valid matches using character class.
\\remote[a-z]\share\file.txt
matches
\\remotea\share\file.txt
\\remote\share[a-z]\file.txt
matches
\\remote\sharex\file.txt
\\remote\share\file[a-z].txt
matches
\\remote\share\fileg.txt
100
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chapter 3. Getting started
Before you can use the IBM Spectrum Protect backup-archive client, you must
learn how to start a GUI or command-line session, and how to start the client
scheduler automatically. You can also learn about other commonly used tasks.
Before you use the backup-archive client, complete the following tasks:
v “Starting a Java GUI session” on page 113
v “Starting a command-line session” on page 114
v “Starting a web client session” on page 117
v “Start the client scheduler automatically” on page 119
v “Changing your password” on page 119
You can also complete the following tasks:
v “Sorting file lists using the backup-archive client GUI” on page 120
v “Displaying online help” on page 122
v “Ending a session” on page 122
|
|
|
|
|
|
|
|
Configuring the client security settings to connect to the IBM
Spectrum Protect server version 8.1.2 and later
There are several configuration options that pertain to the IBM Spectrum Protect
client security settings when connecting to the IBM Spectrum Protect server
version 8.1.2 and later. Accepting the default values for those options transparently
configures the client for enhanced security, and is recommended for most use
cases.
Default security settings for the client (fast path)
|
|
|
|
|
|
|
|
|
Fast path details the configuration options that impact the security of the client
connection to the server and the behavior for various use cases when default
values are accepted. This scenario minimizes the steps in the configuration process
at endpoints. It automatically obtains certificates from the server when the client
connects the first time, assuming that the IBM Spectrum Protect server
'SESSIONSECURITY' parameter is set to 'TRANSITIONAL', which is the default
and recommended value. You can follow this scenario whether you first upgrade
the IBM Spectrum Protect server to version 8.1.2 and then upgrade the client to
version 8.1.2 or vice versa.
|
|
|
|
|
Attention: This scenario cannot be used if the IBM Spectrum Protect server is
configured for LDAP authentication. If LDAP is used, you can manually import
the certificates necessary by using the dsmcert utility. See “Configuring IBM
Spectrum Protect client/server communication with Secure Sockets Layer” on page
36 for details.
|
Client options that affect session security
|
|
|
|
1. SSLREQUIRED. The default value Default enables existing session-security
connections to servers earlier than V8.1.2, and automatically configures the
client to securely connect to a V8.1.2 or newer server by using TLS for
authentication.
© Copyright IBM Corp. 1993, 2017
101
|
|
|
|
2. SSLACCEPTCERTFROMSERV. The default value Yes enables the client to
automatically accept a self-signed public certificate from the server, and to
automatically configure the client to use that certificate when the client
connects to a V8.1.2 or later server.
|
|
|
|
|
|
|
3. SSL. The default value No indicates that encryption is not used when data is
transferred between the client and a server earlier than V8.1.2. When the client
connects to a V8.1.2 or later server, the default value No indicates that object
data is not encrypted. All other information is encrypted, when the client
communicates with the server. When the client connects to a V8.1.2 or later
server, the value Yes indicates that SSL is used to encrypt all information,
including object data, when the client communicates with the server.
|
|
4. SSLFIPSMODE. The default value No indicates that a Federal Information
Processing Standards (FIPS) certified SSL library is not needed.
|
|
|
In addition, the following options apply only when the client uses SSL connections
to a server earlier than V8.1.2. They are ignored when the client connects to a
V8.1.2 or later server.
|
|
|
1. SSLDISABLELEGACYTLS. The default value No indicates that connections at TLS 1.1
and lower SSL protocols are allowed when the client communicates with a
server V8.1.1 and earlier V8 levels, and V7.1.7 and earlier levels.
|
|
2. LANFREESSL. Specifies whether the client uses SSL communication with the
Storage Agent when LAN-free data transfer is configured.
|
|
3. REPLSSLPORT. Specifies the TCP/IP port address that is enabled for SSL when
the client communicates with the replication target server.
|
Uses cases for default security settings for the client (fast path)
|
|
1. First, the server is upgraded to V8.1.2. Then, the client is upgraded. The
existing client is not using SSL communications:
v No changes are needed to the client security options.
|
v The client configuration is automatically updated to use TLS when the client
authenticates with the server.
2. First, the server is upgraded to V8.1.2. Then, the client is upgraded. The
existing client is using SSL communications:
|
|
|
|
|
v No changes are needed to the client security options.
|
|
v SSL communication with existing server public certificate continues to be
used.
|
|
v SSL communication is automatically enhanced to use the TLS level that is
needed by the server.
3. First, the client is upgraded to V8.1.2. Then, the server is upgraded later. The
existing client is not using SSL communications:
|
|
|
v No changes are needed to the client security options.
|
|
v Existing authentication protocol continues to be used to servers at levels
earlier than V8.1.2.
|
|
v The client configuration is automatically updated to use TLS when the client
authenticates with the server after the server is updated to V8.1.2 or later.
4. First, the client is upgraded to V8.1.2. Then, the server is upgraded later. The
existing client is using SSL communications:
|
|
|
v No changes are needed to the client security options.
|
|
v SSL communication with existing server public certificate continues to be
used with servers at levels earlier than V8.1.2.
102
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
|
|
|
v SSL communication is automatically enhanced to use the TLS level that is
needed by the server after the server is updated to V8.1.2 or later.
5. First, the client is upgraded to V8.1.2. Then, the client connects to multiple
servers. The servers are upgraded to V8.1.2 at different times:
|
|
|
|
|
v No changes are needed to the client security options.
v The client uses existing authentication and session security protocol to
servers at versions earlier than V8.1.2, and automatically upgrades to use
TLS authentication when initially connecting to a server at V8.1.2 or later.
Session security is managed per server.
|
|
6. New client installation, server is at V8.1.2 or later:
v Configure the client according to a new client installation.
|
|
v Default values for the client security options automatically configure the
client for TLS-encrypted session authentication.
|
|
v Set the SSL parameter to the Yes value if encryption of all data transfers
between the client and the server is needed.
|
7. New client installation, server is at a version earlier than V8.1.2:
|
v Configure the client according to a new client installation.
|
|
v Accept the default values for client session-security parameters if SSL
encryption of all data transfers is not needed.
|
|
– Non-SSL authentication protocol is used until the server is upgraded to
V8.1.2 or later.
|
|
|
v Set the SSL parameter to the Yes value if encryption of all data transfers
between the client and the server is needed, and proceed with the manual
client configuration for SSL.
|
|
– See “Configuring IBM Spectrum Protect client/server communication with
Secure Sockets Layer” on page 36 for details.
|
|
– SSL communication is automatically enhanced to use the TLS level that is
needed by the server after the server is updated to V8.1.2 or later.
|
Related reference:
|
“Sslrequired” on page 546
|
“Sslacceptcertfromserv” on page 544
|
“Ssl” on page 542
|
“Sslfipsmode” on page 545
|
“Ssldisablelegacytls” on page 544
|
“Lanfreessl” on page 450
|
“Replsslport” on page 498
|
|
Configuring the client without automatic certificate
distribution
|
|
|
|
|
This scenario details the configuration options that impact the security of the client
when automatic distribution of certificates from the server is not acceptable.
Automatic distribution of certificates from the server is not acceptable if the server
is configured to use LDAP authentication or it is necessary that certificates are
signed by a certificate authority.
|
|
Note: In this scenario, you can accept the default values for most of the
session-security options, except for the SSLACCEPTCERTFROMSERV option.
Chapter 3. Getting started
103
|
|
|
|
|
|
|
|
Client options that affect session security
|
|
|
|
|
|
|
3. SSL. The default value No indicates that encryption is not used when data is
transferred between the client and a server earlier than V8.1.2. When the client
connects to a V8.1.2 or later server, the default value No indicates that object
data is not encrypted. All other information is encrypted, when the client
communicates with the server. When the client connects to a V8.1.2 or later
server, the value Yes indicates that SSL is used to encrypt all information,
including object data, when the client communicates with the server.
|
|
4. SSLFIPSMODE. The default value No indicates that a Federal Information
Processing Standards (FIPS) certified SSL library is not needed.
|
|
|
|
|
|
|
|
In addition, the following options apply only when the client uses SSL connections
to a server earlier than V8.1.2. They are ignored when the client connects to a
V8.1.2 or later server.
1. SSLDISABLELEGACYTLS. The default value No indicates that connections at TLS 1.1
and lower SSL protocols are allowed when the client communicates with a
server V8.1.1 and earlier V8 levels, and V7.1.7 and earlier levels.
2. LANFREESSL. Specifies whether the client uses SSL communication with the
Storage Agent when LAN-free data transfer is configured.
|
|
3. REPLSSLPORT. Specifies the TCP/IP port address that is enabled for SSL when
the client communicates with the replication target server.
|
|
Uses cases for configuring the client without automatic
certificate distribution
|
|
1. First, the server is upgraded to V8.1.2. Then, the client is upgraded. The
existing client is not using SSL communications:
1. SSLREQUIRED. The default value Default enables existing session-security
connections to servers earlier than V8.1.2, and automatically configures the
client to securely connect to a V8.1.2 or newer server by using TLS for
authentication.
2. SSLACCEPTCERTFROMSERV. Set this value to No to ensure that the client does not
automatically accept a self-signed public certificate from the server when the
client first connects to a V8.1.2 or later server.
|
|
v Use the client configuration wizard to set the SSLACCEPTCERTFROMSERV option
with the value No.
|
v Obtain the necessary certificate from a trusted source.
|
|
|
v Use the dsmcert utility to import the certificate for client use. See
“Configuring IBM Spectrum Protect client/server communication with Secure
Sockets Layer” on page 36 for details.
2. First, the server is upgraded to V8.1.2. Then, the client is upgraded. The
existing client is using SSL communications:
|
|
|
|
|
v No changes are needed to the client security options. If the client already has
a server certificate for SSL communication, the SSLACCEPTCERTFROMSERV option
does not apply.
|
|
v SSL communication with existing server public certificate continues to be
used.
|
|
v SSL communication is automatically enhanced to use the TLS level that is
needed by the server.
3. First, the client is upgraded to V8.1.2. Then, the server is upgraded later. The
existing client is not using SSL communications:
|
|
v Use the client configuration wizard to set the SSLACCEPTCERTFROMSERV option
with the value No.
|
|
104
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
|
|
|
|
|
|
|
|
v Existing authentication protocol continues to be used to servers at levels
earlier than V8.1.2.
v Before the client connects to an 8.1.2 or later server:
– Obtain the necessary certificate from a trusted source.
– Use the dsmcert utility to import the certificate for client use. See
“Configuring IBM Spectrum Protect client/server communication with
Secure Sockets Layer” on page 36 for details.
4. First, the client is upgraded to V8.1.2. Then, the server is upgraded later. The
existing client is using SSL communications:
|
|
|
v No changes are needed to the client security options. If the client already has
a server certificate for SSL communication, the SSLACCEPTCERTFROMSERV option
does not apply.
|
|
v SSL communication with existing server public certificate continues to be
used with servers at levels earlier than V8.1.2.
|
|
v SSL communication is automatically enhanced to use the TLS level that is
needed by the server after the server is updated to V8.1.2 or later.
|
|
5. First, the client is upgraded to V8.1.2. Then, the client connects to multiple
servers. The servers are upgraded to V8.1.2 at different times:
|
|
v Use the client configuration wizard to set the SSLACCEPTCERTFROMSERV option
with the value No.
|
|
v Existing authentication protocol continues to be used to servers at levels
earlier than V8.1.2.
|
|
v Before the client connects to an 8.1.2 or later server, or when SSL
communication is needed at any server level:
|
– Obtain the necessary certificate for the target server from a trusted source.
|
|
|
– Use the dsmcert utility to import the certificate for client use. See
“Configuring IBM Spectrum Protect client/server communication with
Secure Sockets Layer” on page 36 for details.
|
|
|
|
v The client uses existing authentication and session security protocol to
servers at versions earlier than V8.1.2, and automatically upgrades to use
TLS authentication when initially connecting to a server at V8.1.2 or later.
Session security is managed per server.
|
6. New client installation, server is at V8.1.2 or later:
|
v Configure the client according to a new client installation.
|
|
v Use the client configuration wizard to set the SSLACCEPTCERTFROMSERV option
with the value No.
|
v Obtain the necessary certificate from a trusted source.
|
|
|
v Use the dsmcert utility to import the certificate for client use. See
“Configuring IBM Spectrum Protect client/server communication with Secure
Sockets Layer” on page 36 for details.
|
|
v Set the SSL parameter to the Yes value if encryption of all data transfers
between the client and the server is needed.
|
|
7. New client installation, server is at a version earlier than V8.1.2, SSL-encrypted
sessions are needed:
|
|
v Configure the client according to a new client installation.
v Set the SSL parameter to the Yes value.
|
v Obtain the necessary certificate from a trusted source.
|
|
|
v Use the dsmcert utility to import the certificate for client use. See
“Configuring IBM Spectrum Protect client/server communication with Secure
Sockets Layer” on page 36 for details.
Chapter 3. Getting started
105
8. New client installation, server is at a version earlier than V8.1.2, SSL-encrypted
sessions are not needed:
v Configure the client according to a new client installation.
v Use the client configuration wizard to set the SSLACCEPTCERTFROMSERV option
with the value No.
– Non-SSL authentication protocol is used until the server is upgraded to
V8.1.2 or later.
v Before the client connects to an 8.1.2 or later server:
|
|
|
|
|
|
|
|
|
– Obtain the necessary certificate from a trusted source.
|
|
|
– Use the dsmcert utility to import the certificate for client use. See
“Configuring IBM Spectrum Protect client/server communication with
Secure Sockets Layer” on page 36 for details.
|
Related reference:
|
“Sslrequired” on page 546
|
“Sslacceptcertfromserv” on page 544
|
“Ssl” on page 542
|
“Sslfipsmode” on page 545
|
“Ssldisablelegacytls” on page 544
|
“Lanfreessl” on page 450
|
“Replsslport” on page 498
|
Secure password storage
|
|
Beginning in IBM Spectrum Protect Version 8.1.2, the location of the IBM Spectrum
Protect password is changed.
|
|
|
In V8.1.0 and V7.1.6 and earlier clients, the IBM Spectrum Protect password was
stored in the Windows registry for Windows clients, and stored in the TSM.PWD file
on UNIX and Linux clients.
|
|
|
|
|
Beginning in V8.1.2, the IBM Global Security Kit (GSKit) keystores are used to
store all IBM Spectrum Protect passwords. The process of importing server
certificates is simplified. For information about importing server certificates, see
“Configuring IBM Spectrum Protect client/server communication with Secure
Sockets Layer” on page 36.
|
|
When you upgrade to IBM Spectrum Protect V8.1.2 backup-archive client, the
existing passwords are migrated to the following files in the new password store:
|
|
TSM.KDB
|
|
|
|
TSM.sth
|
|
TSM.IDX
|
|
For Data Protection for VMware clients, the Data Protection for VMware GUI
server administration password is migrated to a keystore.
The file that stores the encrypted passwords.
The file that stores the random encryption key that is used to encrypt
passwords in the TSM.KDB file. This file is protected by the file system. This
file is needed for automated operations.
An index file that is used to track the passwords in the TSM.KDB file.
106
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
Password locations on Windows clients
|
|
|
On Windows clients, the passwords in the SOFTWARE\IBM\ADSM\CurrentVersion\
BackupClient\Nodes registry key and the SOFTWARE\IBM\ADSM\CurrentVersion\Nodes
registry key are migrated to the new password store.
|
The password entries in these registry keys are deleted after the migration.
|
|
|
|
|
|
The migrated server and encryption passwords are stored in the password stores
in separate subdirectories of the C:\ProgramData\Tivoli\TSM\baclient directory (a
hidden directory). Separating the server passwords this way allows an
administrator to grant a non-administrative user access to individual passwords
without giving that user access to all the other passwords. The following
directories are examples of password file locations:
|
v C:\ProgramData\Tivoli\TSM\BAClient\NodeName\ServerName
|
v C:\ProgramData\Tivoli\TSM\BAClient\(VCB)\ServerName
|
v C:\ProgramData\Tivoli\TSM\BAClient\(DOMAIN)\ServerName
|
v C:\ProgramData\Tivoli\TSM\BAClient\(FILER)\ServerName
|
|
|
|
Access to the password stash files (TSM.sth) is restricted to the creator of the
keystore, Administrators, and System. A utility (dsmcutil addace) is available to
allow Windows users to easily modify password file access control lists. For more
information, see “ADDACE” on page 285 and “DELETEACE” on page 286.
|
Password locations in cluster environments
|
|
|
|
If you are operating the client in a cluster environment (CLUSTERNODE YES in the
client options file), the password files are stored in a subdirectory of the client
options file location. The subdirectory name is:
|
|
|
|
In a cluster configuration, the options file is stored on a cluster disk so that it can
be accessed by the takeover node. The password files must also be stored on a
cluster disk so that after a failure, the generated backup-archive client password is
available to the takeover node.
|
|
|
|
For example, if the dsm.opt file is in the c:\ClusterStorage\Volume1\SPData
directory, the node name is Cluster-B, and the server name is Bigdata, the location
for password files is:
|
|
NODES\NodeName\ServerName
C:\ClusterStorage\Volume1\SPdata\Nodes\Cluster-B\Bigdata
Backup-archive client operations and security rights
|
|
This section explains the types of IBM Spectrum Protect backup-archive client
operations that can be performed and the security rights that are needed.
|
|
You must have local or domain administrator privileges to install and configure
IBM Spectrum Protect client services.
|
|
|
|
Table 14 on page 108 summarizes the user security rights needed for backup and
restore operations. The information in the table assumes that the default privileges
for the Microsoft Windows Administrators group, Backup Operators group, and
Users group have not been altered.
Chapter 3. Getting started
107
|
|
Table 14. Required user security rights for IBM Spectrum Protect backup and restore
services
|
|
Operating system
Account
What can I back up and
restore?
||
||
|
|
|
|
|
|
|
Windows Clients
Member of Administrators
group
v Back up and restore all file
and directory objects
||
||
|
|
Windows Clients
v Back up and restore
system state
v System state data (Backup
Operators group cannot
back up ASR writer data
and cannot restore system
state data)
Member of Backup
Operators group
v Back up and restore all file
and directory objects
v Back up system state,
except for ASR Writer
|
|
|
Note: Backup Operator
group members cannot
restore system state.
||
||
|
|
|
|
|
|
|
|
|
|
Windows Clients
Member of Users or other
group
v Back up and restore all file
and directory objects
Attention: Users must
have the following
Microsoft Windows
security privileges in order
to back up and restore
files and directories:
– Back up files and
directories
– Restore files and
directories
|
|
|
|
|
|
|
|
|
|
|
|
|
These privileges represent
a potential security risk
since they allow the user
to back up any file, or
restore any file for which a
backup copy exists. The
privileges should be
granted only to trusted
users. For more
information about these
privileges, see the
Microsoft Windows
documentation.
|
|
|
Note: System state cannot be
backed up or restored.
By default, IBM Spectrum Protect client services run under the local system
account. However, the local system account does not have access to network
mapped drives and does not have the same permissions and logon properties as a
user that is logged in to the system. If you experience discrepancies between a user
|
|
|
|
108
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
|
initiated backup and a scheduled backup using the local system account, consider
changing the services to run under the user account.
|
|
|
|
|
|
Tip: In addition to the appropriate user security rights, the IBM Spectrum Protect
backup-archive client requires that the user has read permission to the root of any
drive that needs to be backed up or restored. If you are using the system account
to logon for the IBM Spectrum Protect scheduler service, ensure that you grant the
system account (SYSTEM) read access to the root of the drive. It is not sufficient to
grant Everyone read access to the root of the drive.
|
|
|
Domain resources, such as network drives, can only be accessed by services
configured to run under a domain authorized account using dsmcutil or the
Service Control Panel Application.
|
|
|
|
Beginning with IBM Spectrum Protect Version 8.1.2, stricter access control is
enforced for the IBM Spectrum Protect password storage on Windows operating
systems. By default, only the Administrator, SYSTEM, or LocalSystem account has
access to the password store and SSL certificates.
|
|
|
|
You can use the dsmcutil addace command to modify the access control list to
allow additional users, such as non-administrative users, or processes such as the
IBM Spectrum Protect Data Protection client processes to access the password store
and SSL certificates.
|
|
|
|
You can use the dsmcutil deleteace command to modify the access control list to
remove access to the password store and client certificates for users, such as
non-administrative users or processes such as the IBM Spectrum Protect Data
Protection client processes.
|
|
For more information, see “ADDACE” on page 285 and “DELETEACE” on page
286.
|
Backup Operators group operations
|
|
The Backup Operators group allows users to back up and restore files regardless of
whether they have read or write access to the files.
|
|
This group has a limited set of user rights, so some functions are not available to
members of the Backup Operators group.
|
|
The following list contains the backup-archive client operations that a member of
the Backup Operators can do:
|
|
v Back up and restore files (see Table 14 on page 108)
v Back up system state
|
You must be a member of the Administrators group to back up ASR writer data.
|
v Start the scheduler service
|
|
The following list contains the backup-archive client operations that a member of
the Backup Operators cannot do:
|
v Start any other services (client acceptor, remote client agent, and journal service)
|
v Install and configure client services
|
v Use open file support (OFS)
|
v Back up and restore images
|
v Back up and restore Windows file shares
Chapter 3. Getting started
109
Considerations before you start using a Backup Operators
group account
|
|
|
|
There are some items that you need to consider before you use a Backup Operators
group account to back up, archive, restore, or retrieve your data.
|
|
|
|
|
|
|
Consider these items before using a Backup Operators group account to back up,
archive, restore, or retrieve your data:
v If you have already been using the backup-archive client with an Administrators
group account you might not be able to launch the client because you cannot
open the log files (for example dsmerror.log). To alleviate this problem, you can
grant the Backup Operators group Read and Write permissions to the log files or
the directories containing these log files.
|
|
|
|
v If you have existing backups from a version 5.2 or earlier backup-archive client
and you attempt an incremental backup of an existing file space with a member
of the Backup Operators group, all of the data appears as changed and it is
resent to the IBM Spectrum Protect Server.
|
|
|
v Members of the Backup Operators group might not be able to back up or restore
file data that was encrypted by an Administrator account using the Windows
encrypting file system (EFS).
|
|
|
|
v Members of the Backup Operators group do not have the proper authority to
update the last access time for files that is encrypted with the Windows
encrypting file system (EFS). If EFS files are restored by a member of the Backup
Operators group, the last access time will not be preserved.
Permissions required to restore files that use adaptive subfile backup
Adaptive subfile backup is deprecated, but you can still restore subfile backup data
that was created with the version 7.1 or earlier client. To restore files that were
processed using adaptive subfile backup, you must either be the owner of the file
or have read access.
These permissions are in addition to those required to perform a normal restore.
For information about adaptive subfile backup, see Performing a backup with
limited bandwidth in the version 7.1 backup-archive client documentation.
Permissions required to back up, archive, restore or retrieve files on
cluster resources
To back up, restore, archive, or retrieve data residing on Microsoft Cluster Server
(MSCS) or Veritas Cluster Server cluster resources, your Windows account must
belong to the Administrators or Domain Administrators group or Backup
Operators group.
By default, Backup Operators do not have the user rights necessary to perform
these tasks on a cluster node. However, Backup Operators can perform this
procedure if that group is added to the security descriptor for the Cluster service.
You can do that using Cluster Administrator or cluster.exe.
110
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
IBM Spectrum Protect client authentication
When using the graphical user interface or command line interface of the IBM
Spectrum Protect client, you can log on using a node name and password or
administrative user ID and password.
The client prompts for your user ID and compares it to the configured node name.
If they match, the client attempts to authenticate the user ID as a node name. If the
authentication fails or if the user ID does not match the configured node name, the
client attempts to authenticate the user ID as an administrative user ID.
To use an administrative user ID with any of the backup-archive clients, the user
ID must have one of the following authorities:
System privilege
Authority over the entire system. An administrator with system privilege
can perform any administrative task.
Policy privilege
Authority over the node policy domain. Allows an administrator to
manage policy objects, register client nodes, and schedule client operations
for client nodes.
Client owner
Authority over the registered IBM Spectrum Protect client node. You can
access the client through the web client or backup-archive client. You own
the data and have a right to physically gain access to the data remotely.
You can back up and restore files on the same or different system, and you
can delete file spaces or archive data.
Client access
To use the web client to back up and restore files on a remote client
system, you must have an administrative user ID with client access
authority over the node name for the remote client system. If you do not
want IBM Spectrum Protect administrators with client access authority
over your node name to be able to back up and restore files on your
system, specify the revokeremoteaccess option in your client options file.
Client access authority only allows IBM Spectrum Protect administrators to
back up and restore files on remote systems. They do not have physical
access to the data. That is, they cannot restore the data belonging to the
remote system to their own systems. To restore data belonging to a remote
system to your own system, you must possess at least client owner
authority.
To determine what authority you have, you can use either of the following
methods:
v From the main IBM Spectrum Protect GUI window, select File → Connection
Information.
v Use the IBM Spectrum Protect server QUERY ADMIN command from the
administrative command-line client.
Related reference:
“Revokeremoteaccess” on page 507
QUERY ADMIN command
Chapter 3. Getting started
111
User account control
User Account Control (UAC) is a Windows security feature that helps prevent
malware from compromising the operating system. UAC restricts programs to
standard user privileges.
When UAC is enabled, programs that require elevated privileges cannot run
without your permission.
The backup-archive client requires elevated privileges. If UAC is enabled when
you run the client, a User Account Control dialog box is displayed. The dialog asks
if you want to allow the program to run. If you are not logged in as an
administrator, the dialog also asks for your account credentials.
Enabling client access to network shares when UAC is
enabled
When Windows User Account Control (UAC) is enabled, the backup-archive client
cannot access existing network share mappings. The solution is to map the
network shares from an elevated command prompt before you start the client.
About this task
When you map a network share, the share is linked to your current Windows login
access token. That token has only standard user privileges. Because the
backup-archive client must run with elevated privileges, a different access token is
used. Since the network share is not linked to this other access token, the mapped
network share is not visible to the client. The network share must be linked to the
access token that has the elevated privileges to make the share visible to the client.
Procedure
Complete the following steps to enable the client to access data on network shares.
1. Create a desktop shortcut for the Windows command prompt. The default
location of the command prompt executable file is C:\Windows\System32\
cmd.exe.
2. Right-click the shortcut and select Run as Administrator. A UAC prompt is
displayed with instructions that describe how to proceed.
v If you are logged in as a member of the Administrators group, click Yes to
allow the client to run with elevated privileges.
v If you are not logged in as a member of the Administrators group, enter
your credentials when prompted to do so, and then click Yes to allow the
client to run with elevated privileges.
Perform the remaining steps in the elevated command prompt window that
you just opened.
3. Use the Windows net use command to map the network shares. Contact your
system administrator if you need help with the net use command.
Note: Do not use Windows Explorer to map the network share because
Windows Explorer runs with the standard user rights token.
4. Change to the directory where the client is installed. The default installation
directory is C:\Program Files\Tivoli\TSM\baclient.
5. Start the client GUI (dsm.exe) or the command-line client (dsmc.exe) and
backup or restore data that is on network shares.
112
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Starting a Java GUI session
The steps that are used to start the backup-archive client graphical interface (GUI)
program depend on the operating system.
Procedure
Complete the procedure that is appropriate for your operating system to start the
Java GUI.
Operating System
Procedure
Windows
To start the backup-archive client GUI on a
Windows system, use one of the following
methods:
v Click Start > Programs > IBM Spectrum
Protect > Backup-Archive GUI.
v Click Start > Run and enter the full path
to the backup client dsm.exe file.
v On the command line, change directory to
the backup-archive client installation
directory and enter dsm.
On Windows operating systems that have
the User Account Control feature enabled,
you might be prompted to allow the dsm.exe
program to run. To allow the program to
continue and start the backup-archive client
GUI, provide administrative credentials.
The backup-archive client locates and uses the options that are specified in the
client options file (dsm.opt).
Related concepts:
Chapter 2, “Configure the IBM Spectrum Protect client,” on page 21
Related tasks:
“Configuring the language for displaying the Java GUI” on page 27
“Configuring the language for displaying the Java GUI” on page 27
IBM Spectrum Protect password
Your IBM Spectrum Protect administrator can require you to use a password to
connect to the server.
The IBM Spectrum Protect client prompts you for the password if one is required.
Contact your IBM Spectrum Protect administrator if you do not know your
password.
Related tasks:
“Changing your password” on page 119
Setup wizard
When the client GUI starts, it checks to see whether a client options file exists.
If the client options file does not exist (which usually happens after you have
installed the client for the first time on your system), the setup wizard
automatically starts and guides you through the configuration process.
Chapter 3. Getting started
113
You can launch the setup wizard at any time to modify your client options file.
The client options file is dsm.opt.
Starting a command-line session
You can start a command-line session by invoking the dsmc command.
Note: If the PATH environment variable is set to the client installation directory,
you can enter the dsmc command from any directory; otherwise, enter the fully
qualified path.
One can start client with "dsmc" command only in case PATH environment
variable is updates with path to the client location.
You can open the Windows Start menu and select Programs > IBM Spectrum
Protect > Backup-Archive Command Line.
Your IBM Spectrum Protect administrator can require you to use a password to
connect to the server. The client prompts you for a password, if it is required.
Contact your administrator if you do not know your password.
Related concepts:
“Backup-archive client operations and security rights” on page 107
“Options in interactive mode” on page 640
“Start and end a client command session” on page 638
Chapter 12, “Using commands,” on page 635
Using batch mode
Use batch mode to enter a single client command. When you use batch mode, you
must precede the command with dsmc.
About this task
For example, to issue the incremental command, enter the following at the
command prompt:
dsmc incremental
Some commands require one or more arguments. For example, to archive a file:
dsmc archive c:\myfiles\file1.dat
Depending upon the current setting of your passwordaccess option, the client
might prompt you for your password before the command is processed in a batch
mode session.
When you enter your password, the password is not displayed on your screen.
Related reference:
“Passwordaccess” on page 476
Issuing a series of commands by using interactive mode
Use interactive mode when you want to issue a series of commands.
114
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
About this task
The connection to the server is established only once for interactive mode, so you
can process a series of commands more quickly in interactive mode than in batch
mode.
To start a client command session in interactive mode, enter either of the following
commands:
v dsmc
v dsmc loop
The following prompt is displayed on your screen:
Protect>
When you log on with an administrator ID, you can complete standard user tasks..
If you are not logged on before you begin a task from a command-prompt
window, you are prompted to do so..
When you are in interactive mode, do not precede commands with dsmc. For
example, instead of typing dsmc archive to archive a file, type only archive.
For example, to archive a file, enter the command with the file specification:
archive c:\myfiles\file1.dat
Depending upon the current setting of the passwordaccess option, the client might
prompt you for your password before you are allowed to enter a command in an
interactive session.
When you enter your password, the password is not displayed on your screen.
Displaying Euro characters in a command-line prompt
This topic explains how to display the Euro character in the Windows
command-line prompt (console window).
Procedure
1. Contact your Microsoft Representative for the 858 code page (the file name is
c_858.nls). Copy the file into your Windows system32 directory (for example,
C:\WINNT\system32).
2. Edit the Windows Registry key, using this command: HKEY_LOCAL_MACHINE\
SYSTEM\CurrentControlSet\Control\Nls\CodePage\850, and set it to value
c_858.nls. Any changes that you make to the Windows Registry editor
cannot be undone. Errors made in editing the Windows Registry can cause
your system to malfunction, and you might not even be able to restart your
system. Be very careful when editing the Windows Registry. If you are
unfamiliar with using the Windows Registry editor, then ask someone else who
is familiar with the Windows Registry editor to help you.
3. In your Regional Settings, select a Western European country (Germany, France,
Italy, etc.) as your locale setting.
4. Exit and reboot the system.
Results
Ensure that the console window font that you use supports the Euro symbol (such
as Lucida Console).
Chapter 3. Getting started
115
Use options on the DSMC command
This topic shows some examples of how to use options on the dsmc command.
About this task
For example, suppose you have one workstation with node name galaxy1, and
another workstation with node name galaxy2, and you want to restore the data
from galaxy1 to the galaxy2 system. To recover a file from one workstation
(galaxy1) while at the other workstation (galaxy2), you must access galaxy1. Use
the set access command to gain access.
For example, assume the file to be recovered on galaxy1 is c:\universe\
saturn.planet. The owner of galaxy1 enters the following command:
dsmc set access archive c:\universe\saturn.planet galaxy2
When access is granted, you would retrieve the file by entering the following
command:
dsmc retrieve -fromnode=galaxy1 \\galaxy1\universe\saturn.planet c:\
Note: Access to the files of another user can also be granted and gained using the
GUI.
If you have more than one backup server in your organization, you can easily
switch between them using a command-line option. To override the server
specified in dsm.opt, you could use a command such as this:
dsmc -tcpserveraddress=myserver -node=mynode -tcpport=1599
Related reference:
“Fromnode” on page 416
“Set Access” on page 778
Specifying input strings that contain blank spaces or quotation marks
You must follow certain rules when you specify an input string that has blanks or
quotation marks.
Follow these rules when you specify an input string that has blank spaces or
quotation marks:
v If the input string has one or more spaces, enclose the string with either single
or double quotation marks. You can use single or double quotation marks, as
long as they match.
v If the input string has a single quotation mark, enclose the string within double
quotation marks, as in this example:
-description="Annual backup of the accounting department’s monthly reports"
v If the input string has a double quotation mark, enclose the string within single
quotation marks, as in this example:
-description=’New translations of "The Odyssey" and "The Iliad"’
v
If the input string has spaces and quotation marks, enclose the string in
quotation marks. The outer quotation marks must not be the same as the
quotation marks within the string.
Restriction: An input string that has single and double quotation marks is not a
valid input string.
116
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
The following rules apply to these types of data:
v Fully qualified names
v The description that you specify in the archive command
v Any value for an option value where the character string can include spaces or
quotation marks
Important: You cannot use escape characters in input strings. Escape characters are
treated the same as any other characters. Here are some examples where escape
characters are not recognized:
v If the character string is in an option file
v If the character string is in a list file
v If the character string is entered in interactive mode
|
Using the web client in the new security environment
|
|
Beginning with IBM Spectrum Protect Version 8.1.2, you can no longer use the web
client to connect to the IBM Spectrum Protect V8.1.2 or later server.
|
|
However, you can still use the web client to connect to IBM Spectrum Protect
V8.1.1, V8.1.0, or V7.1.7 or earlier servers.
|
|
If you are connected to the IBM Spectrum Protect V8.1.2 or later server, use the
following alternatives to the web client:
|
|
|
v To restore data that was backed up with the backup-archive client, use the
backup-archive client Java GUI (dsmj) or the command-line client (dsmc). For
more information, see:
|
– Chapter 4, “Backing up your data,” on page 125
|
– Chapter 5, “Restoring your data,” on page 185
|
|
|
v To back up and restore NAS file servers using Network Data Management
Protocol (NDMP), use the IBM Spectrum Protect server commands on the
administrative command-line client (dsmadmc).
|
For more information, see the following server documentation:
|
– Protecting NAS file servers
|
– Backing up and restoring NAS file servers using NDMP
|
– File-level backup and restore for NDMP operations
|
Starting a web client session
|
|
|
|
|
|
The web client is a Java Web Start application that can be started and managed
independent of web browser software. After you install and configure the web
client on your workstation, you can use the web client for remote access to
remotely back up, restore, archive, or retrieve data on the client node. The web
client facilitates the use of assistive devices for users with disabilities and contains
improved keyboard navigation.
|
Before you begin
|
|
Ensure that you configure the web client before you use it. You can use the Client
Configuration Wizard to configure the web client.
|
|
Refer to the software requirements topic for your operating system to determine
which browsers are supported by this software.
Chapter 3. Getting started
117
Procedure
|
|
|
|
|
|
1. Specify the URL of the client workstation that you installed the web client on,
in your web browser. Also, specify the HTTP port number that is defined on
the client workstation for the web client. The default port number is 1581. The
following example shows the syntax of a web client URL:
http://myhost.mycompany.com:1581
|
|
If you enter a different URL or click Back during an operation, the web client is
disconnected and the current operation ends.
|
|
Note: Backup and restore activities that are running with a NAS server
continue after the web client disconnects.
2. Follow the instructions in the IBM Spectrum Protect web client launch page to
start the web client.
Each time that you start the web client, a Java Web Start application (.jnlp file)
is downloaded to your browser. Open the dsm.jnlp file to start the web client.
|
|
|
|
|
You can close the web browser after the web client starts.
|
|
|
|
|
Tip: The web client runs in the language of the web browser's workstation
because it uses the JRE that is installed locally on the workstation. For example,
if your web browser's workstation is running in the English locale and the
remote client node is in Japanese, the web client launch page is displayed in
Japanese while the web client is in English.
|
Related concepts:
|
“Web client configuration overview” on page 27
|
|
|
|
User privileges
|
|
When a new node is registered with the server, the node must be given an
administrative user ID of the same node name with client owner authority.
|
|
|
The IBM Spectrum Protect server administrator must specify the userid parameter
with the REGISTER NODE server command:
|
|
|
where the node name and the administrative user ID must be the same. For
example:
|
|
|
|
|
Tip: You can use the revokeremoteaccess option to prevent IBM Spectrum Protect
administrators with client access privilege from performing client operations on
your workstation through the web client. However, IBM Spectrum Protect
administrators with client owner privilege, system privilege, or policy privilege can
still perform client operations on your workstation through the web client.
|
Related concepts:
|
“IBM Spectrum Protect client authentication” on page 111
|
Related reference:
|
“Revokeremoteaccess” on page 507
If you plan to use the web client, ensure that you are assigned an administrative
user ID with system privilege, policy privilege, client access authority, or client
owner authority.
REGISTER NODE node_name password userid=user_id
REGISTER NODE node_a mypassw0rd userid=node_a
118
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Start the client scheduler automatically
You can start the client scheduler automatically when you start your workstation.
If the IBM Spectrum Protect administrator has defined schedules for your node,
starting the client scheduler permits you to automatically back up your
workstation (or perform other scheduled actions).
You can also use the IBM Spectrum Protect Client Acceptor service to manage the
scheduler.
IBM Spectrum Protect supports remote network connections to the server. With a
remote network connection, mobile users no longer need to dial-in to their
company network when a backup is scheduled to run. IBM Spectrum Protect
automatically establishes a connection before the scheduled backup occurs. If the
connection fails, IBM Spectrum Protect reestablishes the connection before
attempting the backup.
Related tasks:
“Setting the client scheduler process to run as a background task and start
automatically at startup” on page 246
Changing your password
Your IBM Spectrum Protect administrator can require you to use a password to
connect to the server.
About this task
The backup-archive client prompts you for the password if one is required. Contact
your IBM Spectrum Protect administrator if you do not know your password.
Important: The password discussed in this topic is different than the password
used for encrypting files.
To change your password from the GUI:
Procedure
1. From the main window, open the Utilities menu and select Change password.
2. Enter your current and new passwords, and enter your new password again in
the Verify password field.
3. Click Change.
Results
To change your password from the command-line client, enter this command:
For UNIX, Linux, and Windows clients:
dsmc set password
Then, enter your old and new passwords when prompted.
Passwords can be up to 63 character in length. Password constraints vary,
depending on where the passwords are stored and managed, and depending on
the version of the IBM Spectrum Protect server that your client connects to.
Chapter 3. Getting started
119
If your IBM Spectrum Protect server is at version 6.3.3 or later, and if you use an
LDAP directory server to authenticate passwords
Use any of the following characters to create a password:
a
A
0
|
b
B
1
{
c
C
2
}
d
D
3
[
e
E
4
]
f
F
5
:
g
G
6
;
h
H
7
<
i
I
8
>
j
J
9
,
k
K
.
?
l
L
!
/
m n o p q r s t u v w x y z
M N O P Q R S T U V W X Y Z
@ # $ % ^ & * _ - + = ` ( )
~
Passwords are case-sensitive and are subject to more restrictions that can
be imposed by LDAP policies.
If your IBM Spectrum Protect server is at version 6.3.3 or later, and if you do not
use an LDAP directory server to authenticate passwords
Use any of the following characters to create a password:
a
A
0
|
b
B
1
{
c
C
2
}
d
D
3
[
e
E
4
]
f
F
5
:
g
G
6
;
h
H
7
<
i
I
8
>
j
J
9
,
k
K
.
?
l
L
!
/
m n o p q r s t u v w x y z
M N O P Q R S T U V W X Y Z
@ # $ % ^ & * _ - + = ` ( )
~
Passwords are stored in the IBM Spectrum Protect server database and are
not case-sensitive.
If your IBM Spectrum Protect server is earlier than version 6.3.3
Use any of the following characters to create a password:
a
A
0
_
b
B
1
-
c
C
2
&
d
D
3
+
e f g h i j k l m n o p q r s t u v w x y z
E F G H I J K L M N O P Q R S T U V W X Y Z
4 5 6 7 8 9
.
Passwords are stored in the IBM Spectrum Protect server database and are
not case-sensitive.
Remember:
On the command line, enclose all parameters that contain one or more special
characters in quotation marks. Without quotation marks, the special characters can
be interpreted as shell escape characters, file redirection characters, or other
characters that have significance to the operating system.
On Windows systems:
Enclose the command parameters in quotation marks (").
Command line example:
dsmc set password "t67@#$%^&" "pass2><w0rd"
Quotation marks are not required when you type a password with special
characters in an options file.
Related concepts:
“Start the client scheduler automatically” on page 119
Related reference:
“Password” on page 474
“Set Password” on page 784
Sorting file lists using the backup-archive client GUI
You can use the backup-archive client GUI to display, sort, or select files.
120
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
About this task
Table 15. Working with your files using the backup-archive client GUI
Task
Procedure
Displaying files
To display files in a directory, click the folder icon next to the
directory name. The files appear in the File List box on the
right.
Sorting the file list
v Click the appropriate column heading in the File List box.
Display active and inactive
backup versions
v Click the Display Active/Inactive Files option from the
View menu.
v Click the Display both active and inactive files tool on the
tool bar.
Display only active backup
versions
Click the Display active files only option from the View
menu.
Selecting files to restore or
retrieve.
v Click the selection box next to the directory or file name
that you want to restore or retrieve.
v Highlight the files that you want to restore or retrieve and
click the Select Items tool on the tool bar.
v Highlight the files that you want to restore or retrieve and
click the Select Items option from the Edit menu.
Deselecting files
v Click the checked selection box next to the directory or file
name.
v Highlight the files that you want to deselect and click the
Deselect Items tool on the tool bar.
v Highlight the files that you want to deselect and click the
Deselect Items option from the Edit menu.
Displaying file information
v Highlight the file name, and click the View File Details
button on the tool bar.
v Highlight the file name, and select File Details from the
View menu.
Note:
1. Unless otherwise noted, the tasks and procedures in the above table apply to
all client GUIs.
2. Using the client GUIs, you can sort a list of files by various attributes, such as
name, directory, size, or modification date. Sorting files by the last backup date
can be useful in determining what date and time to use for the point-in-time
function.
3. An active file is the most recent backup version of a file that existed on your
workstation when you ran your last backup. All other backup versions of that
file are inactive. Only active backup versions of files are displayed, unless you
select the Display active/inactive files menu option. If you delete the file from
your workstation, the active version becomes inactive the next time you run an
incremental backup.
On the command-line client, you can use query commands with the inactive
option to display both active and inactive objects. You can use restore
commands with the pick and inactive options to produce the list of active and
inactive backups to choose from.
Related reference:
“Inactive” on page 424
“Pick” on page 477
Chapter 3. Getting started
121
Displaying online help
You can display online help in any of the following ways: On the backup-archive
client GUI, from the web client, or from the dsmc command line.
About this task
v On the backup-archive client GUI:
– Open the help menu. Click Help or press F1.
– Click the Help button in the current window.
v From the dsmc command line: Enter the help command. The complete table of
contents for the available help text is displayed.
Related reference:
“Help” on page 689
Ending a session
You can end a client session from the backup-archive client GUI or from the dsmc
command line.
About this task
v
From the backup-archive client GUI main window:
– Click File > Exit.
– Press Alt-X.
– For the web client: Open a different URL or close the browser.
v From the DSMC command line:
– In batch mode, each dsmc command you enter is a complete session. The
client ends the session when it finishes processing the command.
– To end an interactive session, enter quit at the protect> prompt.
– To interrupt a dsmc command before the client has finished processing, enter
QQ on the IBM Spectrum Protect console. In many cases but not all, this
interrupts the command. If the command cannot be interrupted, use the
Windows Task Manager to end the dsmc process. Do not press Ctrl-C
because, while it ends the session, it can lead to unexpected results.
Related reference:
“Loop” on page 698
Online forums
To participate in user discussions of IBM Spectrum Protect products, you can
subscribe to the ADSM-L list server.
About this task
This is a user forum maintained by Marist College. While not officially supported
by IBM, product developers and other IBM support staff also participate on an
informal, best-effort basis. Because this is not an official IBM support channel, you
should contact IBM Technical Support if you require a response specifically from
IBM. Otherwise there is no guarantee that IBM will respond to your question on
the list server.
You can subscribe by sending a note to the following e-mail address:
listserv@vm.marist.edu
122
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
The body of the message must contain the following:
SUBSCRIBE ADSM-L yourfirstname yourlastname
The list server will send you a response asking you to confirm the subscription
request. Once you confirm your subscription request, the list server will send you
further instructions. You will then be able to post messages to the list server by
sending e-mail to:
ADSM-L@vm.marist.edu
If at a later time you want to unsubscribe from ADSM-L, you can send a note to
the following e-mail address:
listserv@vm.marist.edu
The body of the message must contain the following:
SIGNOFF ADSM-L
You can also read and search the ADSM-L archives, join discussion forums, and
access other resources at the following URL:
http://www.adsm.org
Chapter 3. Getting started
123
124
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chapter 4. Backing up your data
Use the backup-archive client to store backup versions of your files on the IBM
Spectrum Protect server. You can restore these backup versions if the original files
are lost or damaged.
All client backup and restore procedures also apply to the web client.
Restriction: The web client does not provide a Preferences Editor for setting client
options. The web client does not offer a Setup wizard, which is available in the
backup-archive client GUI on Windows clients. The web client cannot browse
network resources.
Unless otherwise specified, references to Windows refer to all supported Windows
operating systems.
The client provides backup and archive services for all files on the following file
systems: File Allocation Table (FAT), FAT 32, NTFS, and ReFS.
The following is a list of primary backup tasks.
v “Planning your backups (Windows)”
v “Pre-backup considerations (Windows)” on page 134
v “Incremental, selective, or incremental-by-date backups (Windows)” on page 139
v “Deleting backup data” on page 132
v “Backing up files from one or more file spaces for a group backup (Windows)”
on page 147
v “Backing up Windows system state” on page 152
v “Backing up Automated System Recovery files” on page 153
v “Image backup” on page 156
v “Back up NAS file systems using Network Data Management Protocol” on page
162
v “Preparing the environment for full backups of VMware virtual machines” on
page 169
v “Back up virtual machines on a Hyper-V system” on page 173
v “Backing up Net Appliance CIFS share definitions” on page 174
Planning your backups (Windows)
If you are a first-time user, or if you only back up files occasionally, you can use
the table in this topic as a checklist of preliminary steps to consider before
performing a backup.
Read the tasks listed in this table to determine whether you are ready to back up
your data.
Table 16. Planning your backups
h
© Copyright IBM Corp. 1993, 2017
Decide whether you want to back up or archive files. See “When to back up and
when to archive files” on page 133 for more information.
125
Table 16. Planning your backups (continued)
h
See “Pre-backup considerations (Windows)” on page 134 for important migration
information, and how you might increase performance before backing up files
and directories.
h
Create an include-exclude list to specify files and directories you want to exclude
from backup services. See “Control processing with an include-exclude list” on
page 137 for more information.
h
Decide what type of backup you want according to your needs. See the following
sections for more information:
v “Incremental, selective, or incremental-by-date backups (Windows)” on page
139
v “Backing up files from one or more file spaces for a group backup (Windows)”
on page 147
v “Backing up Windows system state” on page 152
v “Backing up Automated System Recovery files” on page 153
v “Image backup” on page 156
v “Back up NAS file systems using Network Data Management Protocol” on
page 162
v “Parallel backups of virtual machines” on page 173
h
For additional backup considerations, see “Backup (Windows): Additional
considerations” on page 177.
Related concepts:
Chapter 1, “Installing the IBM Spectrum Protect backup-archive clients,” on page 1
Which files are backed up
When you request a backup, the client backs up a file if certain requirements are
met.
To back up a file, the client must meet the following are the requirements:
v The selected management class contains a backup copy group.
v The file meets the serialization requirements that are defined in the backup copy
group. If the copy group serialization parameter is static or shrstatic, and the
file changes during backup, the file is not backed up.
v The file meets the mode requirements that are defined in the backup copy group.
If the copy group mode parameter is modified, the file must have changed since
the last backup. If the mode is absolute, the file can be backed up even if it does
not change.
v The file meets the frequency requirements that are defined in the backup copy
group. The specified minimum number of days since the last backup must
elapse before a file is backed up.
v The file is not excluded from backup by an exclude statement.
v The file is not excluded from backup by the operating system. These excluded
files can be found in registry subkey HKEY_LOCAL_MACHINE\SYSTEM\
CurrentControlSet\Control\BackupRestore\FilesNotToBackup.
Files that are part of the Windows system state are eligible for backup only when
the system state is backed up. You can back up the system state only as a single
entity because of dependencies among the system state components. You cannot
back up or restore the files individually. For example, because
126
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
C:\windows\system32\ntoskrnl.exe is part of the Windows system state, it is not
backed up during an incremental or selective backup of the C:\ drive.
Related concepts:
Chapter 9, “Storage management policies,” on page 261
“Management classes and copy groups” on page 262
Related tasks:
“Backing up Windows system state” on page 152
Related reference:
“Absolute” on page 318
Open file support for backup operations
The VSS snapshot provider is used for open file support.
VSS is the snapshot provider for Windows.
Some applications can create files and open these files in a way that denies access
to all other processes on a Microsoft Windows operating system. Although this is
not a common practice, it is sometimes used by database vendors or other
applications that might want to limit access to certain files. By restricting access to
these files, backup products are prevented from backing up the data. These locked
files are not the same as files that are open, or in use. The backup-archive client,
running without the open file support (OFS) feature, can back up open, or in use
files, including files that are open for reading or writing, files that are changing
during the backup, executable and dll files that are running, log files that are being
appended to, and so on.
You can create OFS or online image backups on workstations with a single
NTFS-based, or ReFS-based, C:\ drive.
The following is the error message that is seen in the dsmerror.log when the client
encounters one of these locked files without OFS support enabled:
ANS4987E Error processing ’\\machine1\d$\dir1\lockedfile.xyz’: the object is in use
by another process
ANS1228E Sending of object ’\\machine1\d$\dir1\lockedfile.xyz’ failed
Do not use OFS for backing up locked Windows system files, such as the Windows
system state. The client has advanced features for backing up data that is
contained within these files. The backup of the system data that is contained in
these files requires extra processing and must be backed up in a group to allow for
a successful restore. These files are excluded from IBM Spectrum Protect file level
backup.
For database applications that use certain files for transactional consistency (for
example, a recovery log file), it might not be possible to back up and restore these
files without database coordination. In these situations, do not back up these
database files with the normal file level backup. You can exclude these files from
backup processing by using an exclude or exclude.dir statement. A number of
data protection clients (IBM Spectrum Protect for Databases, IBM Spectrum Protect
for Mail, and so on) are available to provide this database coordination and backup
along with other advanced database backup features. For a current list of data
protection clients go to this website: http://www.ibm.com/systems/storage/
spectrum/protect/.
Chapter 4. Backing up your data
127
For private applications or other database products where a Data Protection client
is not available, you can use the preschedulecmd option to signal the database or
application to do one of the following actions:
v Take the steps necessary to move these files to a consistent and unopen state.
v Bring down the database before the file level backup is started.
v Program or script another method to back up this data and exclude these files
from the file level backup. In these cases the OFS feature is not necessary since
these files are no longer unavailable or locked by the application. After the file
level backup completes, use the postschedulecmd option to bring the database
back online or restart the application.
If the time it takes to complete the file level backup is too long to have the open
files offline (for example, having the database offline or holding up transactions),
use the OFS feature to create a point-in-time snapshot of the volume. In this case,
use the presnapshotcmd and postsnapshotcmd options to signal the database or
application to coordinate with the backup of these open files. The snapshot, which
occurs between the pre-snapshot command and post-snapshot command, generally
takes only a few seconds to create. This allows the database or application to
resume operations quickly while still allowing the client to perform a full
incremental backup of the volume, including the locked files. There are other
situations where these application-locked files can be safely backed up and
restored on a file-by-file basis. In these situations, you can enable the OFS feature
for that volume where the open files exist. The client then has access to these files
and back them up using file level backup and archive operations.
For information about Open File Support restrictions and issues, see technote
1248971.
If open file support has been configured, the client performs a snapshot backup or
archive of files that are locked (or "in use") by other applications. The snapshot
allows the backup to be taken from a point-in-time copy that matches the file
system at the time the snapshot is taken. Subsequent changes to the file system are
not included in the backup. You can set the snapshotproviderfs parameter of the
include.fs option to none to specify which drives do not use open file support.
To control an open file support operation, you can specify these additional options
in your dsm.opt file or as values of the include.fs option: snapshotproviderfs,
and presnapshotcmd and postsnapshotcmd.
Note:
1. You can use the include.fs option to set snapshot options on a per file system
basis.
2. Open file support is provided for both backup and archive. For backup, this
includes incremental, incremental by date, selective, incremental image, and
journal-based backup.
3. Open file support is only available for local fixed volumes (mounted to either
drive letters or volume mount points) formatted with FAT, FAT32, NTFS, or
ReFS file systems. This support includes SAN-attached volumes that meet these
requirements.
4. To enable OFS support in a cluster environment, all workstations in the cluster
must have OFS configured. Set VSS as the snapshot provider on the
snapshotproviderfs option.
Related concepts:
Chapter 11, “Processing options,” on page 291
128
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Related tasks:
“Backing up Windows system state” on page 152
“Configuring Open File Support” on page 78
Backing up data using the GUI
You can use the backup-archive client GUI to back up specific files, a group of files
with similar names, or entire directories.
About this task
You can locate the files that you want to back up by searching or filtering. Filtering
displays only the files that match the filter criteria for your backup. Files that do
not match the filter criteria do not display.
To perform a GUI backup, use the following steps:
Procedure
1. Click Backup from the GUI main window. The Backup window appears.
2. Expand the directory tree by clicking the plus sign +. To display files in a
folder, click the Folder icon. To search or filter files, click the Search icon from
the toolbar.
3. Click the selection box for the objects that you want to back up.
4. Select the type of backup from the pull-down menu:
a. To run an incremental backup, select Incremental (complete).
b. To run an incremental backup by date, select Incremental (date only).
c. To run a selective backup, select Always backup.
d. To run an incremental backup without using the journal database, select
Incremental (without journal). If you installed the journal engine service
and it is running, then by default the Incremental command automatically
performs a journal-based backup on selected file systems that are being
monitored by the journal engine service. This option performs a traditional
full incremental backup, instead of the default journal-based backup.
5. Click Backup. The Backup Task List window displays the backup processing
status. When processing completes, the Backup Report window displays
processing details.
Results
The following are some items to consider when you use the GUI to back up your
data.
v IBM Spectrum Protect uses management classes to determine how to manage
your backups on the server. Every time you back up a file, the file is assigned a
management class. The management class that is used is either a default that is
selected for you, or one that you assign to the file using an include option in the
include-exclude options list. Select Utilities → View Policy Information from the
backup-archive client or web client GUI to view the backup policies that are
defined by the IBM Spectrum Protect server for your client node. Select Edit →
Client Preferences from the backup-archive client or web client GUI and select
the Include-Exclude tab in the Preferences editor to display your
include-exclude list.
v To modify specific backup options, click the Options button. Any options that
you change are effective during the current session only.
Chapter 4. Backing up your data
129
v To perform subsequent incremental backups, from the IBM Spectrum Protect
main window, open the Actions menu and select Backup Domain.
v The web client GUI cannot browse network resources to perform a backup. No
shares are listed if you expand the Network branch. It is possible to backup a
network resource from the web client as long as the entire file is processed. To
do this, the filesystem is specified using the domain option in dsm.opt. E.g.
domain all-local \\server\share. To complete the backup, select Backup
Domain from the Action menu. This processes all the filesystems that are
specified with the domain option. Alternatively, you can use the GUI Client to
perform the backup.
Related concepts:
Chapter 9, “Storage management policies,” on page 261
Related tasks:
“Restoring data by using the GUI” on page 187
“Setting the client scheduler process to run as a background task and start
automatically at startup” on page 246
Specifying drives in your domain
When you start the client, it sets your default domain to the drives you specify
with the domain option in the dsm.opt file.
About this task
If you do not set the domain option, the default domain is all local fixed drives (the
drives on your workstation).
You can exclude any domain (including the systemobject domain) in your default
domain from backup processing using the Backup tab in the Preferences editor.
You can also exclude drives or the systemobject domain by specifying the dash (-)
operator before the drive or the systemobject domain. For example, in the
following option the client processes all local drives except for the c: drive and
systemobject domain:
domain ALL-LOCAL -c: -systemobject
Using the backup-archive client command line interface, you can specify drives to
include in addition to your default domain. For example, if your default domain
contains drives c: and d:, and you want to back up those drives as well as the
diskette in drive a:, enter:
dsmc incremental -domain="a:"
You can also select Actions > Backup Domain from the backup-archive client GUI
to perform these backup functions.
Related reference:
“Domain” on page 367
Backing up data using the command line
You can use the incremental or selective commands to perform backups. The
following table shows examples of using commands to perform different tasks.
130
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
About this task
Table 17. Command line backup examples
Task
Command
Considerations
Incremental backups
Perform an incremental
dsmc incremental
backup of your client domain.
See “Incremental” on page 691 for
more information about the
incremental command. See “Full and
partial incremental backup” on page
139 for detailed information about
incremental backups.
Back up the g: and h: drives
in addition to the c:, d:, and
e: drives defined in your
client domain.
See “Domain” on page 367 for more
information about the domain option.
dsmc incremental -domain="g: h:"
Back up all local volumes
dsmc incremental -domain="all-local -c:
defined in your client domain -systemobject"
except for the c: drive and
systemobject domain.
You cannot use the (-) operator in
front of the domain keyword all-local.
See “Domain” on page 367 for more
information. For Windows clients you
can also exclude the systemstate
domain from backup processing in
this way.
Back up all local volumes
dsmc incremental -domain="all-local -c:
defined in your client domain -systemstate"
except for the c: drive and
systemstate domain.
You cannot use the (-) operator in
front of the domain keyword all-local.
See “Domain” on page 367 for more
information.
Back up only the g: and h:
drives.
dsmc incremental g: h:
None
Back up all files in the
c:\Accounting directory and
all its subdirectories.
dsmc incremental c:\Accounting\* -sub=yes See “Subdir” on page 549 for more
information about the subdir option.
Assuming that you initiated a dsmc incremental c: -snapshot=
snapshot of the C: drive and \\florence\c$\snapshots\
mounted the snapshot as the snapshot.0
logical volume \\florence\
c$\snapshots\snapshot.0, run
an incremental backup of all
files and directories under the
local snapshot and manage
them on the IBM Spectrum
Protect server under the file
space name C:.
See “Snapshotroot” on page 537 for
more information.
Incremental-by-date backup
Perform an
dsmc incremental -incrbydate
incremental-by-date backup
of your default client domain.
Use the incrbydate option with the
incremental command to back up
new and changed files with a
modification date later than the last
incremental backup stored at the
server. See “Incrbydate” on page 442
for more information about the
incrbydate option.
Selective backups
Chapter 4. Backing up your data
131
Table 17. Command line backup examples (continued)
Task
Command
Considerations
Back up all files in the
d:\proj directory.
dsmc selective d:\proj\
Use the selective command to back
up specific files, a group of files with
similar names, or empty directories
and their attributes regardless of
whether those files or directories were
backed up during your last
incremental backup and without
affecting the last incremental backup
count from the backup server. You can
use wildcards to back up multiple
files at once. See “Selective” on page
775 for more information about the
selective command.
Back up the d:\proj directory dsmc selective d:\proj\ -subdir=yes
and all its subdirectories.
See “Subdir” on page 549 for more
information about the subdir option.
Back up the d:\h1.doc and
d:\test.doc files.
dsmc selective d:\h1.doc d:\test.doc
You can specify as many file
specifications as available resources or
other operating system limits permit.
Separate file specifications with a
space. You can also use the filelist
option to process a list of files. The
backup-archive client opens the file
you specify with this option and
processes the list of files within
according to the specific command.
See “Filelist” on page 410 for more
information.
Back up a list of files in the
c: drive.
dsmc selective -filelist=c:\filelist.txt
Use the filelist option to process a
list of files. See “Filelist” on page
410 for more information.
Assuming that you initiated a dsmc selective c:\dir1\sub1\* -subdir=yes See “Snapshotroot” on page 537 for
snapshot of the C: drive and snapshot=\\florence\c$\snapshots\
more information.
mounted the snapshot as the snapshot.0
logical volume \\florence\
c$\snapshots\snapshot.0, run
a selective backup of the
c:\dir1\sub1 directory tree
from the local snapshot and
manage it on the IBM
Spectrum Protect server
under the file space name C:.
Related concepts:
“Backup (Windows): Additional considerations” on page 177
Chapter 12, “Using commands,” on page 635
Deleting backup data
If your administrator has given you authority, you can delete individual backup
copies from the IBM Spectrum Protect server without deleting the entire file space.
132
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
About this task
For example, you might need to delete sensitive data that was backed up
(intentionally or unintentionally), and now needs to be removed from the server.
Or you might need to delete files that were backed up, but were later found to
contain viruses. To determine if you have the authority to delete individual backup
copies from the IBM Spectrum Protect server without deleting the entire file space,
select File → Connection Information from the backup-archive client GUI or web
client main menu. Your authority status is provided in the Delete Backup Files
field.
Important: When you delete backup files, you cannot restore them. Verify that the
backup files are no longer needed before you delete them. IBM Spectrum Protect
prompts whether you want to continue with the delete. If you specify yes, the
specified backup files are immediately deleted and removed from IBM Spectrum
Protect server storage.
To delete backup copies using the IBM Spectrum Protect GUI or web client:
Procedure
1. Select Delete Backup Data from the Utilities menu. The Backup Delete
window appears.
2. Expand the Directory tree by clicking the plus sign (+) or folder icon next to
the object you want to expand.
3. Select an item from the drop-down list near the top of the Backup Delete
window to specify the type of backup delete to perform. You can delete active
backup versions, inactive backup versions, or all objects that you have selected
in the tree. A directory is deleted only if you select Delete All Objects.
Results
To delete backup copies using the IBM Spectrum Protect command line client, use
the delete backup command.
Related reference:
“Delete Backup” on page 681
When to back up and when to archive files
When the backup-archive client backs up or archives a file, it sends a copy of the
file and its associated attributes to the server; however, backup and archive
operations have different results.
Use backups to protect against unforeseen damage to your files, and use archives
for maintaining more permanent versions of your files.
Backup data is managed by version by using predetermined policy-based rules.
Using these rules, the IBM Spectrum Protect administrator can control the
following processes:
v The number of versions that are maintained on the IBM Spectrum Protect server
v The number of days each additional backup copy is kept
v What happens to backup versions when the file is deleted on the client system
Each copy of the file that is stored on the server is considered to be a separate and
unique version of the file.
Chapter 4. Backing up your data
133
Archive is a powerful and flexible mechanism for storing long-term data. Archive
data, called archive copies, are kept for a specified number of days. The archive
function has no concept or support for versions. The user or administrator is
responsible for determining what files get added to an archive.
Tip: If a file is archived multiple times by using the same archive description, a
new copy of the file is added to the archive each time that archive is operation
run. To simplify the retrieve operation, store only one copy of a file in each
archive.
Backups protect against file damage or loss that can occur through accidental
deletion, corruption, or disk crashes. The server maintains one or more backup
versions for each file that you back up. Older versions are deleted as newer
versions are made. The number of backup versions the server maintains is set by
your administrator.
Archive copies are saved for long-term storage. Your administrator can limit how
long archive copies are kept. The server can store an unlimited number of archive
versions of a file. Archives are useful if you must go back to a particular version of
your files, or you want to delete a file from your workstation and retrieve it later,
if necessary. For example, you might want to save spreadsheets for tax purposes,
but because you are not using them, you do not want to leave them on your
workstation.
Related concepts:
“Restore data from a backup set” on page 196
Pre-backup considerations (Windows)
Various factors in your system or environment can affect the way the
backup-archive client processes data. Review these considerations before you back
up your data.
LAN-free data movement
LAN-free data movement shifts the movement of client data from the
communications network to a storage area network (SAN). This decreases the load
on the IBM Spectrum Protect server.
The SAN provides a path that allows you to back up, restore, archive, and retrieve
data to and from a SAN-attached storage device. Client data moves over the SAN
to the storage device using the IBM Spectrum Protect Storage Agent. The Storage
Agent must be installed on the same system as the client.
All Windows clients support LAN-free data movement.
LAN-free prerequisites
To enable LAN-free support, you must install and configure the IBM Spectrum
Protect for SAN storage agent on the client workstation.
IBM Spectrum Protect for SAN is a separate product.
For more information about installing and configuring the storage agent, see the
documentation for IBM Spectrum Protect for SAN.
134
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
LAN-free data movement options
To enable LAN-free data movement, you can use several client options. You must
first install and configure the IBM Spectrum Protect for SAN storage agent on the
client workstation.
Use the following options to enable LAN-free data movement:
enablelanfree
Specifies whether to enable an available LAN-free path to a SAN-attached
storage device.
lanfreecommmethod
Specifies a communication protocol between the client and the Storage Agent.
lanfreeshmport
Specifies the unique number that is used by the client and the storage agent to
identify shared memory area used for communications.
lanfreetcpport
Specifies the TCP/IP port number where the Storage Agent is listening.
lanfreetcpserveraddress
Specifies the TCP/IP address for the storage agent.
Related reference:
“Enablelanfree” on page 387
“Lanfreecommmethod” on page 447
“Lanfreeshmport” on page 448
“Lanfreessl” on page 450
“Lanfreetcpport” on page 449
“Lanfreetcpserveraddress” on page 451
Unicode file spaces (Windows)
The Windows client is Unicode-enabled. However, client versions before Version
4.2 were not enabled for Unicode.
If you are backing up a system that had at one time used a client version older
than Version 4.2, and the file spaces have not yet been migrated to Unicode, then
you need to plan for the migration of file spaces to Unicode. This involves
renaming your file spaces on the server and creating new Unicode-enabled file
spaces on the server using the autofsrename option.
Related concepts:
“Considerations for Unicode-enabled clients” on page 425
Related reference:
“Autofsrename” on page 329
“Detail” on page 359
“Query Filespace” on page 714
“Restore” on page 737
“Retrieve” on page 769
Incremental backups on memory-constrained systems
Incremental backup performance suffers if the system has a low amount of
memory available before starting the backup.
Chapter 4. Backing up your data
135
If your system is memory constrained, specify the memoryefficientbackup yes
option in your client options file. This option causes the backup-archive client to
process only one directory at a time, which reduces memory consumption but
increases backup time. When you specify yes, the client analyzes only one directory
at a time for backup consideration. If performance remains poor, check your
communication buffer settings and the communication link between your system
and the IBM Spectrum Protect server. If your system is not memory constrained,
setting the memoryefficientbackup option to yes degrades your backup
performance.
Related reference:
“Memoryefficientbackup” on page 458
Incremental backups on systems with a large number of files
The client can use large amounts of memory to run incremental backup operations,
especially on file systems that contain large numbers of files.
The term memory as used here is the addressable memory available to the client
process. Addressable memory is a combination of physical RAM and virtual
memory.
On average, the client uses approximately 300 bytes of memory per object (file or
directory). Thus for a file system with one million files and directories, the client
requires, on average, approximately 300 MB of memory. The exact amount of
memory that is used per object varies, depending on the length of the object path
and name length, or the nesting depth of directories. The number of bytes of data
is not an important factor in determining the backup-archive client memory
requirement.
The maximum number of files can be determined by dividing the maximum
amount of memory available to a process by the average amount of memory that
is needed per object.
The total memory requirement can be reduced by any of the following methods:
v Use the client option memoryefficientbackup diskcachemethod. This choice
reduces the use of memory to a minimum at the expense of performance and a
significant increase in disk space that is required for the backup. The file
description data from the server is stored in a disk-resident temporary database,
not in memory. As directories on the workstation are scanned, the database is
consulted to determine whether to back up, update, or expire each object. At the
completion of the backup, the database file is deleted.
v Use the client option memoryefficientbackup yes. The average memory that is
used by the client then becomes 300 bytes times the number of directories plus
300 bytes per file in the directory that is being processed. For file systems with
large numbers (millions) of directories, the client still might not be able to
allocate enough memory to perform incremental backup with
memoryefficientbackup yes.
v If the client option resourceutilization is set to a value greater than 4, and
multiple file systems are being backed up, then reducing resourceutilization to
4 or lower limits the process to incremental backup of a single file system at a
time. This setting reduces the memory requirement. If the backup of multiple file
systems in parallel is required for performance reasons, and the combined
memory requirements exceed the process limits, then multiple instances of the
backup client can be used to back up multiple file systems in parallel. For
example, if you want to back up two file systems at the same time but their
136
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
memory requirements exceed the limits of a single process, then start one
instance of the client to back up one of the file systems, and start a second
instance of the client to back up the other file system.
v Use the - incrbydate client option to perform an "incremental-by-date" backup.
v Use the exclude.dirclient option to prevent the client from traversing and
backing up directories that do not need to be backed up.
v Reduce the number of files per file system by spreading the data across multiple
file systems.
Related reference:
“Snapdiff” on page 528
“Exclude options” on page 395
“Incrbydate” on page 442
“Memoryefficientbackup” on page 458
“Resourceutilization” on page 504
Control processing with an include-exclude list
There might be files on your system that you do not want to back up. These files
might be operating system or application files that you can easily recover by
reinstalling the program, or any other file that you can easily rebuild.
Use the include and exclude options in the client options file (dsm.opt) to define
which files to include or exclude from incremental or selective backup processing.
A file is eligible for backup unless excluded by an exclude option. It is not
necessary to use an include option to include specific files for backup unless those
files are in a directory that contains other files that you want to exclude.
The include-exclude list might contain items that are specified by the server. To
view the contents of your include-exclude list, use the query inclexcl command.
IBM Spectrum Protect uses management classes to determine how to manage your
backups on the server. Every time you back up a file, the file is assigned a
management class. The management class is either a default that is chosen for you,
or one you assign to the file by using the include option in the include-exclude
list. If you assign a management class, it must contain a backup copy group for the
file to be backed up.
You can also add include-exclude statements in the backup-archive client GUI
directory tree. You can use the preview command to see the resultant effects of the
currently defined include-exclude list without need of running an actual backup
operation.
Related tasks:
“Creating an include-exclude list” on page 88
“Setting the client scheduler process to run as a background task and start
automatically at startup” on page 246
Related reference:
“Preview Backup” on page 702
Data encryption during backup or archive operations
For the strongest possible encryption, use 256-bit Advanced Encryption Standard
(AES) data encryption, with the encryptiontype option. AES 128-bit encryption is
currently the default.
Chapter 4. Backing up your data
137
The data that you include is stored in encrypted form, and encryption does not
affect the amount of data sent or received.
Attention: If the encryption key password is not saved in the Windows Registry,
and you have forgotten the password, your data cannot be recovered.
The include.encrypt option is the only way to enable encryption on the
Backup-Archive client. If no include.encrypt statements are used, encryption will
not occur.
Encryption is not compatible with VMware virtual machine backups that use the
incremental forever backup modes (MODE=IFIncremental and MODE=IFFull). If the
client is configured for encryption, you cannot use incremental forever backup.
To encrypt file data, you must select an encryption key password, which the client
uses to generate the encryption key for encrypting and decrypting the file data.
You can specify whether to save the encryption key password in the Windows
Registry by using the encryptkey option.
IBM Spectrum Protect client encryption allows you to enter a value of up to 63
characters in length. This encryption password needs to be confirmed when
encrypting the file for backup, and also needs to be entered when performing
restores of encrypted files.
While restoring an encrypted file, you are prompted for the key password to
decrypt the file in the following cases:
v If the encryptkey option is set to Prompt.
v If the key supplied by the user does not match.
v If the encryptkey option is set to Save and the locally saved key password does
not match the encrypted file.
Related concepts:
“Backup (Windows): Additional considerations” on page 177
Related reference:
“Encryptiontype” on page 388
“Encryptkey” on page 389
“Exclude options” on page 395
“Include options” on page 426
Maximum file size for operations
The maximum file sizes for backup and restore, and archive and retrieve
operations depends on the Windows file system that is used.
The following table shows the maximum file size, in bytes, for backing up,
restoring, and retrieving data.
Table 18. Maximum file size
138
File system
Maximum file size (in bytes)
FAT16
2 147 483 647 (2 GB)
FAT32
4 294 967 295 (4 GB)
NTFS and ReFS
17 592 185 978 880 (16 TB-64 K)
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
How the client handles long user and group names
The backup-archive client can handle user and group names that are up to 64
characters without any issues. However, names longer than 64 characters require
special handling.
Restriction: Do not exceed the 64-character limit for user and group names. The
client shortens the name to fall within this limit by using the following algorithm:
Use the first 53 characters, append a forward slash (/), and then use the numeric
ID as a character string.
An error message is logged that contains both the long name and the resulting
shortened string. For most functions, you do not need to be aware of the shortened
name. The exceptions are:
v The set access command
v The fromowner option
v The users and groups (authorization) options
In each of these cases, when you need to enter a name, you either have to find the
error message containing the transformation, or construct the name using the rule
outlined here.
Incremental, selective, or incremental-by-date backups (Windows)
Your administrator might set up schedules to automatically back up files. This
section contains information about how to back up files without a schedule.
There are three types of incremental backup: full, partial, and incremental-by-date.
If you migrate files with IBM Spectrum Protect HSM for Windows, there can be
consequences for backup operations.
Related concepts:
Backup and restore of migrated files
Related tasks:
“Setting the client scheduler process to run as a background task and start
automatically at startup” on page 246
Full and partial incremental backup
An incremental backup backs up only new and changed files. The type of
incremental backup depends on what objects you select to be backed up.
If you select entire drives, the backup is a full incremental backup. If you select a
directory tree or individual files, the backup is a partial incremental backup.
The first time that you run a full incremental backup, the backup-archive client
backs up all the files and directories that you specify. The backup operation can
take a long time if the number of files is large, or if one or more large files must be
backed up. Subsequent full incremental backups only back up new and changed
files. The backup server maintains current versions of your files without having to
waste time or space by backing up files that exist in IBM Spectrum Protect server
storage.
Depending on your storage management policies, the IBM Spectrum Protect server
might keep more than one version of your files in storage. The most recently
Chapter 4. Backing up your data
139
backed up files are active backup versions. Older copies of your backed up files
are inactive versions. However, if you delete a file from your workstation, the next
full incremental backup causes the active backup version of the file to become
inactive. You can restore an inactive version of a file. The number of inactive
versions that are maintained by the server and how long they are retained is
governed by the management policies that are defined by your IBM Spectrum
Protect server administrator. The active versions represent the files that existed on
your file system at the time of the last backup.
To start a full or partial incremental backup by using the client GUI, select Backup,
and then select the Incremental (complete) option. From the command line, use
the incremental command and specify file systems, directory trees, or individual
files to include in the backup.
During an incremental backup, the client queries the server or the journal database
to determine the exact state of your files since the last incremental backup. The
client uses this information for the following tasks:
v Back up new files.
v Back up files whose contents changed since the last backup.
Files are backed up when any of the following attributes change:
– File size
– Date or time of last modification
– Extended Attributes
– Access Control List
– Sparse, reparse point or encrypted file attributes.
– NTFS or ReFS file security descriptors:Owner Security Identifier (SID), Group
SID, Discretionary Access Control List (ACL), and System ACL.
– Directory attributes
If only the following attributes change, the attributes are updated on the IBM
Spectrum Protect server, but the file is not backed up:
– Read-only or read/write
– Hidden or not hidden
– Compressed or not compressed
The archive attribute is not examined by IBM Spectrum Protect in determining
changed files.
v Back up directories.
A directory is backed up in any of the following circumstances:
– The directory was not previously backed up.
– The directory permissions changed since the last backup.
– The directory Access Control List changed since the last backup.
– The directory Extended Attributes changed since the last backup.
Directories are counted in the number of objects that are backed up. To exclude
directories and their contents from backup, use the exclude.dir option.
v Expire backup versions of files on the server that do not have corresponding
files on the workstation. The result is that files that no longer exist on your
workstation do not have active backup versions on the server. However, inactive
versions are retained according to rules defined by the IBM Spectrum Protect
administrator.
v Rebind backup versions if management class assignments change. Only objects
that have active backup versions are bound again. Objects for which only
inactive backup versions exist are not bound again.
140
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
During a partial incremental backup operation, objects are rebound or expired as
follows:
If the file specification matches all files in a path:
Rebinding and expiration occurs for all eligible backup versions that
match the file specification. This is the case for an incremental command
like dsmc incr c:\mydir\* -subdir=yes.
If the file specification does not match all files in a path:
Rebinding and expiration occurs for all eligible backup versions that
match the file specification. However, eligible backup versions are not
expired or rebound if they were in a directory that no longer exists on
the client file system.
Consider an incremental command like dsmc incr c:\mydir\*.txt
-subdir=yes. Assume that some files in c:\mydir\ do not have the txt
file type. Rebinding and expiration occurs only for files that match the
*.txt specification and whose directories still exist on the client file
system.
You can use the preservelastaccessdate option to specify whether to modify the
last access date after a backup or archive operation. By default, the access date
changes after a backup or archive operation.
Related concepts:
Chapter 9, “Storage management policies,” on page 261
Related reference:
“Exclude options” on page 395
“Preservelastaccessdate” on page 485
Journal-based backup
Journal-based backup is an alternate method of backup that uses a change journal
maintained by the IBM Spectrum Protect journal service process.
Journal-based backup is supported for all Windows clients.
To support journal-based backup, you must configure the journal engine service
using the dsmcutil command or the client GUI setup wizard.
A backup for a particular file system will be journal-based when the IBM Spectrum
Protect journal service has been installed and configured to journal the particular
file system, and a valid journal has been established for the file system.
The primary difference between traditional incremental backup and journal-based
backup is the method used for backup and expiration candidates.
Traditional incremental backup obtains the list of backup and expiration candidates
by building comprehensive lists of local objects, and lists of active server objects
for the file system being backed up. The local lists are obtained by scanning the
entire local file system. The server list is obtained by querying the entire server
inventory for all active objects.
The two lists are compared, and candidates are selected according to the following
criteria:
Chapter 4. Backing up your data
141
v An object is selected as a backup candidate if it exists in the local list. but
doesn't exist in the server list. The object is also a backup candidate if it exists in
both lists, but differs according to incremental criteria (for example, attribute
changes, date and size changes).
v An object is selected as an expiration candidate if it exists in the server list, but
doesn't exist in the local list.
Journal-based backup obtains the candidates list of objects to backup and expire by
querying the journal service for the contents of the change journal of the file
system being backed up.
Change journal entries are cleared (marked as free) after they have been processed
by the backup client and committed on the IBM Spectrum Protect server.
Journal-based backup is activated by configuring the journal service to monitor
specified file systems for change activity.
Journal-based backup is enabled by successfully completing a full incremental
backup.
The journal engine service does not record changes in specific system files, such as
the registry, in the journal. Therefore, a journal-based backup will not back up this
file. See the journal service configuration file, tsmjbbd.ini, in the client installation
directory for excluded system files.
You can use journal-based backup when backing up file systems with small or
moderate amounts of change activity between backup cycles. If you have many file
changes between backup cycles, you will have very large change journals. Many
changes to the journal-based backup file might pose memory and performance
problems that can negate the benefits of journal-based backup. For example,
creating, deleting, renaming, or moving very large directory trees can also negate
the benefit of using journal-based backup instead of normal incremental backup.
Journal-based backup is not intended to be a complete replacement for traditional
incremental backup. You should supplement journal-based backup with a full
progressive incremental backup on a regular basis. For example, perform
journal-based backups on a daily basis, and full incremental backups on a weekly
basis.
Journal-based backup has the following limitations:
v Individual server attributes are not available during a journal-based backup.
Certain policy settings such as copy frequency and copy mode might not be
enforced.
v Other operating-system specific behaviors might prevent objects from being
processed properly. Other software that changes the default behavior of the file
system might prevent file system changes from being detected.
v If the file system is very active when a journal-based backup is in progress, it is
possible that a small number of deleted files will not be expired.
v If you restore files to a file system that has an active journal, some of the
restored files might get backed up again when the next journal-based backup
occurs, even if the files have not changed since they were restored.
Note:
1. Multiple journal-based backup sessions are possible.
142
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
2. When using antivirus software, there are limitations to journal-based backup.
3. A journal-based backup might not fall back to the traditional incremental
backup if the policy domain of your node is changed on the server. This
depends on when the policy set within the domain was last updated and the
date of the last incremental backup. In this case, you must force a full
traditional incremental backup to rebind the files to the new domain. Use the
nojournal option with the incremental command to specify that you want to
perform a traditional full incremental backup, instead of the default
journal-based backup.
Related tasks:
“Configuring the journal engine service” on page 41
Restore processing with journal-based backups (Windows):
The journal service attempts to identify changes that are made to a file as the
result of a restore operation. If a file is unchanged since it was restored, it is not
backed up again during the next journaled backup. The presumption is that you
are restoring a file because it contains the data you need, so there is no point to
backing up the file again when the next journal backup occurs. Changes to
restored files that occur after the files are restored must be recognized as new
changes and the file is processed in the next journal backup.
When an active journal exists for a particular file system, the backup-archive client
notifies the journal daemon when a file is about to be restored. Any changes to the
file that occur within a short window in time after the journal daemon is notified
are assumed to be a result of the file being restored. These changes are not
recorded and the file is not included in the next journal backup.
In most cases, journal processing correctly identifies file changes that are generated
as the result of the file being restored and prevents the file from being backed up
by the next journal backup.
Systemic system delays, whether caused by intensive I/O or file system latency,
might prevent a restore operation from starting in the time frame allotted by the
journal daemon once it is notified that a restore is about to take place. If such a
delay occurs, changes made to the file are assumed to be new changes that
occurred after the file was restored. These changes are recorded, and the file is
included in the next journal backup. Things like systemic processing delays and
file system latency are beyond the control of the backup-archive client and are
simply recognized limitations of journal-based backups.
Incremental-by-date backup
For a file system to be eligible for incremental-by-date backups, you must have
performed at least one full incremental backup of that file system. Running an
incremental backup of only a directory branch or individual file will not make the
file system eligible for incremental-by-date backups.
To perform an incremental-by-date backup using the GUI, select the incremental
(date only) option from the type of backup pull-down menu or use the incrbydate
option with the incremental command.
The client backs up only those files whose modification date and time is later than
the date and time of the last incremental backup of the file system on which the
file resides. Files added by the client after the last incremental backup, but with a
modification date earlier than the last incremental backup, are not backed up.
Chapter 4. Backing up your data
143
Files that were renamed after the last incremental backup, but otherwise remain
unchanged, will not be backed up. Renaming a file does not change the
modification date and time of the file. However, renaming a file does change the
modification date of the directory in which it is located. In this case, the directory
is backed up, but not the files it contains.
If you run an incremental-by-date backup of the whole file system, the server
updates the date and time of the last incremental backup. If you perform an
incremental-by-date backup on only part of a file system, the server does not
update the date of the last full incremental backup. In this case, the next
incremental-by-date backup backs up these files again.
Note: Unlike incremental backups, incremental-by-date backups do not expire
deleted files or rebind backup versions to a new management class if you change
the management class.
Comparing incremental-by-date, journal-based, and NetApp
snapshot difference to full incremental and partial incremental
backups
Incremental-by-date, journal-based, and NetApp snapshot difference are
alternatives to full incremental and partial incremental back methods.
Incremental-by-date backup
An incremental-by-date backup takes less time to process than a full
incremental backup and requires less memory.
An incremental-by-date backup might not place exactly the same backup
files into server storage because the incremental-by-date backup:
v Does not expire backup versions of files that you delete from the
workstation.
v Does not rebind backup versions to a new management class if you
change the management class.
v Does not back up files with attributes that change, unless the
modification dates and times also change.
v Ignores the copy group frequency attribute of management classes
(Journal-based backups also ignore this attribute).
Journal-based backup
The memory requirements for an initial journaling environment are the
same as the memory requirements for a full file space incremental, because
journal-based backups must complete the full file space incremental in
order to set the journal database as valid, and to establish the baseline for
journaling.
The memory requirements for subsequent journal-based backups are much
less. Journal backup sessions run in parallel and are governed by the
resourceutilization client option in the same manner as normal backup
sessions. The size of the journal database file reverts to a minimal size (less
than 1 KB) when the last entry has been deleted from the journal. Since
entries are deleted from the journal as they are processed by the client, the
disk size occupied by the journal should be minimal after a complete
journal backup. A full incremental backup with journaling active takes less
time to process than an incremental-by-date backup.
NetApp snapshot difference
144
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
For NAS and N-Series file servers that are running ONTAP 7.3.0, or later,
you can use the snapdiff option to invoke the snapshot difference backup
from NetApp when running a full-volume incremental backup. Using this
option reduces memory usage and is faster.
Consider the following restrictions when running a full-volume
incremental backup using the snapdiff option, to ensure that data is
backed up when it should be.
v A file is excluded due to an exclude rule in the include-exclude file. The
client runs a backup of the current snapshot with that exclude rule in
effect. This happens when you have not made changes to the file, but
you have removed the rule that excluded the file. NetApp will not
detect this include-exclude change because it only detects file changes
between two snapshots.
v If you added an include statement to the option file, that include option
does not take effect unless NetApp detects that the file has changed. The
client does not inspect every file on the volume during backup.
v If you used the dsmc delete backup command to explicitly delete a file
from the IBM Spectrum Protect inventory, NetApp cannot detect that a
file was manually deleted from IBM Spectrum Protect storage. Therefore,
the file remains unprotected in IBM Spectrum Protect storage until it is
changed on the volume and the change is detected by NetApp, which
signals the client to back it up again.
v Policy changes such as changing the policy from mode=modified to
mode=absolute are not detected.
v The entire file space is deleted from the IBM Spectrum Protect inventory.
This action causes the snapdiff option to create a new snapshot to use
as the source, and a full incremental backup to be run.
The NetApp software determines what is a changed object, not IBM
Spectrum Protect.
To avoid backing up all snapshots under the snapshot directory, do one of
the following actions:
v Run NDMP backups
v Run backups using the snapshotroot option
v Run incremental backups using the snapdiff option
Tip: If you run an incremental backup using the snapdiff option and
you schedule periodic incremental backups, use the createnewbase=yes
option with the snapdiff option to create a base snapshot and use it as a
source to run an incremental backup.
v Exclude the snapshot directory from backups.
On Windows systems, the snapshot directory is in ~snapshot.
Snapshot differential backup with an HTTPS connection
You can use a secure HTTPS connection for the backup-archive client to
communicate with a NetApp filer during a snapshot differential backup.
The HTTPS protocol is enabled on NetApp filers by default and cannot be
disabled.
When you run a snapshot differential backup, the backup-archive client establishes
an administrative session with a NetApp filer. The filer credentials, such as the
filer host name or IP address, the user name that is used to connect to the filer, and
Chapter 4. Backing up your data
145
the filer password, are stored locally on the backup-archive client. This information
must be transmitted to the filer to establish the authenticated administrative
session. It is important to use a secure connection because authenticating the
administrative filer session requires the client to transmit the filer password in
clear text.
To establish a secure connection by using the HTTPS communication protocol, you
must use the snapdiffhttps option whenever you run a snapshot differential
backup. Without the snapdiffhttps option, the backup-archive client can establish
filer sessions only with the HTTP protocol, which would require HTTP
administrative access to be enabled on the filer. With the snapdiffhttps option,
you can establish a secure administrative session with the NetApp filer regardless
of whether HTTP administrative access is enabled on the NetApp filer.
Restrictions:
The following restrictions apply to snapshot differential backups with HTTPS:
v The HTTPS connection is used only to securely transmit data over the
administrative session between the backup-archive client and the NetApp filer.
The administrative session data includes information such as filer credentials,
snapshot information, and file names and attributes that are generated by the
snapshot differencing process. The HTTPS connection is not used to transmit
normal file data that is accessed on the filer by the client through file sharing.
The HTTPS connection also does not apply to normal file data transmitted by
the client to the IBM Spectrum Protect server through the normal IBM Spectrum
Protect client/server protocol.
v The snapdiffhttps option does not apply to vFilers because the HTTPS protocol
is not supported on the NetApp vFiler.
v The snapdiffhttps option is available only by using the command-line interface.
It is not available for use with the backup-archive client GUI.
Related concepts:
“Comparing incremental-by-date, journal-based, and NetApp snapshot difference
to full incremental and partial incremental backups” on page 144
Related tasks:
“Configuring NetApp and IBM Spectrum Protect for snapshot difference
incremental backups” on page 79
“Running a snapshot differential backup with an HTTPS connection”
Related reference:
“Snapdiffhttps” on page 534
“Snapdiff” on page 528
Running a snapshot differential backup with an HTTPS
connection
When you run a snapshot differential backup, you can use the snapdiffhttps
option to create a secure HTTPS connection between the backup-archive client and
the NetApp filer.
Before you begin
Before you begin a snapshot differential backup over an HTTPS connection, ensure
that you configured the client as described in “Configuring NetApp and IBM
Spectrum Protect for snapshot difference incremental backups” on page 79.
146
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
This method is available only at the command-line interface.
Procedure
To start a snapshot differential backup operation over an HTTPS connection,
specify the incremental command with the snapdiff and snapdiffhttps options at
the command-line interface.
For example, on a Windows system with a network share \\netapp1.example.com\
vol1, where netapp1.example.com is a filer, issue the following command:
dsmc incr \\netapp1.example.com\vol1 -snapdiff -snapdiffhttps
Related concepts:
“Snapshot differential backup with an HTTPS connection” on page 145
Related reference:
“Snapdiffhttps” on page 534
Selective backup
Use a selective backup when you want to back up specific files or directories
regardless of whether a current copy of those files exists on the server.
Incremental backups are generally part of an automated system to back up entire
file systems. In contrast, selective backups allow you to manually select a set of
files to back up regardless of whether they have changed since your last
incremental backup.
Unlike incremental backups, a selective backup provides the following:
v Does not cause the server to update the date and time of the last incremental.
v Backs up directory and file entries even if their size, modification timestamp, or
permissions have not changed.
v Does not expire deleted files.
v Does not rebind backup versions to a new management class if you change the
management class.
Related tasks:
“Backing up data using the GUI” on page 129
Related reference:
“Selective” on page 775
Backing up files from one or more file spaces for a group backup
(Windows)
Use the backup group command to create and back up a group from a list of files
from one or more file space origins to a virtual file space on the IBM Spectrum
Protect server.
About this task
A group backup creates a consistent point-in-time backup of a group of files that is
managed as a single logical entity:
v All objects in the group are assigned to the same management class. Use the
include option to bind a group to a management class.
v Existing exclude statements for any files in the group are ignored.
v All objects in the group are exported together.
Chapter 4. Backing up your data
147
v All objects in the group are expired together as specified in the management
class. No objects in a group are expired until all other objects in the group are
expired, even when another group they belong to gets expired.
A group backup can be added to a backup set.
You can perform a full or differential backup by using the mode option.
Procedure
Enter the backup group command to start a group backup.
For example, to perform a full backup of all the files in the c:\dir1\filelist1 file
to the virtual file space \virtfs, containing the group leader c:\group1 file, enter
the following command:
dsmc backup group -filelist=c:\dir1\filelist1 -groupname=group1 -virtualfsname=
\virtfs -mode=full
Related concepts:
“Restore data from a backup set” on page 196
Related reference:
“Backup Group” on page 652
“Include options” on page 426
“Mode” on page 460
Backing up data with client-node proxy support (Windows)
Backups of multiple nodes that share storage can be consolidated to a common
target node name on the IBM Spectrum Protect server.
Before you begin
The following considerations apply when you use a proxy node to back up or
restore data on other nodes:
v A proxy operation uses the settings for the target node (such as maxnummp and
deduplication) and schedules that are defined on the IBM Spectrum Protect
server. The IBM Spectrum Protect server node settings and schedules for the
agent node are ignored.
v You cannot use asnodename with the backup nas command.
v You cannot use asnodename with the fromnode option.
v If you use asnodename to backup and restore volumes that are in a cluster
configuration, do not use clusternode yes.
v You cannot use asnodename to back up or restore system state.
v If an agent node restores data from a backup set, the system state object in the
backup set is not restored.
v You can use asnodename with the backup image command, but you must specify
the volume by UNC name. You cannot use the drive letter.
v If you use the same asnodename value to back up files from different machines,
you need to keep track which files or volumes are backed up from each system
so that you can restore them to the correct location.
v All agent nodes in a multiple node environment should be of the same platform
type.
v Do not use target nodes as traditional nodes, especially if you encrypt your files
before backing them up to the server.
148
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
About this task
An agent node is a client node which has been granted authority to perform client
operations on behalf of a target node.
A target node is a client node which grants authority to one (or more) agent nodes
to perform client operations on its behalf.
Using an agent node to backup target nodes is useful when the workstation
responsible for performing the backup can change over time, such as with a cluster
configuration.
The asnodename option allows data to be restored from a different system than the
one which performed the backup.
Use the asnodename option with the appropriate command to back up, archive,
restore, and retrieve data under the target node name on the IBM Spectrum Protect
server. This support is only available with IBM Spectrum Protect Version 5.3 and
higher server and client.
Procedure
To enable this option, follow these steps:
1. Install the backup-archive client on all nodes in a shared data environment.
2. Register each node with the IBM Spectrum Protect server, if it does not exist.
Register the common target node name to be shared by each of the agent nodes
used in your shared data environment.
3. Register each of the nodes in the shared data environment with the IBM
Spectrum Protect server. This is the agent node name that is used for
authentication purposes. Data will not be stored using the node name when the
asnodename option is used.
4. Grant proxy authority to all nodes in the shared environment to access the
target node name on the IBM Spectrum Protect server, using the GRANT
PROXYNODE command (IBM Spectrum Protect administrator).
5. Use the QUERY PROXYNODE administrative client command to display the
client nodes of the authorized user, granted by the GRANT PROXYNODE
command.
Related reference:
“Asnodename” on page 320
Enabling multiple node operations from the GUI
To enable multinode operations in the GUI, use the Preferences editor to specify
the name of the target node to which you have been granted proxy authority.
Procedure
1. Verify that the client node has proxy authority to a target node (or authorized
to act as the target node) by using the QUERY PROXYNODE administrative
client command.
2. Select Edit > Client Preferences to open the preferences window.
3. Select the General tab and fill in the As Node Name field with the name of the
target node.
4. Click Apply and then OK to close the preferences window.
Chapter 4. Backing up your data
149
What to do next
Perform one of the following steps to verify that your client node is now accessing
the server as the target node:
v Open the tree window and check that the target node name specified by the As
Node Name field appears.
v Verify the target node name in the Accessing As Node field in the Connection
Information window.
To return to single node operation, delete the As Node Name from the Accessing
As Node field in the General > Preferences tab.
Setting up encryption
This topic lists the steps that you must follow to set up encryption with the
encryptkey option.
Procedure
1. Specify encryptkey=save in the options file.
2. Back up at least one file with asnode=ProxyNodeName to create a local encryption
key on each agent node in the multiple node environment.
Results
Follow these steps to set up encryption with the encryptkey=prompt option:
1. Specify encryptkey=prompt in the options file.
2. Ensure that users of the agent nodes in the multiple node environment are
using the same encryption key.
Important:
v If you change the encryption key, you must repeat the previous steps.
v Use the same encryption key for all files backed up in the shared node
environment.
Scheduling backups with client-node proxy support
Multiple nodes can be used to perform backup operations using the scheduler.
About this task
When you grant proxy authority to the agent nodes, they perform scheduled
backup operation on behalf of the target node. Each agent node must use the
asnodename option within their schedule to perform multiple node backup for the
agent node.
Perform the following steps to enable scheduling of multiple nodes:
1. Ensure that all agent nodes must have proxy authority over the common target
node
2. Ensure that all agent nodes must have a schedule defined on the server:
def sched domain_name sched_name options=’-asnode=target’
3. Ensure that each agent node must have its schedule associated with a node:
def association domain_name schedule_name <agentnodename>
150
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
The following examples show the administrative client-server commands using the
scheduler on multiple nodes.
v The administrator registers all the nodes to be used, by issuing the following
commands:
– register node NODE-A
– register node NODE-B
– register node NODE-C
v The administrator grants proxy authority to each agent node, by issuing the
following commands:
– grant proxynode target=NODE-Z agent=NODE-A
– grant proxynode target=NODE-Z agent=NODE-B
– grant proxynode target=NODE-Z agent=NODE-C
v The administrator defines the schedules, by issuing the following commands:
– define schedule standard proxy1 description="NODE-A proxy schedule"
action=incremental options="-asnode=NODE-Z" objects=C:
startdate=05/21/2005 starttime=01:00
– define schedule standard proxy2 description="NODE-B proxy schedule"
action=incremental options="-asnode=NODE-Z" objects=D:
startdate=05/21/2005 starttime=01:00
– define schedule standard proxy3 description="NODE-C proxy schedule"
action=incremental options="-asnode=NODE-Z" objects=E:
startdate=05/21/2005 starttime=01:00
Note: Place the asnodename option in the schedule definition only. Do not place it
in the client options file, on the command line, or in any other location.
Start the schedules by either configuring a scheduler service, or by using the
following client command: dsmc sched
You can also use the client acceptor, with managedservices set to schedule in the
systems options file.
Important:
v Each schedule can be started from a different workstation or LPAR.
v After running the schedules, any proxied client can query and restore all the
backed up data.
v A proxy operation uses the settings for the target node (such as maxnummp and
deduplication) and schedules that are defined on the IBM Spectrum Protect
server. The IBM Spectrum Protect server node settings and schedules for the
agent node are ignored.
Related reference:
“Asnodename” on page 320
“Session settings and schedules for a proxy operation” on page 322
DEFINE SCHEDULE command
Associate a local snapshot with a server file space (Windows)
Use the snapshotroot option with the incremental and selective commands in
conjunction with a vendor-supplied application that provides a snapshot of a
logical volume, to associate the data on the local snapshot with the real file space
data that is stored on the IBM Spectrum Protect server.
Chapter 4. Backing up your data
151
The snapshotroot option does not provide any facilities to take a volume snapshot,
only to manage data created by a volume snapshot.
Related reference:
“Snapshotroot” on page 537
Backing up Windows system state
The backup-archive client uses VSS to back up all system state components as a
single object, to provide a consistent point-in-time snapshot of the system state.
System state consists of all bootable system state and system services components.
About this task
The client supports the Microsoft volume shadow copy service (VSS) on the
supported Windows clients.
System state is represented by several VSS writers of type "bootable system state"
and "system service". Of these, the System Writer is the largest part of the system
state in terms of number of files and size of data. By default, the System Writer
backup is incremental. You can use the systemstatebackupmethod option to
perform full backups of the System Writer. For more information, about this
option, see “Systemstatebackupmethod” on page 551. The client always backs up all
other writers in full.
The list of bootable system state and system services components are dynamic and
can change depending on service pack and operating system features installed. The
client allows for the dynamic discovery and back up of these components.
You must be a member of the Administrators or Backup Operators group to back
up system state information.
To back up a system state object using the command line:
1. On the command line, use the backup systemstate command to back up all
system state or system services components as a single object.
2. Use the query systemstate command to display information about a backup of
the system state on the IBM Spectrum Protect server.
To back up a system state object using the GUI:
1. Click Backup from the GUI main window. The Backup window appears.
2. Expand the directory tree by clicking the plus sign (+). To display files in a
folder, click the folder icon.
3. Locate the system state node in the directory tree. You can expand the system
state node to display the components.
4. Click the selection box next to the system state node to back up the entire
system state object. You can back up the system state node only as a single
entity because of dependencies among the system state components. By default,
all components are selected; you cannot back up individual system state
components.
5. Click Backup. The Backup Task List window displays the backup processing
status. When processing completes, the Backup Report window displays
processing details.
152
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
System and boot files are backed up as a group only if one of the members of the
group (one of the files) changes. If the files have not changed since the last backup,
the system and boot files are not redundantly backed up.
By default, system state backups are bound to the default management class. To
bind them to a different management class, use the include.systemstate option;
specify all as the pattern, and specify the name of the new management class.
You can use the domain option to exclude the entire system state from domain
incremental backup processing.
The system dllcache directory is now included in the boot partition backup of
Windows systems. When the dllcache files are not available when you restore a
Windows computer, system recovery might require availability of the operating
system installation media. By backing up the dllcache directory, you can avoid the
need for installation media during system restores.
If you do not want the dllcache directory included in the backup of your boot
partition, and you understand the limitations of not backing up the dllcache
directory, then you can use an exclude.dir statement to suppress backup of those
files. For example:
exclude.dir c:\windows\system32\dllcache
On Windows clients, backup systemstate also backs up ASR data.
Related tasks:
“Restoring Windows system state” on page 191
Related reference:
“Backup Systemstate” on page 660
“Domain” on page 367
“Exclude options” on page 395
“Include options” on page 426
“Query Systemstate” on page 728
“Restore Systemstate” on page 760
Backing up Automated System Recovery files
You can back up Automated System Recovery (ASR) files in preparation for
recovering the Windows disk configuration information and system state in case a
catastrophic system or hardware failure occurs.
About this task
The backup-archive client backs up ASR data when the backup-archive client backs
up the Windows system state.
Procedure
To back up ASR files on Windows operating systems, use the backup systemstate
command.
Chapter 4. Backing up your data
153
Results
The client generates the ASR files in the \adsm.sys\ASR staging directory on the
system drive of your local workstation and stores these files in the ASR file space
on the IBM Spectrum Protect server.
Related concepts:
“Preparation for Automated System Recovery”
Related tasks:
“Restoring Automated System Recovery files” on page 192
Related reference:
“Backup Systemstate” on page 660
Preparation for Automated System Recovery
Specific backups and media are required for Windows Automated System
Recovery (ASR).
Creating a client options file for Automated System Recovery
Before you can recover a Windows computer by using Automated System
Recovery (ASR), you must create an options file. The options file is unique for each
computer.
About this task
This task assumes that you created a generic bootable WinPE CD or DVD. A
generic bootable WinPE CD does not contain the client options file (dsm.opt)
because the options file is unique for each computer. This task helps you create a
computer-specific options file.
The Windows Preinstallation Environment (WinPE) requires particular options
values.
Procedure
1. Find a copy of the client options file. You can find the file in several places:
v There is an options file in the installation directory of an installed IBM
Spectrum Protect client. The default installation location is C:\Program
Files\Tivoli\TSM\baclient\dsm.opt. If you have the options file for the
computer that you want to restore, this options file requires the fewest
modifications.
v There is a sample options file in the client installation package. The path in
the package is TSM_BA_Client\program files\Tivoli\TSM\config\dsm.smp.
Rename the file to dsm.opt.
2. Edit dsm.opt.
a. Enter a writable location for the error log. The backup-archive client creates
several log files. Use the option errorlogname to specify the log file location.
For example, in the dsm.opt file, specify errorlogname x:\dsmerror.log.
Note: This example uses x: because in WinPE mode, the default system
drive is x:.
b. Enter the client node name with the nodename option.
154
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
c. Optional: If you plan to restore the system state from files that are stored on
the IBM Spectrum Protect server, enter the server connection information.
Enter appropriate values for the commmethod and tcpserveraddress options.
d. Optional: If you know the password for the node, enter the password with
the password option.
3. Copy the dsm.opt file to media that the target computer can read during
Automated System Recovery.
4. Optional: Copy IBM Spectrum Protect client registry information to media that
the target computer can read during Automated System Recovery. Use the
regedit.exe utility to export IBM Spectrum Protect client registry entries from
the HKLM\SOFTWARE\IBM key. For example, from a command prompt window,
run this command:
regedit /e tsmregistry.out "HKEY_LOCAL_MACHINE\SOFTWARE\IBM"
Copy the tsmregistry.out file to media that the target computer can read
during ASR.
During ASR, you can import the registry entries from the tsmregistry.out file.
The backup-archive client can use the registry entries in the WinPE
environment to access backup copies on the IBM Spectrum Protect server.
Note: Saving registry entries is optional because there are other ways to get
access to the password-protected IBM Spectrum Protect server. You can access
the server with the following methods:
v If you know the node password, you can type the password when prompted
during recovery.
v Request the IBM Spectrum Protect administrator to change the node
password and provide you with the new password at the time of recovery.
v Provide the password information in the dsm.opt file.
If the files you want to restore are included in a backup set on tape or on a CD
or DVD, then you do not need to access the IBM Spectrum Protect server.
Results
You created an options file that contains client configuration information that is
unique for each computer. This information complements the generic bootable
WinPE CD.
Related tasks:
“Creating a bootable WinPE CD” on page 193
Backing up the boot drive and system drive for Automated
System Recovery
Before you can recover your Windows computer by using Automated System
Recovery (ASR), you must have a complete backup of the boot drive and system
drive.
Procedure
1. Perform a full incremental backup of your system and boot drives. Assuming
that your system and boot files are on the c: drive, enter the following
command:
dsmc incremental c:
2. Back up the system state. To back up the system state, enter the following
command:
Chapter 4. Backing up your data
155
dsmc backup systemstate
To verify that you backed up the system state, enter the following command:
dsmc query systemstate
You can specify -showmembers=yes to display file level detail.
Related concepts:
“Full and partial incremental backup” on page 139
Related tasks:
“Backing up Windows system state” on page 152
Image backup
From your local workstation, you can back up a logical volume as a single object
(image backup) on your system.
The traditional static image backup prevents write access to the volume by other
system applications during the operation.
These volumes can be formatted NTFS or ReFS, or unformatted RAW volumes. If a
volume is NTFS-formatted, only those blocks that are used by the file system or
smaller than the imagegapsize parameter are backed up.
Normally you cannot restore an image backup of the system drive over itself since
an exclusive lock of the system drive is not possible. However, in a Windows
pre-installation environment (WinPE), an image restore of the system drive is
possible. For information about restoring data in a WinPE environment, see
technote 7005028.
You cannot restore an image backup to the volume on which the client is running.
Consider installing the backup-archive client on the system drive.
Image backup does not guarantee consistency of system objects, such as the Active
Directory. System objects can be spread out across multiple volumes, and should
be backed up by using the backup systemstate command.
An image backup provides the following benefits:
v Backs up file systems that contain a large number of files faster than a full file
system incremental backup.
v Improves the speed with which the client restores file systems that contain many
small files.
v Conserves resources on the server during backups since only one entry is
required for the image.
v Provides a point-in-time picture of your logical volume, which might be useful if
your enterprise must recall that information.
v Restores a corrupted file system or raw logical volume. Data is restored to the
same state it was when the last logical volume backup was performed.
The traditional offline image backup prevents write access to the volume by other
system applications during the operation. When you backup an image by using
snapshotproviderimage=none, always run the fsck utility after you restore the data.
To restore an image backup of a volume, the backup-archive client must be able to
obtain an exclusive lock on the volume that is being restored.
156
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
If online image support is configured, the client performs an online image backup,
during which the volume is available to other system applications. The snapshot
provider, as specified by the snapshotproviderimage option, maintains a consistent
image of a volume during online image backup.
You can use the snapshotproviderimage option with the backup image command
or the include.image option to specify whether to perform an offline or online
image backup.
Related tasks:
“Configuring online-image backup support” on page 78
Related reference:
“Snapshotproviderimage” on page 536
Performing prerequisite tasks before creating an image
backup
This topic lists some items to consider before you perform an image backup.
About this task
The following items are the image backup considerations.
v To perform an offline or online image backup you must have administrative authority on
the system.
v You do not need more than one drive to perform an image backup.
v Ensure that no other application is using the volume when you run an offline
image backup. To ensure a consistent image during backup processing, the client
locks the volume, so that no other applications can write to it. If the volume is
in use when the client attempts to lock the volume, the backup fails. If the client
cannot lock a volume because it is in use, you can perform an online image
backup.
v Use the include.image option to assign a management class to the volume
image. If you do not assign a management class, the default management class
is used for the image.
Note: If the snapshotproviderimage option is set to none, then the copy
serialization parameters set by the management class is used.
v You can exclude a volume from image backup using the exclude.image option.
v You must use the mount point or drive letter for the volume on which you want
to perform an image backup. The client will not back up a volume without the
use of a drive letter or mount point.
v Do not include the system drive in an image backup because the client cannot
have an exclusive lock of the system drive during the restore and the system
drive image cannot be restored to the same location. Image backup does not
guarantee consistency of system objects, such as the Active Directory. System
objects can be spread out across multiple volumes, and should be backed up
using the corresponding backup commands. Because you cannot restore an
image backup to the volume from which the client is currently running (or any
volume for which an exclusive lock cannot be obtained) you should install your
client program on the system drive.
Note: When using WinPE, an image restore of the system drive is possible. For
more information, see IBM Spectrum Protect Recovery Techniques Using
Windows Preinstallation Environment (Windows PE).
Chapter 4. Backing up your data
157
v If bad disk sectors are detected on the source drive during a LAN-free or
LAN-based image backup, data corruption can occur. In this case, bad sectors
are skipped when sending image data to the IBM Spectrum Protect server. If bad
disk sectors are detected during the image backup, a warning message is issued
after the image backup completes.
Related concepts:
Chapter 9, “Storage management policies,” on page 261
Related reference:
“Exclude options” on page 395
“Include options” on page 426
“Snapshotproviderimage” on page 536
Utilizing image backups to perform file system incremental
backups
This topic lists the methods and steps to use image backups to perform efficient
incremental backups of your file system.
These backup methods allow you to perform a point-in-time restore of your file
systems and improve backup and restore performance. You can perform the
backup only on formatted volumes; not on raw logical volumes.
You can use one of the following methods to perform image backups of volumes
with mounted file systems.
Method 1: Using image backups with file system incremental
backups
This topic lists the steps to perform image backups with file system incremental
backup.
About this task
Procedure
1. Perform a full incremental backup of the file system. This establishes a baseline
for future incremental backups.
2. Perform an image backup of the same file system to make image restores
possible.
3. Perform incremental backups of the file system periodically to ensure that the
server records additions and deletions accurately.
4. Perform an image backup periodically to ensure faster restore.
5. Restore your data by performing an incremental restore. Ensure that you select
the Image plus incremental directories and files and Delete inactive files
from local options in the Restore Options window before beginning the restore.
During the restore, the client does the following:
Results
v Restores the most recent image on the server.
v Deletes all of the files restored in the previous step which are inactive on the
server. These are files which existed at the time of the image backup, but were
subsequently deleted and recorded by a later incremental backup.
v Restores new and changed files from the incremental backups.
158
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Note: If an incremental backup is performed several times after backing up an
image, make sure that the backup copy group of the IBM Spectrum Protect server
has enough versions for existing and deleted files on the server so that the
subsequent restore image with incremental and deletefiles options can delete
files correctly.
Related tasks:
“Backing up data using the GUI” on page 129
“Performing an image backup using the GUI” on page 160
“Restoring an image using the GUI” on page 195
Method 2: Using image backups with incremental-by-date image
backups
This topic lists the steps to perform image backups with incremental-by-date image
backup.
Procedure
1. Perform an image backup of the file system.
2. Perform an incremental-by-date image backup of the file system. This sends
only those files that were added or changed since the last image backup to the
server.
3. Periodically, perform full image backups.
4. Restore your volume by performing an incremental restore. Ensure that you
select the Image plus incremental directories and files option in the Restore
Options window before beginning the restore. This first restores the most recent
image and then restores all of the incremental backups performed since that
date.
Results
Note: You should perform full image backups periodically in the following cases:
v When a file system changes substantially (more than 40%), as indicated in step 4
of method 1 and step 3 of method 2. On restore, this would provide a file
system image close to what existed at the time of the last incremental-by-date
image backup and it also improves restore time.
v As appropriate for your environment.
This improves restore time because fewer changes are applied from incremental
backups.
The following restrictions apply when using method 2:
v The file system can have no previous full incremental backups.
v Incremental-by-date image backup does not inactivate files on the server;
therefore, when you restore an image with the incremental option, files deleted
after the original image backup is present after the restore.
v If this is the first image backup for the file system, a full image backup is
performed.
v If file systems are running at or near capacity, an out-of-space condition could
result during the restore.
Related tasks:
“Performing an image backup using the GUI” on page 160
“Restoring an image using the GUI” on page 195
Chapter 4. Backing up your data
159
Comparing methods 1 and 2
This topic shows a comparison of methods 1 and 2: (1) Using image backup with
file system incremental or (2) Using image backup with incremental-by-date image
backup.
To help you decide which method is appropriate for your environment, the
following table is a comparison of methods 1 and 2.
Table 19. Comparing incremental image backup methods
Method 1: Using image backup with file
system incremental
Method 2: Using image backup with
incremental-by-date image backup
Files are expired on the server when they are
deleted from the file system. On restore, you
have the option to delete files which are
expired on server from image.
Files are not expired on server. After the
image incremental restore completes, all of
the files that are deleted on the file system
after the image backup are present after the
restore. If file systems are running at or near
capacity, an out-of-space condition could
result.
Incremental backup time is the same as
regular incremental backups.
Incremental image backup is faster because
the client does not query the server for each
file that is copied.
Restore is much faster compared to a full
incremental file system restore.
Restore is much faster compared to a full
incremental file system restore.
Directories deleted from the file system after
the last image backup are not expired.
Directories and files deleted from the file
system after the last full image backup are
not expired.
Performing an image backup using the GUI
If the image backup feature is configured, you can create an image backup where
the real volume is available to other system applications.
About this task
A consistent image of the volume is maintained during the image backup.
When you perform an image backup using the client GUI image backup option, the
backup operation is run according to the snapshotproviderimage setting in your
client options file (dsm.opt). If the online image support is configured, the client
performs an online image backup, during which the volume is available to other
system applications.
To create an image backup of your file system or raw logical volume, perform the
following steps:
Procedure
1. Click on the Backup button in the IBM Spectrum Protect main window. The
Backup window appears.
2. Expand the directory tree and select the objects you want to back up. To back
up a raw logical volume, locate and expand the RAW directory tree object.
3. Click Backup. The Backup Task List window displays the backup processing
status. The Backup Report window displays a detailed status report.
160
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Results
v To perform an offline image backup, select Image Backup from the drop-down
list.
v To perform an online image backup, select Snapshot Image Backup from the
drop-down list.
v To perform an incremental-by-date image backup, select Incremental image
(date only) from the drop-down list.
The following are some items to consider when you perform an online image
backup:
v To modify specific backup options, click the Options button. The options you
select are effective only during the current session.
v Because image backup allows you to back up only used blocks in a file system,
the stored image size on the IBM Spectrum Protect server could be smaller than
the volume size. For online image backups, the stored image can be larger than
the file system based on the size of the cache files. To determine the actual
stored image size, select View > File Details. The actual stored image size is
noted in the Stored Size field.
v To modify specific backup options, click the Options button. The options you
select are effective only during the current session.
v Because image backup allows you to back up only used blocks in a file system,
the stored image size on the IBM Spectrum Protect server could be smaller than
the volume size. For online image backups, the stored image can be larger than
the file system based on the size of the cache files. To determine the actual
stored image size, select View > File Details. The actual stored image size is
noted in the Stored Size field.
Related reference:
“Snapshotproviderimage” on page 536
Performing an image backup using the command line
Use the backup image and restore image commands to perform image backup
and restore operations on a single volume.
You can use the snapshotproviderimage option with the backup image command
or the include.image option in your dsm.opt file or on the command line to
specify whether to perform an offline or online image backup.
Use the mode option with the backup image command to perform an
incremental-by-date image backup that backs up only new and changed files after
the last full image backup. However, this only backs up files with a changed date,
not files with changed permissions.
Related reference:
“Backup Image” on page 654
“Mode” on page 460
“Restore Image” on page 754
“Snapshotproviderimage” on page 536
Chapter 4. Backing up your data
161
Back up NAS file systems using Network Data Management Protocol
Windows, AIX, and Solaris backup-archive clients can use Network Data
Management Protocol (NDMP) to efficiently back up and restore network attached
storage (NAS) file system images. The file system images can be backed up to, or
be restored from, automated tape drives or libraries that are locally attached to
Network Appliance or EMC Celerra NAS file servers, or to or from tape drives or
libraries that are locally attached to the IBM Spectrum Protect server.
NDMP support is available only on IBM Spectrum Protect Extended Edition.
For Linux x86_64 clients, incremental backup can also be used to back up NAS file
system snapshots. See the incremental command and snapshotroot, snapdiff,
createnewbase, and diffsnapshot options for more information.
After configuring NDMP support, the server connects to the NAS device and uses
NDMP to initiate, control, and monitor each backup and restore operation. The
NAS device performs outboard data transfer to and from the NAS file system to a
locally attached library.
Filer to server data transfer is available for NAS devices that support NDMP
Version 4.
The benefits of performing backups using NDMP include the following:
v LAN-free data transfer.
v High performance and scalable backups and restores.
v Backup to local tape devices without network traffic.
The following support is provided:
v Full file system image backup of all files within a NAS file system.
v Differential file system image backup of all files that have changed since the last
full image backup.
v Parallel backup and restore operations when processing multiple NAS file
systems.
v Choice of interfaces to initiate, monitor, or cancel backup and restore operations:
– Web client (only for connections to IBM Spectrum Protect Version 8.1.1,
V8.1.0, or V7.1.7 or earlier servers)
– Backup-archive client command interface (only for connections to IBM
Spectrum Protect Version 8.1.1, V8.1.0, or V7.1.7 or earlier servers)
|
|
|
|
– Administrative client command line interface (backup and restore operations
can be scheduled using the administrative command scheduler)
– Administrative web client
The following functions are not supported:
v Archive and retrieve
v Client scheduling. Use server commands to schedule a NAS backup.
v Detection of damaged files.
v Data-transfer operations for NAS data stored by IBM Spectrum Protect:
– Migration
– Reclamation
– Export
– Backup set generation
162
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Related concepts:
“NDMP support requirements (Extended Edition only)” on page 4
Related reference:
“Diffsnapshot” on page 360
“Incremental” on page 691
“Snapdiff” on page 528
“Snapshotroot” on page 537
Backing up NAS file systems with the web client GUI using
NDMP protocol
For both the web client GUI and the client command line interface, you must
specify passwordaccess=generate (which is a current web client restriction for the
client node) and set authentication=on must be specified at the server.
You are always prompted for a user ID and password. To display NAS nodes and
perform NAS functions, you must enter an authorized administrative user ID and
password. The authorized administrative user ID should have at least client owner
authority over both the NAS node and the client workstation node they are using
either from command line or from the web.
You can use the toc option with the include.fs.nas option in the client options
file to specify whether the client saves Table of Contents (TOC) information for
each file system backup. If you save TOC information, you can use the Windows
web client to examine the entire file system tree and select files and directories to
restore. Creation of a TOC requires that you define the TOCDESTINATION
attribute in the backup copy group for the management class to which this backup
image is bound. Note that TOC creation requires additional processing, network
resources, storage pool space, and possibly a mount point during the backup
operation.
|
|
The web client interface is available only for connections to the IBM Spectrum
Protect Version 8.1.1, V8.1.0, or V7.1.7 or earlier servers.
To back up NAS file systems using the web client GUI:
1. Click Backup from the main window. The Backup window is displayed.
2. Expand the directory tree if necessary.
Note:
a. The root node called Nodes is not selectable. This node only appears if a
NAS plug-in is present on the client workstation.
b. NAS nodes display on the same level as the client workstation node. Only
nodes for which the administrator has authority appear.
c. You can expand NAS nodes to reveal file spaces, but no further expansion is
available (no file names).
3. Click the selection boxes next to the nodes or file systems you want to back up.
4. Click the type of backup you want to perform in the backup type pull-down
menu. The NAS backup type list is active only when you first select NAS
backup objects. Full backup backs up the entire file system. Differential backs
up the changes since the most recent full backup.
5. Click Backup. The NAS Backup Task List window displays the backup
processing status and progress bar. The number next to the progress bar
indicates the number of bytes backed up so far. After the backup completes, the
Chapter 4. Backing up your data
163
NAS Backup Report window displays processing details, including the actual
size of the backup, including the total bytes backed up.
Note: If it is necessary to close the web browser session, current NAS
operations continue after disconnect. You can use the Dismiss button on the
NAS Backup Task List window to quit monitoring processing without ending
the current operation.
6. (Optional) To monitor processing of an operation from the GUI main window,
open the Actions menu and select IBM Spectrum Protect Activities. During a
backup, the status bar indicates processing status. A percentage estimate is not
displayed for differential backups.
Here are some items to consider when you back up NAS file systems using the
web client GUI:
v Workstation and remote (NAS) backups are mutually exclusive in a Backup
window. After selecting an item for backup, the next item you select must be of
the same type (either NAS or non NAS).
v Details will not appear in the right-frame of the Backup window for NAS nodes
or file systems. To view information about objects in a NAS node, highlight the
object and select View > File Details from the menu.
v To delete NAS file spaces, select Utilities > Delete Filespaces.
v Backup options do not apply to NAS file spaces and are ignored during a NAS
backup operation.
Related concepts:
“Web client configuration overview” on page 27
“Restore NAS file systems” on page 228
Related reference:
“Toc” on page 562
Back up NAS file systems using the command line
You can use the command line to back up NAS file system images.
You can use the command-line client only if you are connecting to the IBM
Spectrum Protect Version 8.1.1, V8.1.0, and V7.1.7 or earlier servers. For IBM
Spectrum Protect V8.1.2 or later servers, use server commands on the
administrative command-line client (dsmadmc).
|
|
|
|
Table 20 lists the commands and options that you can use to back up NAS file
system images from the command line.
Table 20. NAS options and commands
Option or command
Definition
Page
domain.nas
Use the domain.nas option to specify the
volumes to include in your default domain
for NAS backups.
“Domain.nas” on page
371
exclude.fs.nas
Use the exclude.fs.nas option to exclude
file systems on the NAS file server from an
image backup when used with the backup
nas command.
“Exclude options” on
page 395
This option is valid for all Windows clients.
164
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 20. NAS options and commands (continued)
Option or command
Definition
Page
include.fs.nas
Use the include.fs.nas option to bind a
management class to Network Attached
Storage (NAS) file systems. You can also
specify whether Table of Contents (TOC)
information is saved during a NAS file
system image backup, using the toc option
with the include.fs.nas option in your
client options file..
“Include options” on
page 426
This option is valid for all Windows clients.
query node
Use the query node command to display all “Query Node” on
the nodes for which a particular
page 722
administrative user ID has authority to
perform operations. The administrative user
ID should have at least client owner
authority over both the NAS node and the
client workstation node they are using.
backup nas
Use the backup nas command to create an
image backup of one or more file systems
that belong to a Network Attached Storage
(NAS) file server.
“Backup NAS” on
page 658
toc
Use the toc option with the backup nas
command or the include.fs.nas option to
specify whether Table of Contents (TOC)
information is saved for each file system
backup.
“Toc” on page 562
monitor process
Use the monitor process command to
“Monitor Process” on
display current backup and restore processes page 700
for all NAS nodes for which an
administrative user has authority. The
administrative user can then select one
process to monitor.
cancel process
Use the cancel process command to display “Cancel Process” on
current backup and restore processes for all page 678
NAS nodes for which an administrative user
has authority. From the display, the
administrative user can select one process to
cancel.
query backup
Use the query backup command with the
class option to display information about
file system images backed up for a NAS file
server.
“Query Backup” on
page 707
query filespace
Use the query filespace command with the
class option to display a list of file spaces
belonging to a NAS node.
“Query Filespace” on
page 714
delete filespace
Use the delete filespace command with the
class option to display a list of file spaces
belonging to a NAS node so that you can
choose one to delete.
“Delete Filespace” on
page 685
A NAS file system specification uses the following conventions:
v NAS nodes represent a new node type. The NAS node name uniquely identifies
a NAS file server and its data to IBM Spectrum Protect. You can prefix the NAS
Chapter 4. Backing up your data
165
node name to the file specification to specify the file server to which the include
statement applies. If you do not specify a NAS node name, the file system you
specify applies to all NAS file servers.
v Regardless of client platform, NAS file system specifications use the forward
slash (/) separator, as in this example: /vol/vol0.
v NAS file system designations on the command line require brace delimiters {}
around the file system names, such as: {/vol/vol0}. Do not use brace delimiters
in the option file.
Note: When you initiate a NAS backup operation by using the client command
line interface, client GUI, or web client the server starts a process to initiate,
control, and monitor the operation. It might take several moments before you
notice progress at the client command line interface because the server must
perform a mount operation, and other necessary tasks, before data movement
occurs.
Related reference:
“Toc” on page 562
Methods for backing up and recovering data on NAS file
servers accessed by CIFS protocol
The backup-archive client can process network-attached storage (NAS) file-server
data that is accessed by using the Common Internet File System (CIFS) protocol.
You can use the following methods to back up and recover data on NAS devices:
v Use the backup-archive client to back up and restore data, by using CIFS to
access files from the backup-archive client. Data can be stored on the IBM
Spectrum Protect server with file-level granularity, by using the
progressive-incremental backup method. The data is stored in the IBM Spectrum
Protect storage hierarchy and can be migrated, reclaimed, and backed up to a
copy storage pool.
This method increases processor usage when the client accesses individual files.
The method requires that the data to flow through the client. This method also
requires that the data flows through the IBM Spectrum Protect server unless a
LAN-free configuration is used.
v Use the snapdiff option to mitigate the performance problems of CIFS backup.
This option stores data with file-level granularity by using progressive
incremental backup for CIFS.
v Use a backup-archive client that is running on the NAS device, if you can use
external programs with the NAS operating system.
This method decreases processor usage of CIFS. Data can be stored on the IBM
Spectrum Protect server with file-level granularity by using
progressive-incremental backup. The data is stored in the IBM Spectrum Protect
storage hierarchy and can be migrated, reclaimed, and backed up to a copy
storage pool. This method requires that data flow through the backup-archive
client. This method also requires that the data flows over a network and through
the IBM Spectrum Protect server unless a LAN-free configuration is used.
v Use NDMP with the backup-archive client. File systems are backed up as full
images (all files) or differential images (all files that changed since the last full
backup). Backed up images are stored on a tape device that is accessed by the
NAS file server. This method provides high performance because there is no
data flow through a backup-archive client or IBM Spectrum Protect server. Data
that is backed up to the server by using NDMP cannot be migrated, reclaimed,
or backed up to a copy storage pool.
166
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
The following limitations exist for NAS file server data when it is accessed by
using CIFS:
v File and directory security information might be inaccessible when the Windows
account that is performing the backup is not a member of the Domain
Administrators group of the domain the NAS file server is a trusted member of.
It is also possible that these security access failures might prevent the entire file
or directory from being backed up.
v Performance degradation occurs because data is being accessed remotely.
v The mapped drives appear to the client as NTFS file systems, but they might not
have full NTFS functionality. For example, the encryption attribute of a file is
set, but when the client backs up the file, the backup fails because the
volume-level encryption setting indicates that encryption cannot be used for the
volume. ReFS file systems also appear to the client as NTFS file systems.
Tip: Use NDMP with the backup-archive client on a NAS file server to back up
and restore volumes instead of backing up and restoring the volumes by using
remote mapped drives.
Related reference:
“Snapdiff” on page 528
Support for CDP Persistent Storage Manager
Persistent Storage Manager (PSM) is the snapshot technology that is included with
a number of Microsoft Server Appliance Kit-based NAS boxes that include the IBM
TotalStorage NAS 200, 300, and 300G.
You can use the backup-archive client to back up the persistent images (PI) of a
volume that is produced by PSM. You must first ensure that the volume has a
label. You can then use PSM to schedule or create a persistent image with a
specific image name, such as snapshot.daily, and set the number of images to
save to 1. PSM overwrites the PI as needed and you can use the client to
incrementally back up the PI. In this case, the client backs up only the files that
changed between snapshots. One advantage of backing up a PSM PI rather than
the actual volume, is that there are no open files in the PI.
Consider the following items before you use Persistent Storage Manager:
v By default, a PSM schedule uses a variable name (snapshot.%i) and keeps a
number of images.
Important: Do not use the client with PSM in this manner. The client considers
each image as unique and makes a complete copy of each image.
v The client requires that the volume used to make the PI has a label. If the
volume does not have a label, the client does not back up its PI.
v You use the image backup function to back up the original volume that is used
to create the PI. However, you cannot use the backup image function to back up
the PI.
v To avoid backing up unnecessary files when you back up PSM, include the
following entries in your client option file (dsm.opt):
exclude.dir "Persistent Storage Manager State"
exclude.file "*.psm"
exclude.file "*.otm"
Chapter 4. Backing up your data
167
Backing up VMware virtual machines
You can use the backup-archive client to back up and restore a VMware virtual
machine (VM). Full backups of the virtual machine operate at a disk image level.
Incremental backups copy only the data that is changed since the previous full
backup.
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments: Data Protection for VMware.
Table 21 lists the backup and restore operations for VMware virtual machines that
the backup-archive client can implement on Windows platforms.
Restriction: You can complete VMware backup and restore operations with the
backup-archive client only on 64-bit Windows operating systems.
Table 21. Backup and restore capabilities for VMware virtual machines on Windows platforms
Capability
Comment
Full VM incremental-forever
backup:
Requires the IBM Spectrum Protect for Virtual Environments licensed product.
A full VM backup is required before you can create incremental backups. If you
schedule incremental-forever backups, this backup type is selected automatically for
the first backup if a full backup was not already created. Data from incremental
backups is combined with data from the full backup to create a synthetic full backup
image. Subsequent full VM incremental-forever backups read all used blocks and copy
those blocks to the IBM Spectrum Protect server. Each full VM incremental-forever
backup reads and copies all of the used blocks, whether the blocks are changed or not
since the previous backup. You can still schedule a full VM backup, although a full
backup is no longer necessary. For example, you might run a full VM backup to create
a backup to a different node name with different retention settings.
You cannot use this backup mode to back up a VMware virtual machine if the client is
configured to encrypt the backup data.
Incremental-foreverincremental VM backup:
Requires the IBM Spectrum Protect for Virtual Environments licensed product.
Requires you to create a full VM backup one time only. The full VM backup copies all
of the used disk blocks owned by a virtual machine to the IBM Spectrum Protect
server. After the initial full backup is complete, all subsequent backups of the virtual
machine are incremental-forever-incremental backups. Each incremental-foreverincremental backup copies only the blocks that are changed since the previous backup,
irrespective of the type of the previous backup. The server uses a grouping technology
that associates the changed blocks from the most recent backup with data already
stored on the server from previous backups. A new full backup is then effectively
created each time changed blocks are copied to the server by an incremental-foreverincremental backup.
The incremental-forever-incremental backup mode provides the following benefits:
v Improves the efficiency of backing up virtual machines.
v Simplifies data restore operations.
v Optimizes data restore operations.
During a restore operation, you can specify options for point-in-time and point-in-date
to recover data. The data is restored from the original full backup and all of the
changed blocks that are associated with the data.
You cannot use this backup mode to back up a VMware virtual machine if the client is
configured to encrypt the backup data.
168
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 21. Backup and restore capabilities for VMware virtual machines on Windows platforms (continued)
Capability
Comment
Item recovery for files and
Requires the IBM Spectrum Protect for Virtual Environments licensed product.
folders from a full backup of
Provides the capability to recover files and folders from a full backup of a virtual
the virtual machine:
machine. Item recovery is available only with the IBM Spectrum Protect recovery
agent.
Full restore of the virtual
machine:
Restores all of the file systems, virtual disks, and the virtual machine configuration.
File-level restore of the
virtual machine:
The restore approach depends on the type of backup of the virtual machine:
v If you have a license for IBM Spectrum Protect for Virtual Environments, you can
restore files and directories from a full VM image backup.
v Backup-archive client users can restore files and directories that are created file-level
backups of a virtual machine. You use the restore command to restore individual
files from a file-level backup of a virtual machine, not the restore vm command.
Note: File-level backups were created with the version 7.1 or earlier backup-archive
clients.
Related concepts:
“Parallel backups of virtual machines” on page 173
Related tasks:
“Preparing the environment for full backups of VMware virtual machines”
“Creating full backups for VMware virtual machines” on page 171
Preparing the environment for full backups of VMware virtual
machines
Complete the following steps to prepare the VMware environment for backing up
full VMware virtual machines. The vStorage backup server can run either a
Windows or Linux client.
Before you begin
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments: Data Protection for VMware.
Procedure
1. To configure the storage environment for backing up, complete the following
steps:
a. Configure your storage environment so that the vStorage backup server can
access the storage volumes that are in your ESX server farm.
b. If you are using network-attached storage (NAS) or direct-attach storage,
ensure that the vStorage backup server is accessing the volumes with a
network-based transport.
c. Optional: For data access, make the following settings:
v Create storage area network (SAN) zones that your vStorage backup
server can use to access the storage logical units (LUNs) that host your
VMware datastores.
v
Configure your disk subsystem host mappings so that all ESX servers
and the backup proxy can access the same disk volumes.
2. To configure the vStorage backup server, complete the following steps:
Chapter 4. Backing up your data
169
a. When the backup-archive client runs on a vStorage backup server, this
client configuration is called the IBM Spectrum Protect data mover node. A
Windows system that is a data mover must have the 64-bit Windows client
installed on it. A data mover node typically uses the SAN to back up and
restore data. If you configure the data mover node to directly access the
storage volumes, turn off automatic drive letter assignment. If you do not
turn off letter assignments, the client on the data mover node might corrupt
the Raw Data Mapping (RDM) of the virtual disks. If the RDM of the
virtual disks is corrupted, backups fail. Consider the following conditions
for restore configurations:
The data mover node is on a Windows Server 2012 or Windows Server
2012 R2 system:
If you plan to use the SAN to restore data, you must set the
Windows SAN policy to OnlineAll. Run diskpart.exe and type the
following commands to turn off automatic drive letter assignment
and set the SAN policy to OnlineAll:
diskpart
automount disable
automount scrub
san policy OnlineAll
exit
The backup-archive client is installed in a virtual machine on a Windows
Server 2012 or Windows Server 2012 R2 system:
If you plan to use the hotadd transport to restore data from
dynamically added disks, the SAN policy on that system must also
be set to OnlineAll.
Whether the client uses the SAN or hotadd transport, the Windows
SAN policy must be set to OnlineAll. If the SAN policy is not set to
OnlineAll, restore operations fail, and the following message is
returned:
ANS9365E VMware vStoragee API error.
IBM Spectrum Protect function name: vddksdk Write
IBM Spectrum Protect file : vmvddkdsk.cpp (2271)
API return code : 1
API error message : Unknown error
ANS0361I DIAG: ANS1111I VmRestoreExtent(): VixDiskLib_Write
FAILURE startSector=512 sectorSize=512 byteOffset=262144,
rc=-1
For a description of the vStorage transport settings and how you can
override the defaults, see the following topic:
“Vmvstortransport” on page 627
b. Install the backup-archive client on the vStorage backup server. At the
custom setup page of the installation wizard, select VMware vStorage API
runtime files.
Important: If you are moving the backup data by using backups that are
not in a LAN, the SAN must have separate connections for tape and disk.
3. To modify IBM Spectrum Protect, complete the following steps:
a. Access the administrative command line on the backup-archive client.
b. From the backup-archive client on the vStorage backup server, run the
following command to register the node:
register node my_server_name my_password
170
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Where my_server_name is the full computer name of the vStorage backup
server and my_password is the password to access the server.
Tip: On Windows systems, you can get the server full computer name by
right-clicking on My Computer. Click the Computer Name tab and look at
the name listed next to Full computer name.
c. From the backup-archive client on the vStorage backup server, run the
following command to register the node:
register node my_vm_name my_password
Where my_vm_name is the full name of the virtual machine that you are
backing up.
4. If you back up a virtual machine where volumes are mounted to directories
rather than drive letters, files might not be stored in the correct location. An
error might be caused because the mount point does not correspond to the
actual mount points of backed up files. An error is caused because the mount
points for a virtual machine that is running Windows do not have a drive letter
assignment. When you use the VMware vStorage APIs for Data Protection, a
filespace name is created that includes a number assignment. The filespace
names that are created for the mount point do not correspond to the actual
mount points of the backed up file.
To back up or restore files to their original location, use the following steps:
a. To restore files to their original location, map the drive or assign a drive
letter to the mount point from the virtual machine.
b. If you restore a file that the vStorage API renamed, select a different restore
location.
c. When using mount points without drive letter assignments, use an include
or exclude statement for that volume. See the following example of an
exclude statement:
exclude \\machine\3$\dir1\...\*.doc
Related tasks:
“Creating full backups for VMware virtual machines”
Related reference:
“Backup VM” on page 662
“Query VM” on page 729
“Restore VM” on page 760
“Vmchost” on page 579
“Vmcpw” on page 580
“Vmcuser” on page 582
“Vmvstortransport” on page 627
Creating full backups for VMware virtual machines
A full backup of a VMware virtual machine is a backup of an entire virtual
machine, including the virtual disks and the virtual machine configuration file.
This type of backup is similar to an image backup. To create the full backup, you
configure the backup-archive client on the vStorage backup server. The vStorage
backup server must run a Windows client or a Linux client.
Chapter 4. Backing up your data
171
Before you begin
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments: Data Protection for VMware.
Procedure
1. To prepare the environment, complete the steps in the following topic:
“Preparing the environment for full backups of VMware virtual machines” on
page 169
2. To configure the backup-archive client on the vStorage backup server, complete
the following steps:
a. From the welcome page of the backup-archive client GUI, click Edit >
Client Preferences.
b. Select the VM Backup tab.
c. Select VMWare Full VM.
d. In the Domain Backup Types list, select Domain Full VM.
e. In the Host field, enter either the host name of each ESX server or the host
name of the Virtual Center. If you specify the Virtual Center, you can back
up virtual machines from any of the VMware servers that are managed by
the Virtual Center.
f. Enter the user ID and password information for the host that you specify in
the Host field.
g. Optional: If you want to override the default management class for full
virtual machine backups, specify the management class that you want to
use.
h. In the Datastore Location field, enter the path to the directory where the
files are stored.
i. Click OK to save your changes.
3. To create a backup of one of the virtual machines, complete the following steps:
a. At the command line of the vStorage backup server, run the following
command:
dsmc backup vm my_vm_name -mode=iffull -vmbackuptype=fullvm
Where my_vm_name is the name of the virtual machine.
b. Verify that the command is completed without errors. The following
message indicates successful completion:
Backup VM command complete
Total number of virtual machines
virtual machine vmname backed up
Total number of virtual machines
Total number of virtual machines
backed up successfully: 1
to nodename NODE
failed: 0
processed: 1
4. To verify that you can restore the files for the virtual machine, complete the
following steps:
a. At the command-line interface of the vStorage backup server, run the
following command:
dsmc restore vm my_vm_name
The default location of the restore is in the following directory:
c:\mnt\tsmvmbackup\my_vm_name\fullvm\
RESTORE_DATE_yyyy_mm_dd[hh_mm_ss].
172
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
b. If errors occur in the restore processing, view the client error log for more
information.
Tip: The error log is saved to the following file:
c:\Program Files\Tivoli\TSM\baclient\dsmerror.log
Related concepts:
“Parallel backups of virtual machines”
Related tasks:
“Preparing the environment for full backups of VMware virtual machines” on page
169
Related reference:
“Backup VM” on page 662
“Domain.vmfull” on page 372
“Query VM” on page 729
“Restore VM” on page 760
“Mode” on page 460
“Vmchost” on page 579
“Vmcpw” on page 580
“Vmcuser” on page 582
“Vmmc” on page 604
“Vmvstortransport” on page 627
Parallel backups of virtual machines
With parallel backup processing, you can use a single data mover node to back up
multiple virtual machines (VMs) at the same time to optimize your backup
performance.
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments.
For information about parallel backup operations, see Backing up multiple virtual
machines in parallel.
Back up virtual machines on a Hyper-V system
You can use the backup-archive client to backup virtual machines that are
managed by a Microsoft Hyper-V server.
For information about protecting Hyper-V virtual machines, see IBM Spectrum
Protect for Virtual Environments, Data Protection for Microsoft Hyper-V .
Related reference:
“Backup VM” on page 662
“Query VM” on page 729
“Restore VM” on page 760
Hyper-V backup support limitations
Because of the tight integration of Microsoft Failover Clustering with Cluster
Shared Volumes and Hyper-V, the following limitations apply when you are using
the backup-archive client.
Chapter 4. Backing up your data
173
For the description of limitations, see IBM Spectrum Protect for Virtual
Environments, Data Protection for Microsoft Hyper-V backup support limitations.
Back up and archive Tivoli Storage Manager FastBack data
Use Tivoli Storage Manager FastBack to back up and archive the latest snapshots
for short-term retention.
Use the archive fastback and backup fastback commands to archive and back up
volumes that are specified by the fbpolicyname, fbclientname and fbvolumename
options for short-term retention.
Related concepts:
“Installation requirements for backing up and archiving Tivoli Storage Manager
FastBack client data” on page 5
“Configuring the client to back up and archive Tivoli Storage Manager FastBack
data” on page 63
Related reference:
“Fbclientname” on page 403
“Fbpolicyname” on page 405
“Fbvolumename” on page 409
Backing up Net Appliance CIFS share definitions
Network Appliance (NetApp) CIFS share definitions include share permissions that
are set on the file server.
About this task
The Windows client backs up the CIFS share definition under the root directory,
the mapped CIFS share, or the UNC name. This support requires that the Net
Appliance file server is running DATA ONTAP software, which presents CIFS
shares to remote clients as ordinary remote NTFS shares.
The root directory of a CIFS share is backed up with a full progressive incremental
backup of the mapped drive/UNC name. See the following two examples:
net use x: \\NetAppFiler\CifsShareName
dsmc incr x:
dsmc incr \\NetAppFiler\CifsShareName
The following output is displayed when the root directory (and share definition) is
backed up:
Directory-->
0 \\NetAppFiler\CifsShare\ [Sent]
Related concepts:
“Restore Net Appliance CIFS shares” on page 202
Related reference:
“Snapdiff” on page 528
Display backup processing status
During a backup, by default the backup-archive client displays the status of each
file it attempts to back up.
174
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
The client reports the size, path, file name, total number of bytes transferred, and
whether the backup attempt was successful for the file. These are also recorded in
the dsmsched.log file for scheduled commands.
The web client and backup-archive client GUI provide a Task List window that
displays information about files during processing. When a task completes, a
Backup Report window displays processing details. Click the Help button in the
Backup Report window for context help.
On the backup-archive command line, the name of each file is displayed after it is
sent to the server. The progress indicator shows overall progress.
Table 22 lists some informational messages and meanings.
Table 22. Client command line informational messages
Informational message
Meaning
Directory-->
Indicates the directory that you back up.
Updating-->
Indicates that only the file meta data is sent, not the data itself.
Expiring-->
Indicates an object (file or directory) on the server that no longer exists
on the client is expired and made inactive on the server.
Total number of objects inspected:
As indicated. When using journal-based backup, the number of objects
that are inspected might be less than the number of objects that are
backed up.
When you use the snapshot difference incremental backup, the number
of objects that are inspected is zero. The number is zero because the
client performs an incremental backup of the files that NetApp reported
as changed. The client does not scan the volume looking for files that
have changed.
Total number of objects backed up:
As indicated.
Total number of objects encrypted:
This is a count of the objects that were encrypted during backup or
archive processing.
Data encryption type:
Specifies the encryption algorithm type (e.g 256-bit AES), if one or more
objects are encrypted during backup or archive processing.
Total number of objects updated:
These are files whose attributes, such as file owner or file permissions,
have changed.
Total number of objects rebound:
See “Bind management classes to files” on page 269 for more
information.
Total number of objects deleted:
This is a count of the objects that are deleted from the client workstation
after being successfully archived on the server. The count is zero for all
backup commands.
Total number of objects expired:
See the section about full and partial incremental backup for more
information.
Total number of objects failed:
Objects can fail for several reasons. Check the dsmerror.log for details.
Total snapshot difference objects:
For snapshot difference incremental backups, this represents the total
number of objects backed up and the total number of objects expired.
Total objects deduplicated:
Specifies the number of files that are deduplicated.
Total bytes before deduplication:
Specifies the number of bytes to send to the IBM Spectrum Protect server
if the client does not eliminate redundant data. Compare this amount
with Total bytes after deduplication. Includes metadata size and
might be greater than bytes inspected.
Chapter 4. Backing up your data
175
Table 22. Client command line informational messages (continued)
Informational message
Meaning
Total bytes after deduplication:
Specifies the number of bytes that are sent to the IBM Spectrum Protect
server after deduplication of the files on the client computer. Includes
metadata size and might be greater than bytes processed.
Total number of bytes inspected:
Specifies the sum of the sizes of the files that are selected for the
operation. For example, the total number of bytes inspected for this
command is the number of bytes used in the directory C:\Users
dsmc.exe INCREMENTAL C:\Users\* -su=yes
Total number of bytes processed:
Specifies the sum of the sizes of the files that are processed for the
operation.
Data transfer time:
The total time to transfer data across the network. Transfer statistics
might not match the file statistics if the operation was retried due to a
communications failure or session loss. The transfer statistics display the
bytes attempted to be transferred across all command attempts.
Network data transfer rate:
The average rate at which the network transfers data between the client
and the server. This is calculated by dividing the total number of bytes
transferred by the time to transfer the data over the network. The time it
takes to process objects is not included in the network transfer rate.
Therefore, the network transfer rate is higher than the aggregate transfer
rate.
Aggregate data transfer rate:
The average rate at which IBM Spectrum Protect and the network
transfer data between the client and the server. This is calculated by
dividing the total number of bytes transferred by the time that elapses
from the beginning to the end of the process. Both IBM Spectrum Protect
processing and network time are included in the aggregate transfer rate.
Therefore, the aggregate transfer rate is lower than the network transfer
rate.
Note: On occasion, the aggregate data transfer rate might be higher than
the network data transfer rate. This is because the backup-archive client
can have multiple simultaneous sessions with the backup server. If you
set the resourceutilization option, the client attempts to improve
performance and load balancing by using multiple sessions when it
backs up a volume or other set of files. When multiple sessions are open
during backup, the data transfer time represents the sum of the times
reported by all sessions. In this case, aggregate data transfer time is
incorrectly reported as higher. However, when running with a single
session, the aggregate data transfer rate should always be reported as
lower than the network data transfer rate.
Objects compressed by:
Specifies the percentage of data sent over the network divided by the
original size of the file on disk. For example, if the net data-bytes are 10K
and the file is 100K, then Objects compressed by: == (1 - (10240/102400))
x 100 == 90%.
Total number of objects grew:
The total number of files that grew larger as a result of compression.
Deduplication reduction:
Specifies the size of the duplicate extents that were found, divided by the
initial file or data size. For example, if the initial object size is 100 MB,
after deduplication it is 25 MB. The reduction would be: (1 - 25/100) *
100 = 75%.
Total data reduction ratio:
Adds incremental and compression effects. For example, if the bytes
inspected are 100 MB and the bytes sent are 10 MB, the reduction would
be: (1 - 10/100) * 100 = 90%
Elapsed processing time:
The active processing time to complete a command. This is calculated by
subtracting the starting time of a command process from the ending time
of the completed command process.
176
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 22. Client command line informational messages (continued)
Informational message
Meaning
Total number of bytes transferred:
As indicated.
LanFree bytes transferred:
The total number of data bytes transferred during a lan-free operation. If
the enablelanfree option is set to no, this line will not appear.
Total number of bytes inspected:
A sum of sizes of files selected for the operation.
Total number of retries:
The total number of retries during a backup operation. Depending on the
settings for the serialization attribute and the changingretries option, a
file that is opened by another process might not be backed up on the
first backup try. The backup-archive client might try to back up a file
several times during a backup operation. This message indicates the total
retries for all files that are included in the backup operation.
Backup (Windows): Additional considerations
This section discusses additional information to consider when backing up data.
Open files
Some files on your system might be in use when you try to back them up. These
are called open files because they are locked by an application for its exclusive use.
It is not very common for files to be opened in locked mode. An application can
open a file in this way to avoid other applications or users from reading or
accessing the file, but it can prevent backup programs from reading the file for
backup.
You might not always want to use the open file feature to back up open or locked
files. Sometimes an application opens a file or group of files in this locked mode to
prevent the access of these files in an inconsistent state.
To avoid the increase of processor usage when you create a volume snapshot for
each backup, and on platforms where the open file feature is not available or is not
in use, consider the following points:
v If the file is unimportant or can be easily rebuilt (a temporary file for example),
you might not care if the file is backed up, and might choose to exclude it.
v If the file is important:
– Ensure the file is closed before backing it up. If backups are run according to
a schedule, use the preschedulecmd option to enter a command that closes the
file. For example, if the open file is a database, issue a command to close the
database. You can use the postschedulecmd option to restart the application
that uses the file after the backup completes. If you are not using a schedule
for the backup, close the application that uses the file before you start the
backup.
– The client can back up the file even if it is open and changes during the
backup. This is only useful if the file is usable even if it changes during
backup. To back up these files, assign a management class with dynamic or
shared dynamic serialization.
Note: If open file support is not configured: While the client attempts to back up
open files, this is not always possible. Some files are open exclusively for the
application that opened them. If the client encounters such a file, it cannot read it
Chapter 4. Backing up your data
177
for backup purposes. If you are aware of such file types in your environment, you
should exclude them from backup to avoid seeing error messages in the log file.
Related concepts:
“Display information about management classes and copy groups” on page 263
“Select a management class for files” on page 267
Ambiguous file space names in file specifications
If you have two or more file spaces such that one file space name is the same as
the beginning of another file space name, then an ambiguity exists when you try to
restore, retrieve, query, or do another operation that requires the file space name as
part of the file specification.
For example, consider the following file spaces and the backup copies they contain:
File space name
File name
\\storman\home
amr\project1.doc
\\storman\home\amr
project2.doc
Notice that the name of the first file space, \\storman\home, matches the beginning
of the name of the second file space, \\storman\home\amr. When you use the
backup-archive command-line client interface to restore or query a file from either
of these file spaces, by default the client matches the longest file space name in the
file specification, \\storman\home\amr. To work with files in the file space with the
shorter name, \\storman\home, use braces around the file space name portion of
the file specification.
This means that the following query command finds project2.doc but does not
find project1.doc:
dsmc query backup "\\storman\home\amr\*"
This is because the longer of the two file space names is \\storman\home\amr and
that file space contains the backup for project2.doc.
To find project1.doc, enclose the file space name in braces. The following
command finds project1.doc but does not find project2.doc:
dsmc query backup "{\\storman\home}\amr\*"
Similarly, the following command restores project1.doc but does not restore
project2.doc:
dsmc restore {\\storman\home}\amr\project1.doc
Management classes
IBM Spectrum Protect uses management classes to determine how to manage your
backups on the server.
Every time you back up a file, the file is assigned a management class. The
management class used is either a default selected for you, or one that you assign
to the file using an include option in the include-exclude options list. The selected
management class must contain a backup copy group for the file to be backed up.
178
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Select Utilities → View Policy Information from the backup-archive client or web
client GUI to view the backup policies defined by the IBM Spectrum Protect server
for your client node.
Related concepts:
Chapter 9, “Storage management policies,” on page 261
Related tasks:
“Setting the client scheduler process to run as a background task and start
automatically at startup” on page 246
Deleted file systems
When a file system or drive has been deleted, or it is no longer backed up by the
client, the existing backup versions for each file are managed according to the
following policy attributes: Number of days to keep inactive backup versions, and
number of days to keep the last backup version (if there is no active version).
If you do nothing else, active backup versions remain indefinitely. If you do not
need to keep the active versions indefinitely, use the expire command to inactive
the active versions.
You can also use the delete backup command to delete individual backup
versions, or the delete filespace command to delete the entire file space. Your IBM
Spectrum Protect server administrator must give you "delete backup" authority to
use these commands. If the file space also contains archive versions, you must also
have delete archive authority to use delete filespace.
Use the query session command to determine whether you have delete backup
and delete archive authority. Alternatively, you can ask your IBM Spectrum Protect
server administrator to delete the file space for you.
When you delete a file system, it has no effect on existing archive versions.
However, if you no longer require the archive versions, you can use the delete
archive or delete filespace commands to delete archives.
Related concepts:
Chapter 9, “Storage management policies,” on page 261
Removable media backup
The backup-archive client backs up your removable media (such as tapes,
cartridges or diskettes) based on the drive label, not the drive letter.
If a drive has no label, the backup does not occur. This use of drive labels permits
you to perform such tasks as backing up different diskettes from the a: drive.
For a restore or retrieve, a separate file space for each drive label is maintained.
These labels become the file space names on the IBM Spectrum Protect server. If
you change the label of a drive you already backed up, the client views it as a new
drive and does not relate it to your previous drive.
Because the client uses the labels to manage backups and archives of your
removable media, you occasionally need to use those labels to locate data when
using commands. For example, if you try to restore a file on diskette or
DVD–ROM using d:\projx\file.exe as a file name, IBM Spectrum Protect
Chapter 4. Backing up your data
179
substitutes the current label of your d: drive for the d:. If the d: drive label is
d-disk, d:\projx\file.exe becomes {d–disk}\projx\file.exe, and the label is
enclosed in braces.
If the label of the d: drive does not match a file space name on the server, IBM
Spectrum Protect cannot locate your files using the current d: drive label.
However, the client can locate your files if you use the file space name based on
the original drive label. A mismatch between a label and a file space name might
occur if you label your drives again, or if you access IBM Spectrum Protect from a
different workstation than the one from which you backed up the files. If you have
not relabeled the drive, and you are at the same workstation where the file was
backed up, then you can use the drive letter as a shorthand version of the file
space name (drive label).
Fixed drives
The backup-archive client can back up your fixed drives even if they do not have a
label, including drive aliases created with the DOS subst command. This applies to
both the drive alias and the underlying physical drive, because the alias name and
the physical drive label are the same.
NTFS and ReFS file spaces
When you back up files on NTFS or ReFS partitions, the client also backs up file
security information and file descriptors.
The following file descriptors are backed up:
v Owner security information (SID)
v Primary group SID
v Discretionary access-control list
v System access-control list
You must specify a file space name that is mixed case or lowercase text, and
enclosed in quotation marks and braces. For example, {"NTFSDrive"}. Single
quotation marks or double quotation marks are valid in loop mode. For example:
{"NTFSDrive"} and {’NTFSDrive’} are both valid. In batch mode, only single
quotation marks are valid. The single quotation mark requirement is a restriction
of the operating system.
Universal Naming Convention names
A Universal Naming Convention (UNC) name is a network resource name for a
share point on a workstation.
The resource name includes the workstation name assigned to the workstation and
a name you assign to a drive or directory so that it can be shared. The name you
assign is also called a share point name.
Examples: UNC names in domain lists
This topic shows some examples of using UNC names to specify a domain list.
About this task
You must specify the following information:
v A drive letter for removable media
v Drive letters or UNC name for local fixed drives
v Drive letters or UNC names for remote mapped drives
180
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
v UNC names for remote unmapped drives
Example 1: To specify drive a: containing removable media, enter
domain a: \\local\c$
Example 2: To specify fixed drive c:, enter
domain c: \\remote\share1 \\remote\c$
Examples: UNC name backup
You can back up shared files in a network through the use of a UNC name. Some
examples of backing up UNC name files are shown.
A UNC name is a network resource name for a share point on a workstation. The
resource name includes the workstation name assigned to the workstation and a
name you assign to a drive or directory so that it can be shared. The name you
assign is also called a share point name.
Using a UNC name permits you to back up specific shared directories to a separate
file space. This is useful if, for example, you or an administrator want to back up a
small portion of data that you would otherwise be unable to access. Drives are not
backed up to a separate file space.
Every local drive is accessible using a UNC name except for drives containing
removable media (such as tapes, cartridges or diskettes). Access these drives by
using a predefined administrative share name consisting of the workstation name
and the local drive letter, followed by $. For example, to specify a UNC name on
the c: drive for workstation ocean, enter:
\\ocean\c$
The $ sign must be included with the drive letter.
To enter a UNC name for workstation ocean and share point wave, enter:
\\ocean\wave
When accessing files, you do not need to enter the letter of the drive except for
drives containing removable media.
See the following table for examples showing selective backup of files using UNC
names. In these examples, assume that:
v The workstation running dsmc is major.
v Share names betarc and testdir from workstation alpha1 are mapped to drives
r and t, respectively.
Table 23. UNC examples
Example
Comment
dsmc sel \\alpha1\c$\
name of remote file space is \\alpha1\c$
dsmc sel \\major\c$\
name of local, fixed file space is \\major\c$
dsmc sel a:\
name of local, removable file space is volume
label of a:
dsmc sel \\alpha1\betarc\
name of remote file space is \\alpha1\betarc
dsmc sel \\alpha1\testdir\
name of remote file space is
\\alpha1\testdir
dsmc sel d:\
name of local, fixed file space is \\major\d$
Chapter 4. Backing up your data
181
Table 23. UNC examples (continued)
Example
Comment
dsmc sel c:\
file space name is \\major\c$
dsmc sel r:\
file space name is \\alpha1\betarc
You can also specify UNC names for files in your include-exclude and domain
lists.
Related tasks:
“Creating an include-exclude list” on page 88
Related reference:
“Domain” on page 367
Microsoft Dfs file protection methods
There are some methods that you can use to protect the data in your Microsoft Dfs
environment.
About this task
Here are the methods you should use to protect your Microsoft Dfs data:
Procedure
1. Back up the Dfs link metadata and the actual data at the share target of each
link from the workstation hosting the Dfs root. This method simplifies back up
and restore by consolidating all of the IBM Spectrum Protect activities on a
single workstation. This method has the disadvantage of requiring an
additional network transfer during backup to access the data stored at link
targets.
2. Back up only the Dfs link metadata that is local to the workstation hosting the
Dfs root. Back up the data at the target of each link from the workstation(s)
which the data is local too. This method increases back up and restore
performance by eliminating the extra network transfer, but requires back up
and restore operations to be coordinated among several workstations.
Results
Note:
1. See the product README file for current limitations of this feature.
Files contained on a Dfs server component are accessed using a standard UNC
name, for example:
\\servername\dfsroot\
where servername is the name of the host computer and dfsroot is the name of the
Dfs root.
If you set the dfsbackupmntpnt option to yes (the default), an incremental backup of
a Dfs root does not traverse the Dfs junctions. Only the junction metadata is
backed up. This is the setting you should use so that the client can be used to
restore Dfs links.
You can use the dfsbackupmntpnt option to specify whether the client sees a Dfs
mount point as a Microsoft Dfs junction or as a directory.
182
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Important: Restore the Dfs junction metadata first. This recreates the links. Then
restore each junction and the data at each junction separately. If you do not restore
the junction metadata first, the client creates a directory under the Dfs root using
the same name as the junction point and restores the data in that directory.
The following example relates to method 1 above and illustrates how to use the
client to back up and restore a Microsoft Dfs environment. Assume the existence of
a domain Dfs environment hosted by the workstation wkst1:
Dfs root
\\wkst1\abc64test
Dfs link1
\\wkst1\abc64test\tools
Dfs link2
\\wkst1\abc64test\trees
Backup procedure:
1. Set the dfsbackupmntpnt option to yes in your client options file (dsm.opt).
2. Enter the following command to back up link junction information:
dsmc inc \\wkst1\abc64test
3. Enter the following command to back up data at the tools link:
dsmc inc \\wkst1\abc64test\tools
4. Enter the following command to back up data at the trees link:
dsmc inc \\wkst1\abc64test\trees
Note: DFS Replication uses staging folders to act as caches for new and changed
files to be replicated from sending members to receiving members. If you do not
want to backup these files, you can exclude them from your backup using the
exclude.dir option.
exclude.dir x:\...\Dfsrprivate
Restore procedure:
1. Manually recreate shares at target workstations only if they no longer exist.
2. Manually recreate the Dfs root using the exact name as it existed at the time of
back up.
3. Enter the following command to recover data from the tools link. This step is
not necessary if the data still exists at the link target:
dsmc restore \\wkst1\abc64test\tools\* -sub=yes
4. Enter the following command to recover data from the trees link. This step is
not necessary if the data still exists at the link target:
dsmc restore \\wkst1\abc64test\trees\* -sub=yes
5. Use the Distributed File System management console snap-in to reestablish
replication for each link, if necessary.
The following limitations exist for restoring Microsoft Dfs data:
v The client does not restore root of Dfs. To recreate the Dfs tree, manually create
the Dfs root first, then start restore to recreate the links.
Chapter 4. Backing up your data
183
v The client can back up the Dfs tree (both domain based Dfs and stand alone Dfs)
hosted on local workstation only. You cannot back up Dfs if the Dfs host server
is not your local workstation.
v The client cannot recreate shared folders on restore. For example, if you delete
the junction and the shared folder the junction points to, restoring the Dfs root
recreates the Dfs junction, but restoring a junction creates a local folder instead
of creating the original backed up shared network folder.
v If a Dfs link is created with replica and the replica share is on a different server,
the client does not display the replica data.
v If a Dfs root is added or modified, the client will not back it up. You must
specify the Dfs root in the domain option in the client options file (dsm.opt)
regardless of whether DOMAIN ALL-LOCAL is specified.
184
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chapter 5. Restoring your data
Use IBM Spectrum Protect to restore backup versions of specific files, a group of
files with similar names, or entire directories.
You can restore these backup versions if the original files are lost or damaged.
Select the files that you want to restore by using a file specification (file path,
name, and extension), a directory list, or a subdirectory path to a directory and its
subdirectories.
Note: When you restore a directory, its modification date and time is set to the
date and time of the restore operation, and not to the date and time the directory
had when it was backed up. This is because IBM Spectrum Protect restores the
directories first, then adds the files to the directories.
All client backup and restore procedures that are referenced by this topic also
apply to the web client. However, the web client does not provide a Preferences
Editor for setting client options.
The following are the primary restore tasks:
v “Restoring files and directories” on page 187
v “Restoring Windows system state” on page 191
v “Restoring Automated System Recovery files” on page 192
v “Microsoft Dfs tree and file restore” on page 193
v “Restoring an image” on page 194
v “Restore data from a backup set” on page 196
v “Restoring data to a point in time” on page 227
v “Restore NAS file systems” on page 228
v “Authorizing another user to restore or retrieve your files” on page 223
v “Restoring or retrieving files from another client node” on page 224
v “Restoring or retrieving your files to another workstation” on page 225
v “Deleting file spaces” on page 226
v “Restoring data from a VMware backup” on page 202
Related tasks:
“Starting a web client session” on page 117
Duplicate file names
If you attempt to restore or retrieve a file whose name is the same as the short
name of an existing file, a file name collision occurs (existence of duplicate file
names).
An example is when the file abcdefghijk.doc has a short name of abcdef~1.doc, and
you attempt to restore or retrieve a file explicitly named abcdef~1.doc into the same
directory. In this case, a collision occurs because the name of the file you are
restoring conflicts with the short name for abcdefghijk.doc.
A collision can occur even if the files are restored or retrieved to an empty
directory. For example, files abcdef~1.doc and abcdefghijk.doc might originally have
© Copyright IBM Corp. 1993, 2017
185
existed in the directory as abcdefghijk.doc and abcdef~2.doc. During the restore, if
abcdefghijk.doc is restored first, it is assigned a short name of abcdef~1.doc by the
Windows operating system. When you restore abcdef~1.doc, the duplicate file name
situation occurs.
IBM Spectrum Protect handles these situations based on the value of the replace
option. Use the replace option to specify whether to overwrite an existing file, or
to prompt you for your selection when you restore or retrieve files.
If
v
v
v
v
a file name collision occurs, you can do any of the following:
Restore or retrieve the file with the short file name to a different location.
Stop the restore or retrieve and change the name of the existing file.
Disable short file name support on Windows.
Do not use file names, such as abcdef~1.doc, that would conflict with the short
file naming convention.
Related reference:
“Replace” on page 494
Universal Naming Convention names restore
Using a Universal Naming Convention (UNC) name permits you to restore specific
shared files to a separate file space. This is useful if, for example, you or an
administrator want to restore a portion of data that you would otherwise be
unable to access.
Except for drives with removable media, every local drive letter is accessible using
a local UNC name that includes the workstation name and a designation for the
drive letter. For example, to enter a UNC name on drive c: for workstation ocean,
enter:
\\ocean\c$
The $ sign must be included with the drive letter.
To enter a UNC name for workstation ocean and share point wave, enter:
\\ocean\wave
When accessing files, you do not need to enter the letter of the drive except for
drives with removable media.
Active or inactive backup restore
Your administrator determines how many backup versions IBM Spectrum Protect
maintains for each file on your workstation. Having multiple versions of a file
permits you to restore older versions if the most recent backup is damaged.
The most recent backup version is the active version. Any other backup version is
an inactive version. Every time IBM Spectrum Protect backs up your files, it marks
the new backup version as the active backup, and the last active backup becomes
an inactive backup. When the maximum number of inactive versions is reached,
IBM Spectrum Protect deletes the oldest inactive version.
To restore a backup version that is inactive, you must display both active and
inactive versions by clicking on the View menu → Display active/inactive files
item. To display only the active versions (the default), click on the View menu →
186
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Display active files only item. If you try to restore both an active and inactive
version of a file at the same time, only the active version is restored.
On the IBM Spectrum Protect command line, use the inactive option to display
both active and inactive objects.
Related reference:
“Inactive” on page 424
Restoring files and directories
You can locate the files you want to restore by searching and filtering.
Filtering displays only the files that match the filter criteria for your restore
operation. Files that do not match the filter criteria do not display. The filter
process searches files in the specified directory but does not include subdirectories.
Restoring data by using the GUI
You can use the client GUI to restore files and directories.
About this task
Restriction: The web client GUI cannot browse network resources for a restore
operation. No shares are listed if you expand the Network branch. You can restore
to a network resource from the web client if the entire file is processed. Specify the
shared file system in the domain option in the dsm.opt options file. For example,
domain all-local \\server\share. To complete the restore operation, specify
Network Share in the Restore Destination dialog. This processes all file systems
that are specified by the domain option. Alternatively, you can use the GUI Client
to complete the restore operation.
Procedure
1. Click Restore on the main window. The Restore window appears.
2. Expand the directory tree by clicking the plus (+) sign or the folder icon next to
an object in the tree. Select the object that you want to restore. To search or
filter files, click the Search icon from the toolbar.
3. Click the selection box for the objects that you want to restore.
4. To modify specific restore options, click the Options button. Any options that
you change are effective during the current session only.
5. Click Restore. The Restore Destination window appears. Enter the appropriate
information.
6. Click Restore. The Restore Task List window displays the processing status.
Related tasks:
“Backing up data using the GUI” on page 129
Examples for restoring data using the command line
You can use the examples in this topic when you need to restore objects from IBM
Spectrum Protectserver storage.
The following table shows how to use some restore commands to restore your
objects from IBM Spectrum Protect server storage.
Chapter 5. Restoring your data
187
Table 24. Command-line restore examples
Task
Command
Considerations
Restore the most recent backup
version of the c:\doc\h1.doc file,
even if the backup is inactive.
dsmc restore c:\doc\h1.doc -latest
If the file you are restoring no longer
resides on your workstation, and you
have run an incremental backup since
deleting the file, there is no active
backup of the file on the server. In
this case, use the latest option to
restore the most recent backup
version. IBM Spectrum Protect
restores the latest backup version,
whether it is active or inactive. See
“Latest” on page 452 for more
information.
Display a list of active and inactive
backup versions of files from which
you can select versions to restore.
dsmc restore c:\project\* -pick
-inactive
If you try to restore both an active
and inactive version of a file at the
same time, only the active version is
restored. See “Pick” on page 477 and
“Inactive” on page 424 for more
information.
Restore all files with a file extension
of .c from the c:\devel \projecta
directory.
dsmc restore c:\devel
\projecta\*.c
If you do not specify a destination,
the files are restored to their original
location.
Restore the c:\project\doc\h1.doc
file to its original directory.
dsmc restore c:\project\doc\h1.doc
If you do not specify a destination,
the files are restored to their original
location.
Restore the c:\project\doc\h1.doc
file under a new name and directory.
dsmc restore c:\project\doc\h1.doc
c:\project\newdoc\h2.doc
None
Restore the files in the e: drive and
all of its subdirectories.
dsmc restore e:\ -subdir=yes
You must use the subdir option to
restore directory attributes/
permissions. See “Subdir” on page
549 for more information about the
subdir option.
Restore all files in the c:\mydir
directory to their state as of 1:00 PM
on August 17, 2002.
dsmc restore -pitd=8/17/2002
-pitt=13:00:00 c:\mydir\
See “Pitdate” on page 478 and
“Pittime” on page 479 for more
information about the pitdate and
pittime options.
Restore the c:\doc\h2.doc file to its
original directory on the workstation,
named star.
dsmc restore c:\doc\h2.doc
\\star\c$\
For the purposes of this manual, the
workstation name is part of the file
name. Therefore, if you back up files
on one workstation and you want to
restore them to another workstation,
you must specify a destination. This
is true even if you are restoring to the
same physical workstation, but the
workstation has a new name.
To restore the file to “star” which has
been renamed “meteor”, enter:
dsmc restore \\star\c$\
doc\h2.doc \\meteor\c$\
You could also enter:
dsmc restore \\star\c$\
doc\h2.doc c:\
This example is valid because if the
workstation name is not included in
the specification, the local workstation
is assumed (“meteor”, in this case).
188
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 24. Command-line restore examples (continued)
Task
Command
Considerations
Restore a file that was originally
backed up from the diskette labeled
“workathome” in the a: drive, and
restore it to a diskette in the a: drive
labeled “extra”.
dsmc restore {workathome}\doc\
h2.doc a:\doc\h2.doc
If you are restoring a file to a disk
with a different label than the disk
from which the file was backed up,
you must use the file space name
(label) of the backup disk instead of
the drive letter.
Restore files specified in the
c:\filelist.txt file to the d:\dir
directory.
dsmc restore -filelist=c:\
filelist.txt d:\dir\
See “Filelist” on page 410 for more
information about restoring a list of
files.
Restore all members of the
virtfs\group1 group backup stored
on the IBM Spectrum Protect server.
dsmc restore group
{virtfs}\group1
See “Restore Group” on page 753 for
more information.
Related concepts:
Chapter 12, “Using commands,” on page 635
Related reference:
“Restore” on page 737
Examples: Restoring large amounts of data
If you need to restore a large number of files, you get faster performance using the
command line interface rather than the GUI interface. In addition, you improve
performance if you enter multiple restore commands at one time.
About this task
For example, to restore all the files in your c: file space, enter:
dsmc restore c:\* -subdir=yes -replace=all -tapeprompt=no
However, if you enter multiple commands for the root directories in your c: file
space, you can restore the files faster. For example, enter these commands:
dsmc restore c:\users\ -subdir=yes -replace=all -tapeprompt=no
dsmc restore c:\data1\ -subdir=yes -replace=all -tapeprompt=no
dsmc restore c:\data2\ -subdir=yes -replace=all -tapeprompt=no
Or, if you need to restore files for multiple drives, enter these commands:
dsmc restore c:\* -subdir=yes -replace=all -tapeprompt=no
dsmc restore d:\* -subdir=yes -replace=all -tapeprompt=no
dsmc restore e:\* -subdir=yes -replace=all -tapeprompt=no
You can also use the quiet option with the restore command to save processing
time. However, you will not receive informational messages for individual files.
Note: If you already have the appropriate values set for the subdir, replace,
tapeprompt, and quiet options in your client options file, it is not necessary to
include these options in the commands.
When you enter multiple commands to restore your files, you must specify a
unique part of the file space in each restore command. Do not use any overlapping
file specifications in the commands.
To display a list of the root directories in a file space, use the query backup
command. For example:
dsmc query backup -dirsonly -subdir=no c:\
Chapter 5. Restoring your data
189
As a general rule, you can enter two to four restore commands at one time. The
maximum number you can run at one time without degrading performance
depends on factors such as network utilization and how much memory you have.
For example, if \users and \data1 are on the same tape, the restore for \data1
must wait until the restore for \users is complete. However, if \data2 is on a
different tape, and there are at least two tape drives available, the restore for
\data2 can begin at the same time as the restore for \users.
The speed at which you can restore the files also depends upon how many tape
drives are available and whether your administrator is using collocation to keep
file spaces assigned to as few volumes as possible. If your administrator is using
collocation, the number of sequential access media mounts required for restore
operations is also reduced.
Standard query restore, no-query restore, and restartable restore
This topic describes the standard (or classic) restore method, the no-query restore
method, and the restartable restore method.
Standard query restore process:
The standard query restore process is also known as classic restore. This topic
explains how standard query restore works.
Here is how standard query restore works:
v The client queries the server for a list of files backed up for the client file space
you want to restore.
v The server sends a list of backed up files that match the restore criteria. If you
want to restore both active and inactive files, the server sends information about
all backed up files to the client.
v The list of files returned from the server is sorted in client memory to determine
the file restore order and to minimize tape mounts required to perform the
restore.
v The client tells the server to restore file data and directory objects.
v The directories and files you want to restore are sent from the server to the
client.
No-query restore process:
In the no-query restore process, a single restore request is sent to the server instead
of querying the server for each object to be restored.
1. The client tells the server that a no-query restore is going to be completed and
provides the server with details about file spaces, directories, and files.
2. The server uses a separate table to track entries which guide the restore.
3. The data to be restored is sent to the client. File and directory objects that are
stored on disk are sent immediately since sorting for such data is not required
before the object is restored.
4. You can use multiple sessions to restore the data. If the data is on multiple
tapes, there are multiple mount points available at the server. The combination
of using the resourceutilization option and MAXNUMMP allows multiple
sessions.
When you enter an unrestricted wildcard source file specification on the restore
command and do not specify any of the options: inactive, latest, pick, fromdate,
or todate, the client uses a no-query restore method for restoring files and
190
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
directories from the server. This method is called no-query restore because instead
of querying the server for each object to be restored, a single restore request is sent
to the server. In this case, the server returns the files and directories to the client
without further action by the client. The client merely accepts the data that comes
from the server and restores it to the destination named on the restore command.
Using the command-line client, an example of an unrestricted wildcard command
would be:
c:\mydocs\2004\*
An example of a restricted wildcard file specification would be:
c:\mydocs\2004\sales.*
Restartable restore process:
If the restore process stops because of a power outage or network failure, the
server records the point at which this occurred.
This record is known to the client as a restartable restore. It is possible to have more
than one restartable restore session. Use the query restore command or choose
restartable restores from the Actions menu to find out if your client has any
restartable restore sessions in the server database.
You must complete a restartable restore before attempting further backups of the
file system. If you attempt to repeat the restore that was interrupted or try to back
up the destination file space, the attempt fails because you did not complete the
original restore. You can restart the restore at the point of interruption by entering
the restart restore command, or you can delete the restartable restore using the
cancel restore command. If you restart the interrupted restore, it restarts with the
first transaction, which might consist of one or more files, not completely restored
when the interruption occurred. Because of this, you might receive some replace
prompts for files from the interrupted transaction which were already restored.
From the IBM Spectrum Protect GUI Restartable restores dialog box you can select
the interrupted restore and delete it, or you can choose to restart the restore. If you
restart the interrupted restore, it restarts with the first transaction, which might
consist of one or more files, not completely restored when the interruption
occurred. Because of this, you might receive some replace prompts for files from
the interrupted transaction which were already restored.
To
1.
2.
3.
perform restartable restores using the GUI, follow these steps:
Select Actions –> Restartable restores from the main panel.
Select the restartable restore session you want to complete.
Click the Restart button at the bottom of the panel.
Related reference:
“Resourceutilization” on page 504
“Restore” on page 737
Restoring Windows system state
The Microsoft Volume Shadowcopy Service (VSS) is supported on Windows
backup-archive clients. The client uses VSS to restore the system state. The system
state restore function is deprecated for online system state restore operations.
Chapter 5. Restoring your data
191
About this task
You can no longer restore the system state on a system that is still online. Instead,
use the ASR-based recovery method to restore the system state in offline Windows
PE mode. For more information, see the following IBM Spectrum Protect wiki
articles:
v Best Practices for Recovering Windows Server 2012 and Windows 8
v Best Practices for Recovering Windows Server 2012 R2 and Windows 8.1
If you try to restore the system state with the dsmc restore systemstate command,
from the backup-archive client GUI, or from the web client, the following message
is displayed:
ANS5189E Online SystemState restore has been deprecated. Please use offline
WinPE method for performing system state restore.
Related concepts:
“Recovering a computer when the Windows OS is not working” on page 193
Related reference:
“Restore Systemstate” on page 760
Restoring Automated System Recovery files
You can restore Automated System Recovery (ASR) files to recover the Windows
operating system volume configuration information and system state if a
catastrophic system or hardware failure occurs.
Before you begin
You must be a member of the Administrators or Backup Operators group to back
up and restore ASR files.
About this task
The backup-archive client restores ASR data when the backup-archive client
restores the Windows system state.
Procedure
To restore ASR files on Windows operating systems, use the restore systemstate
command.
Related concepts:
“Recovering a computer when the Windows OS is not working” on page 193
Restoring the operating system when the computer is working
If your computer is working, you can restore the operating system from backed up
files.
About this task
If Active Directory is installed, you must be in Active Directory restore mode.
When performing an operating system recovery including the system state, use the
following restore order. Do not restart the computer between each step, even
though you are prompted to do so.
192
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Procedure
1. Restore the system drive. For example: dsmc restore c:\* -sub=yes -rep=all.
2. Restore system state. For example: dsmc restore systemstate.
Recovering a computer when the Windows OS is not working
If the computer has a catastrophic hardware or software failure, you can recover a
Windows operating system with Automated System Recovery (ASR).
Related tasks:
“Restoring the operating system when the computer is working” on page 192
Creating a bootable WinPE CD
Before you can recover a Windows computer by using Automated System
Recovery (ASR), you must create a bootable Windows Preinstallation Environment
(WinPE) CD or DVD.
Procedure
For instructions that describe how to create a bootable WinPE CD or DVD, see the
following IBM Spectrum Protect Wiki articles:
v Best Practices for Recovering Windows Server 2012 and Windows 8
v Best Practices for Recovering Windows Server 2012 R2 and Windows 8.1
Restoring the Windows operating system with Automated
System Recovery
You can restore the Windows operating system of a computer with Automated
System Recovery (ASR).
Procedure
For instructions that describe how to restore a Windows system by using ASR, see
the following IBM Spectrum Protect Wiki articles:
v Best Practices for Recovering Windows Server 2012 and Windows 8
v Best Practices for Recovering Windows Server 2012 R2 and Windows 8.1
What to do next
You can now restore other volumes.
Related tasks:
“Creating a bootable WinPE CD”
“Creating a client options file for Automated System Recovery” on page 154
Related reference:
“Restore” on page 737
“Restore Systemstate” on page 760
Microsoft Dfs tree and file restore
To restore Dfs junctions and the data for each junction, restore the Dfs junction
metadata first and then restore each junction separately.
Chapter 5. Restoring your data
193
If the junction metadata is not restored, IBM Spectrum Protect creates a directory
under the Dfs root using the same name as that of the junction point and restores
the data in that directory.
Related tasks:
“Microsoft Dfs file protection methods” on page 182
Restoring an image
There are some items to consider before you begin restoring images on your
system.
Before you restore an image (offline or online), you must have administrative
authority on the system.
Here is a list of items to consider before you restore an image:
v Restoring the image of a volume restores the data to the same state that it was
in when you performed your last image backup. Be absolutely sure that you
need to restore an image, because it replaces your entire current file system or
raw volume with the image on the server.
v The image restore operation overwrites the volume label on the destination
volume with the one that existed on the source volume.
v Ensure that the volume to which you are restoring the image is at least as large
as the image that is being restored.
v The file system or volume you are restoring to does not have to be the same
type as the original. The volume does not even have to be formatted. The image
restore process creates the appropriately formatted file system for you.
v Ensure that the target volume of the restore is not in use. The client locks the
volume before starting the restore. The client unlocks the volume after the
restore completes. If the volume is in use when the client attempts to lock the
file system, the restore fails.
v You cannot restore an image to where the IBM Spectrum Protect client program
is installed.
v If you created an image of the system drive, you cannot restore the image to the
same location because the client cannot have an exclusive lock of the system
drive. Also, because of different system component configurations, the system
image might not be consistent across components (such as Active Directory).
Some of these components can be configured to use different volumes where
parts are installed on the system drive and others to non-system volumes.
v If you have run progressive incremental backups and image backups of your file
system, you can perform an incremental image restore of the file system. The
process restores individual files after the complete image is restored. The
individual files restored are those backed up after the original image. Optionally,
if files were deleted after the original backup, the incremental restore can delete
those files from the base image.
Deletion of files is performed correctly if the backup copy group of the IBM
Spectrum Protect server has enough versions for existing and deleted files.
Incremental backups and restores can be performed only on mounted file
systems, not on raw logical volumes.
v If for some reason a restored image is corrupted, you should run chkdsk to check
for and repair any bad sectors (unless the restored volume is RAW).
You can use the verifyimage option with the restore image command to specify
that you want to enable detection of bad sectors on the destination target
194
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
volume. If bad sectors are detected on the target volume, the client issues a
warning message on the console and in the error log.
If bad sectors present on the target volume, you can use the imagetofile option
with the restore image command to specify that you want to restore the source
image to a file. Later, you can use a data copy utility of your choice to transfer
the image from the file to a disk volume.
Related reference:
“Imagetofile” on page 423
“Verifyimage” on page 571
Restoring an image using the GUI
You can use the GUI to restore an image of your file system or raw logical volume.
About this task
Follow these steps to restore an image of your file system or raw logical volume:
Procedure
1. Click Restore from the main window. The Restore window appears.
2. Expand the directory tree.
3. Locate the object in the tree named Image and expand it. Click the selection
box next to the image you want to restore. You can obtain detailed information
about the object by highlighting the object and selecting View → File Details...
from the main window or click the View File details button.
4. (Optional) To perform an incremental image restore, click the Options button
to open the Restore Options window and select the Image plus incremental
directories and files option. If you want to delete inactive files from your local
file system, select the Delete inactive files from local check box. Click the OK
button.
5. Click Restore. The Restore Destination window appears. The image can be
restored to the volume with the drive letter or mount point from which it was
originally backed up. Alternatively, a different volume can be chosen for the
restore location.
6. Click the Restore button to begin the restore. The Task List window appears
showing the progress of the restore. The Restore Report window displays a
detailed status report.
Results
The following are some items to consider when you perform an image restore
using the GUI:
v You can select View → File Details from the main window or click the View File
details button to display the following statistics about file system images backed
up by the client:
– Image Size - This is the volume size which was backed up.
– Stored Size - This is the actual image size stored on the server. Because image
backup allows you to back up only used blocks in a file system, the stored
image size on the IBM Spectrum Protect server could be smaller than the
volume size. For online image backups, the stored image can be larger than
the file system based on the size of the cache files.
– File system type
– Backup date and time
Chapter 5. Restoring your data
195
– Management class assigned to image backup
– Whether the image backup is an active or inactive copy
v To modify specific restore options, click the Options button. Any options you
change are effective during the current session only.
v In the Restore Options window, you can choose to restore the image only or the
image and incremental directories files. If you choose Image Only, you restore
the image from your last image backup only. This is the default.
If you ran incremental-by-date image backup on a volume or image backups on
a volume with incrementals, you can choose the Image plus incremental
directories and files option. If you choose Image plus incremental directories
and files, you can also select Delete inactive files from local to delete the
inactive files that are restored to your local file system. If incremental-by-date
image backup was the only type of incremental backup you performed on the
file system, deletion of files will not occur.
Important: Be absolutely sure that you need to perform an incremental restore
because it replaces your entire file system with the image from the server and
then restore the files that you backed up using the incremental image backup
operation.
Restoring an image using the command line
Use the restore image command to restore an image using the IBM Spectrum
Protect command line client.
You can use the verifyimage option with the restore image command to specify
that you want to enable detection of bad sectors on the destination target volume.
If bad sectors are detected on the target volume, IBM Spectrum Protect issues a
warning message on the console and in the error log.
If bad sectors are present on the target volume, you can use the imagetofile
option with the restore image command to specify that you want to restore the
source image to a file. Later, you can use a data copy utility of your choice to
transfer the image from the file to a disk volume.
Related reference:
“Imagetofile” on page 423
“Verifyimage” on page 571
Restore data from a backup set
Your IBM Spectrum Protect administrator can generate a backup set, which is a
collection of your files that reside on the server, onto portable media created on a
device using a format that is compatible with the client device.
You can restore data from a backup set from the IBM Spectrum Protect server, or
when the backup set is locally available as a file or on a tape device.
You can restore backup sets from the following locations:
v From the IBM Spectrum Protect server
v From portable media on a device attached to your client workstation
v From a backup set file on your client workstation
Backup sets can provide you with instant archive and rapid recovery capability as
described in the following list.
196
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Instant archive
This capability allows an administrator to create an archive collection from
backup versions already stored on the server.
Rapid recovery with local backup sets
Typically, restores are performed from normal file backups that are stored
on the IBM Spectrum Protect server outside of backup sets. This restore
approach gives you the ability to restore the most recent backup version of
every file. It is possible that a backup set does not contain the most recent
backup version of your files.
In some cases restoring data from a backup set can be a better option than
restoring data from normal backup files on the IBM Spectrum Protect
server. Restoring from a backup set can be a better option for the following
reasons:
v A backup set restore can provide for a faster recovery because all of the
required files for restore are contained together within a smaller number
of storage volumes.
v A backup set provides a point-in-time collection of files. You can restore
to a point in time rather than restoring what is currently available from
a normal file-level restore from the server.
v You can perform an ASR restore using a backup set volume.
Restoring a backup set from the IBM Spectrum Protect server provides a
larger set of restore options than restoring from a local backup set.
However, restoring from a local backup set can be preferable in some
cases:
v It is possible that you need to restore your data when a network
connection to the IBM Spectrum Protect server is not available. This is
possible in a disaster recovery situation.
v The local restore may be faster than restoring over a network connection
to your IBM Spectrum Protect server.
A backup set can be restored from the IBM Spectrum Protect server while the
backup set volumes are available to the server, or they can be moved to the client
system for a local backup set restore. A backup set can be generated with or
without a table of contents (TOC), and can contain file data or image data.
The backup set can contain system state data.
Your ability to restore data from backup sets is restricted by the location of the
backup set and the type of data in the backup set. The command-line client can
restore some data that the GUI cannot restore, but the GUI can allow you to
browse and choose which objects to restore. Generally, backup sets from the server
with a TOC allow more options when restoring. However, local backup sets
provide options that are sometimes preferable to restoring from theIBM Spectrum
Protect server.
The restrictions for restoring data from backup sets using the GUI are summarized
in the following table. Each interior cell represents one combination of data type
and backup set location. For each situation, the cell indicates if you can use the
GUI to restore only the entire backup set, to select objects within the backup set, or
if you cannot use the GUI to restore the backup set.
Chapter 5. Restoring your data
197
Table 25. Backup set GUI restore restrictions
Backup set location
Local
(location=file
or
location=tape)
Data type in the
backup set
IBM Spectrum Protect Server
(TOC available)
IBM Spectrum
Protect Server
(TOC not
available)
file
Restore entire
backup set only.
Restore entire backup set, or
selected objects in the backup set.
Restore entire
backup set only.
image
Cannot be
restored.
Restore entire backup set, or
selected objects in the backup set.
Cannot be
restored.
system state
Restore entire
backup set only.
Restore entire backup set, or
selected objects in the backup set.
Restore entire
backup set only.
The restrictions for restoring data from backup sets using the command-line client
are summarized in the following table. Each interior cell represents one
combination of data type and backup set location. For each situation, the cell lists
the restore commands you can use. Except as noted, you can restore specific
objects within a backup set, as well as the entire backup set.
Table 26. Backup set command-line restore restrictions
Backup set location
Data type
in the
backup set
Local (location=file or
location=tape)
file
Commands:
Commands:
Commands:
restore
restore backupset
restore
restore backupset
restore backupset
Cannot be restored
Command:
Cannot be restored
image
IBM Spectrum Protect
Server (TOC available)
IBM Spectrum Protect
Server (TOC not
available)
restore image
system state Command:
restore backupset
Commands:
Command:
restore backupset
restore systemstate
restore backupset
Restriction: When restoring system state data using the restore backupset
command, you cannot specify individual objects. You can only restore the entire
system state.
Related reference:
“Localbackupset” on page 453
“Query Backupset” on page 711
“Query Image” on page 718
“Restore” on page 737
“Restore Backupset” on page 746
“Restore Image” on page 754
“Restore Systemstate” on page 760
Restore backup sets: considerations and restrictions
This topic lists some considerations and restrictions that you must be aware of
when restoring backup sets.
198
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Backup set restore considerations
Consider the following when restoring backup sets:
v If the object you want to restore was generated from a client node whose name
is different from your current node, specify the original node name with the
filespacename parameter on any of the restore commands.
v If you are unable to restore a backup set from portable media, check with your
IBM Spectrum Protect administrator to ensure that the portable media was
created on a device using a compatible format.
v If you use the restore backupset command on the initial command line with the
parameter -location=tape or -location=file, the client does not attempt to
contact the IBM Spectrum Protect server.
v When restoring a group from a backup set:
– The entire group, or all groups, in the virtual file space are restored. You
cannot restore a single group by specifying the group name, if there are
several groups in the same virtual file space. You cannot restore a part of a
group by specifying a file path.
– Specify a group by using the following values:
- Specify the virtual file space name with the filespacename parameter.
- Use the subdir option to include subdirectories.
v Limited support is provided for restoring backup sets from tape devices attached
to the client system. A native device driver provided by the device manufacturer
must always be used. The device driver provided by IBM to be used with the
IBM Spectrum Protect server cannot be used on the client system for restoring
local backup sets.
v To enable the client GUI to restore a backup set from a local device, without
requiring a server connection, use the localbackupset option.
Backup set restore restrictions
Be aware of the following restrictions when restoring backup sets:
v A backup set data that was backed up with the API cannot be restored or used.
v You cannot restore image data from a backup set using the restore backupset
command. You can restore image data from a backup set only with the restore
image command.
v You cannot restore image data from a local backup set (location=tape or
location=file). You can restore image data from a backup set only from the
IBM Spectrum Protect server.
Related reference:
“Localbackupset” on page 453
“Restore” on page 737
“Restore Image” on page 754
“Restore Backupset” on page 746
Backup set restore
IBM Spectrum Protect considers a backup set as one object containing the whole
file structure. You can restore the entire backup set or, in some cases, you can select
portions. The backup set media is self-describing and contains all the information
required to perform a successful restore.
Chapter 5. Restoring your data
199
If you are connected to the Tivoli Storage Manager Version 5.4 or later server, your
server administrator can create backup sets that are stacked. Stacked backup sets
can contain data from multiple client nodes, and they can contain different types of
data for a particular client node. The types of data can be file data or image data.
If you have upgraded from Tivoli Storage Manager Express®, some application
data is also supported.
Restriction: Image data and application data restore processing is only available
when restoring from the server. You cannot restore image data and application
data from a client local backup set restore.
When a backup set is stacked, you can only restore data for your own node. Data
for all other nodes is skipped. When restoring data from a stacked backup set on a
local device, you can only restore file level data for your own client node. It is
important that the nodename option is set to match the node name used to generate
the backup set for one of the nodes in the stack.
Important: Due to the portability of local backup sets, you must take additional
steps to secure your local backup sets on portable media. The backup set media
should be physically secured because the backup set can be restored locally
without authenticating with the server. Each user has access to all of the data on
the stacked backup set, which means that the user has access to data that they do
not own, by changing the node name or viewing the backup set in its raw format.
Encryption or physical protection of the media are the only methods to ensure that
the data is protected.
If you restore backup set data from the server, individual files, directories or entire
backup set data can be restored in a single operation from the GUI or the
command line. When you restore backup set data locally, the GUI can only display
and restore an entire backup set. The command line can be used to restore
individual files or directories stored in a backup set locally.
Restoring backup sets using the GUI
The client GUI can restore data from a backup set from the server, from a local file,
or from a local tape device. You can use the GUI to restore individual files from a
backup set from the IBM Spectrum Protect server with a TOC, but not from a local
backup set nor from a backup set from the server without a TOC.
About this task
Important: Before you begin a restore operation, be aware that backup sets can
contain data for multiple file spaces. If you specify a destination other than the
original location, data from all file spaces are restored to the location you specify.
To restore a backup set from the GUI, perform the following steps:
1. Click Restore from the GUI main window. The Restore window appears.
2. Locate the Backup Sets directory tree object and expand it by clicking the plus
sign (+) beside it.
v To restore the backup set from a local device, expand the Local object and
the Specify backup set location window is displayed. On the window, select
File name: or Tape name: from the list and enter the tape or file name
location. You can also click the Browse button to open a file selection
window and select a backup set.
200
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
v To restore data from backup set from the server, first expand the Server
object and then either Filelevel or Image, depending on the type of restore
requested.
3. Click the selection box next to the backup set or directory or file within the
backup set that you want to restore.
You can select files from within a backup set if that backup set is from the
server and has a table of contents.
4. Click Restore. The Restore Destination window appears. Enter the appropriate
information.
5. Click Restore. The Task List window displays the restore processing status.
Note:
v If the object you want to restore is part of a backup set generated on a node, and
the node name is changed on the server, any backup set objects that were
generated prior to the name change will not match the new node name. Ensure
that the node name is the same as the node for which the backup set was
generated.
v The client can be used to restore a backup set on an attached device with or
without a server connection. If the server connection fails, a prompt appears to
continue for purposes of local backup set restore. Also, thelocalbackupset
option can be used to tell the client not to attempt the connection to the server.
v Certain local devices such as tape devices (tape devices do not apply to Mac OS
X) require device drivers to be set up prior to performing a restore. See the
device manual for assistance with this task. You also need to know the device
address in order to perform the restore.
v The following features of a backup set restore from the server are not available
when restoring locally:
1. Image restore.
2. Restoring individual system state components.
3. The GUI display and restore of individual files and directories. The
command line can be used to restore an individual directory or file from a
local backup set.
4. Application data restore if the server was migrated from the Tivoli Storage
Manager Express product.
Backup set restores using the client command-line interface
The client command line interface can restore data from a backup set from the
server, from a local file, or from a local tape device. You can use the client
command line interface to restore individual files from local backup sets and from
backup sets without a TOC.
To restore a backup set from the client command line interface, use the query
backupset command to display what backup set data is available, then use restore
commands to restore the data.
You can use the following commands to restore data from backup sets:
v restore
v restore backupset
v restore image
v restore systemstate
Chapter 5. Restoring your data
201
Use the appropriate command for the location of the backup set and the data in
the backup set. For more information, see Table 26 on page 198.
Related reference:
“Query Backupset” on page 711
“Query Image” on page 718
“Restore” on page 737
“Restore Backupset” on page 746
“Restore Image” on page 754
“Restore Systemstate” on page 760
Restore Net Appliance CIFS shares
Restoring the share definition requires restoring the root directory of the share file
space, which under most circumstances can be done as follows: dsmc rest
\\NetAppFiler\CifsShareName\ -dirsonly.
The following output indicates that the root directory (and share definition has
been restored):
Restoring
0 \\NetAppFiler\CifsShareName\ [Done]
If the CIFS share definition is deleted on the Net Appliance file server, the client is
unable to directly restore the share definition because the share is no longer
accessible.
The share definition can be restored indirectly by creating a temporary local share
and restoring the share definition to the temporary share as follows:
md c:\tempdir net share tempshare=c:\tempdir
/remark:"Temporary Share for Restoring Deleted CIFS Share"
net use z: \\LocalMachineName\tempshare
dsmc res \\NetAppFiler\CifsShareName\ z:\ -dirsonly
This restores the original share definition (including permissions) on the file server.
Older versions of the IBM Spectrum Protect server might have a problem which
prevents restoring the root directory and the CIFS share definition. If this problem
occurs, it can be circumvented by using by one of the following methods:
1. Use the DISABLENQR testflag to restore the root directory as follows:
dsmc res \\NetAppFiler\CifsShareName\ -test=disablenqr
-dirsonly
2. Use the command line client -pick option with a restore command and select
the root directory:
dsmc res \\NetAppFiler\CifsShareName\
-dirsonly -pick
Related tasks:
“Backing up Net Appliance CIFS share definitions” on page 174
Restoring data from a VMware backup
You can use several methods for restoring data from backups to a VMware virtual
machine. The restore method depends on the type of backup and on the version of
the backup-archive client software that you use to run the restore.
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments: Data Protection for VMware.
202
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Full VM restore
Use the restore vm command to restore an entire virtual machine from a
full VM backup. When you restore a full VM backup, the restored image
replaces the virtual machine or a new virtual machine is created. In a full
VM restore, you restore all of the VMware files and the system state on
Windows systems. If you have access to IBM Spectrum Protect recovery
agent, you can restore individual files.
Depending on the version of the backup-archive client that is running on
the VMware client, use the appropriate method to restore a full VM
backup:
Versions of the backup-archive earlier than 6.2.2:
Restore the full VM backup by using VMware Consolidated
Backup. For more information, see the following topic:
“Restoring full VM backups that were created with VMware
Consolidated Backup” on page 216
Versions of the backup-archive client at 6.2.2 or later:
Restore the full VM backup by using the vStorage API. The IBM
Spectrum Protect V6.2.2 or later client can restore full VMware
backups that were created with versions of the client that is earlier
than V6.2.2. For more information, see the following topic:
“Restoring full VM backups”
File-level restore
Use the restore command to restore individual files from a file-level VM
backup. Use this method when you cannot practically restore an entire
VMware image. File-level backups were created with the version 7.1 or
earlier backup-archive clients.
The following restrictions apply to file-level restores:
v You can use the file-level restore method only if a file-level backup of
the virtual machine exists.
v You cannot restore an entire virtual machine from file-level backups
because the restore command does not re-create Windows system states.
v You cannot use this method to restore individual files from a full VM
backup of a virtual machine.
Depending on the configuration of the virtual machine where you restore
the files, use the appropriate method to restore files from a file-level
backup:
The backup-archive client is not installed on the VM:
Restore the files from the vStorage backup server that backed up
the virtual machine.
The backup-archive client is installed on the VM:
Restore the file from the backup-archive client that is installed on
the virtual machine.
For more information, see the following topic:
“Scenario: Restoring file-level VM backups” on page 213
Restoring full VM backups
You can restore a full VMware backup to re-create all of the files for a VMware
virtual machine (VM) directly to the VMware server. This method replaces the
deprecated method of restoring backups that were created by using the VMware
Chapter 5. Restoring your data
203
Consolidated Backup (VCB) tools. This restore method does not require you to use
the VMware converter tool before you restore the backup to the VMware server.
You cannot use this restore method to restore individual files from a full VM
backup.
Before you begin
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments: Data Protection for VMware.
To restore a full VMware backup that was created by using VCB tools in IBM
Spectrum Protect Version 6.2.0 or earlier, see the topic "Restoring full VM backups
that were created with VMware Consolidated Backup".
Procedure
1. Depending on the target location for the restore, complete the appropriate step:
v If the restore of the full VM backup is going to overwrite the existing
VMware virtual machine, delete the existing virtual machine.
v If you restore the full VM backup to a new virtual machine, you do not need
to delete the existing virtual machine. You can delete the existing virtual
machine if you prefer, otherwise proceed to the next step.
2. Query the virtual machine for VMware backups, by completing the following
steps:
a. From the off-host backup server, run the following command:
dsmc q vm *
The command lists the available backups, for example:
#
Backup Date
Mgmt Class
---------------------1
12/03/2009 03:05:03
DEFAULT
2
09/02/2010 10:45:09
DEFAULT
3
09/02/2010 09:34:40
DEFAULT
4
09/02/2010 10:10:10
DEFAULT
5
12/04/2009 20:39:35
DEFAULT
6
09/02/2010 11:15:18
DEFAULT
7
09/02/2010 02:52:44
DEFAULT
8
08/05/2010 04:28:03
DEFAULT
9
08/05/2010 05:20:27
DEFAULT
10
08/12/2010 04:06:13
DEFAULT
11
09/02/2010 00:47:01
DEFAULT
12
09/02/2010 01:59:02
DEFAULT
13
09/02/2010 05:20:42
DEFAULT
ANS1900I Return code is 0.
ANS1901I Highest return code was 0.
Type A/I Virtual Machine
---- --- --------------VSTORFULL A vm_guest1
VSTORFULL A vm_guest11
VSTORFULL A vm_guest12
VSTORFULL A vm_guest13
VSTORFULL A vm_guest14
VSTORFULL A vm_guest15
VSTORFULL A vm_guest16
VSTORFULL A vm_guest17
VSTORFULL A vm_guest18
VSTORFULL A vm_guest19
VSTORFULL A vm_guest7
VSTORFULL A vm_guest8
VSTORFULL A vm_guest9
b. From the results that are returned by the query command, identify a virtual
machine to restore.
3. Restore the full VMware backup, by using the restore vm command. To restore
the backup to a virtual machine with a new name, use the -vmname option. For
example, in the following command the virtual machine is restored and a new
name is specified for the restored virtual machine:
dsmc restore vm my_old_vmname -vmname=new_vm_name -datastore=myPath
4. When the restore is complete, the virtual machine is powered off. Start the
virtual machine from the VMware vCenter.
204
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
What to do next
|
|
|
If you are restoring application protection backups, see “Shadow copy
considerations for restoring an application protection backup from the data
mover.”
Related tasks:
“Restoring full VM backups that were created with VMware Consolidated Backup”
on page 216
Related reference:
“Query VM” on page 729
“Restore VM” on page 760
“INCLUDE.VMSNAPSHOTATTEMPTS” on page 437
Shadow copy considerations for restoring an application
protection backup from the data mover
|
|
|
For Windows VMware virtual machines (VMs), if you attempt to restore an
application protection backup from the data mover, be aware of shadow copy
restrictions when you restore the application protection backup.
The shadow storage might run out of space
If you attempt to run a full VM restore of an application protection backup that
was created with 2 or more snapshot attempts, the system provider snapshot is
present on the restored VM. As the application writes to the disk, the shadow
storage space grows until it runs out of disk space.
In general, if application protection was used during a backup, use only
application protection restore. When you restore the application, the volume is
automatically reverted. However, if you must restore the full VM, you must either
revert or delete the shadow copy.
After you restore the entire VM, verify that the restore was successful, and the data
is not corrupted. If the data is not corrupted, delete the shadow copy. If the data is
corrupted, revert the shadow copy to restore data integrity.
You can determine which shadow copy to delete or revert by looking for the
dsmShadowCopyID.txt file in the root directory of each restored volume. This file
contains the snapshot IDs of the shadow copies that were created during the
snapshot attempts. You can use the diskshadow command delete shadows to
delete these IDs, or the revert command to revert the shadow copy. After the
delete or revert is completed, you can also delete the dsmShadowCopyID.txt file.
|
|
|
Important: In order for the revert operation to succeed, the application database,
such as the Microsoft SQL Server database or Microsoft Exchange Server database,
must be on a non-boot drive (any drive other than the boot drive).
|
|
The shadow copy must be available on the restored volume during an
application protection restore
|
|
|
|
In some cases, an application protection backup operation might use the Volume
Shadow Copy Service (VSS) to create an application-consistent shadow copy before
you start a VM backup. All changes that are made after the creation time of the
shadow copy are saved to the shadow storage.
Chapter 5. Restoring your data
205
|
|
|
|
A database restore might fail if the shadow copy is not available during an
application restore. The shadow copy is used at the time of restore to revert the
restored volume to an application-consistent state. If the shadow copy not
available, the restored data will be in an inconsistent state.
|
The following situations can cause the shadow copy to be unavailable:
|
|
|
|
|
v Typically, the shadow storage is part of a volume. However, sometimes the
shadow storage space is configured to be on a different volume either by default
or manually. In this case, the database restore might fail because the shadow
copy that was created during the VM backup operation is not available at
restore time.
|
|
v The shadow storage is not available because the volume with the shadow
storage was excluded at backup time.
|
The following workarounds are available for this issue:
|
|
|
|
|
v Before you run a VM backup, add the shadow copy storage association for each
volume that is available on the guest VM by using the vssadmin add
shadowstorage command. For example, to set the shadow storage location for
volume E: on volume E:, issue following command:
|
|
|
Important: The vssadmin add shadowstorage command might fail if the VM
has existing VSS snapshots. You must delete the VSS snapshots by using the
same application that created them.
|
|
|
|
|
|
For example, if a VSS backup of an Exchange database with LOCAL backup
destination was created by IBM Spectrum Protect for Mail: Data Protection for
Microsoft Exchange Server, use the Data Protection for Microsoft Exchange
Server application to delete the VSS backup. If an unidentified VSS snapshot
exists, use the Windows diskshadow command delete shadows to delete the
VSS snapshot.
|
|
Also, ensure that the volume that holds the shadow storage is not excluded from
backup operations.
vssadmin add shadowstorage /for=E: /on=E: /maxsize=unbounded
v Manually revert snapshots to achieve application-consistency of the database
files:
|
|
|
|
1. Mount all disks in the VM backup by using IBM Spectrum Protect recovery
agent.
|
|
|
|
|
|
2. Start the Windows diskshadow command in interactive mode.
3. In the interactive diskshadow mode, issue the following command:
|
|
5. Open the ShadowCopyID.txt file and identity the GUID of the volume where
the database files are located.
|
|
6. In the interactive diskshadow mode, issue the following command:
list shadows all
4. In the root directory of each mounted drive, locate the ShadowCopyID.txt file.
This file contains the globally unique identifier (GUID) of the VSS shadow
copy that is needed in the volume revert operation.
revert GUID
where GUID is the snapshot GUID that was identified in the
ShadowCopyID.txt file.
|
|
In order for the revert operation to succeed, the application database must be on
a non-boot drive.
|
|
206
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
|
Recovering from an application protect restore failure of a guest VM
with Microsoft Exchange Server
|
|
|
Restoring a guest VM from an application protection backup can fail if the guest
VM contains disks of different sizes and the original application protection
snapshot of the VM took more than 10 seconds to complete.
|
|
|
This situation applies to application protection restore operations that fail when the
/RECOVer=APPLYALLlogs AND /MOUNTDAtabases=Yes option is specified with the
database restore command.
|
|
|
For example, a restore operation failed when the following Data Protection for
Microsoft Exchange Server command is run:
|
|
|
|
To resolve this problem, you must enable disk shadow copies for each disk in the
guest VM and rerun the application protection backup. To avoid this problem in
the future, enable disk shadow copies of each disk in the guest VM before you run
application protection backups.
|
To recover from the restore failure, complete the following steps:
|
|
|
|
|
1. Ensure that the guest VM snapshot takes less than 10 seconds to complete.
2. If the snapshot takes longer than 10 seconds to complete, and the source disks
on the guest VM are of different sizes, enable the shadow copies on each disk
in the guest VM.
3. Run a guest VM backup on data mover machine.
|
4. Restore the databases again.
|
|
|
|
Important: If this problem occurs, the VM backup cannot be used to perform an
application-consistent restore. You can perform only a crash-consistent restore. You
must correct the configuration and run a new backup in order to have an
application-consistent restore.
tdpexcc restore DB1 FULL /mountdatabases=Yes /recover=applyalllogs
Scenarios for running full VM instant access and full VM
instant restore from the backup-archive client command line
Full VM instant access and full VM instant restore operations require a license for
IBM Spectrum Protect for Virtual Environments. You can perform either of these
operations from the backup-archive client command line. Instant access and instant
restore operations and options are supported only for VMware virtual machines
that are hosted on VMware ESXi 5.1 servers, or later versions.
The following scenarios demonstrate the full VM instant access or full VM instant
restore operations that you might perform. Before you can complete the operations
that are described in the following text, you must configure at least one data
mover node on the vStorage backup server so it can protect the virtual machines
by starting off host backup and restore operations. The steps for setting up the
data mover nodes are described in Setting up the data mover nodes in a vSphere
environment.
Chapter 5. Restoring your data
207
Scenario: You want to perform a full VM instant access to verify
the integrity of a backed up image of a VMware virtual machine,
without actually restoring the virtual machine or disks to the
ESXi host
The purpose of this goal is to verify that a backed up virtual machine image can
be used to successfully restore a system if the virtual machine is deleted or its
disks and data are corrupted or otherwise unusable.
For this scenario, assume that an ESX server has a virtual machine named Orion
running on it. You want to verify that the backed up image that is stored by the
IBM Spectrum Protect server can be used to restore this virtual machine if the
current virtual machine fails.
You perform a VM instant access operation, you use the restore vm command with
inventory location options specified to identify the location for the restored virtual
machine. All inventory location options, such as vmname, datacenter, host, and
datastore can be used in combination with the instant access option
(-VMRESToretype=INSTANTAccess) to specify the location for the restored (instant
access) virtual machine.
Because the Orion virtual machine does exist in the inventory and is running, you
must provide a new name for a temporary virtual machine by adding the new
name to the vmname option. You must also add the –VMRESToretype=INSTANTAccess
option to the command line to indicate that this is an instant access restore
operation.
Entering the following command prepares a virtual machine named “Orion_verify”
so it is available for instant access. You can use this virtual machine to verify that
the backed-up image can be restored.
dsmc restore vm Orion -vmname=Orion_verify –Host=esxi.example.com
–datacenter=mydataCenter –VMRESToretype=INSTANTAccess –VMAUTOSTARTvm=YES
The –VMAUTOSTARTvm=YES option indicates that the virtual machine is started when
it is restored. By default, the new virtual machine is not automatically started. With
this default setting, you can reconfigure the virtual machine before you start it.
You can also list the versions of a virtual machine that were backed up by using
the inactive or pick options or the pittime or pitdate options to select an inactive
or active backup, from a particular date or time. For example, to display a list of
backed up versions of the Orion virtual machine, by using the following
command:
dsmc restore vm Orion -pick
For a virtual machine that is restored by using the –VMRESToretype=INSTANTAccess
option, temporary data that is created by this virtual machine is stored in a
VMware snapshot.
After you restore the temporary virtual machine (Orion_verify), run verification
tools on it to verify the integrity of the disks and data. Use a utility such as
chkdsk, or a utility or application of your choosing, to verify the virtual disks and
data. If the temporary virtual machine passes the integrity checks, you can remove
the temporary resources that were created to support the instant access restore
operation.
208
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Scenario: You want to determine whether any temporary (instant
access) virtual machines exist, so you can run a clean-up
operation to free the resources associated with them
Use the query vm command with one of the following options that you specify on
the command line:
-VMRESToretype=INSTANTAccess
-VMRESToretype=ALLtype
Where:
-VMRESToretype=INSTANTAccess
Displays all temporary virtual machines that are running in instant access
mode, created by a restore vm -VMRESToretype=INSTANTAccess operation.
-VMRESToretype=ALLtype
Displays all virtual machines with active instant access or instant restore
sessions that were started by a restore vm command that uses either the
-VMRESToretype=INSTANTAccess or VMRESToretype=-INSTANTRestore options.
The following examples show the syntax for the various options:
query vm * -VMREST=INSTANTA
query vm * -VMREST=ALL
You can add a –Detail option to each of the query vm commands shown to
display more information about each of the temporary virtual machines.
query vm vmname –VMREST=INSTANTA –Detail
To remove the resources that were created for a temporary virtual machine named
“Orion_verify”, run the following command:
dsmc restore vm Orion –vmname=Orion_verify –VMRESToretype=VMCLeanup
The –VMRESToretype=VMCLeanup option deletes the temporary virtual machine from
the ESXi host, unmounts any iSCIS mounts that were mounted, and clears the
iSCSI device list from the ESX host. All temporary data for the temporary virtual
machine is deleted from the VMware snapshot.
Scenario: You want to start an instant restore operation to
restore a failed virtual machine to an ESX host, from a backup
image created by IBM Spectrum Protect
The advantage of a full VM instant restore, as opposed to a classic full VM restore,
is that an instant restore operation makes the virtual machine ready for immediate
use, as soon as it is started. You do not have to wait for all data to be restored
before you can use the virtual machine. During an instant restore operation, the
virtual machine uses iSCSI disks until its local disks are fully restored. When the
local disks are restored, the virtual machine switches I/O from the iSCSI disks to
the local disks, without noticeable interruption of service.
Restore a virtual machine named Orion by using the following command:
dsmc restore vm Orion –Host=esxi.example.com –datacenter=mydatacenter
–VMTEMPDAtastore=temp_datastore –VMRESToretype=INSTANTRestore
–datastore=mydatastore
Chapter 5. Restoring your data
209
This command specifies the name of the virtual machine to restore, the host and
data center to restore it to, and the restore type (-VMRESToretype=INSTANTRestore).
The VMTEMPDAtastore option is a mandatory parameter for instant restore
operations.
The temporary datastore is used by vMotion to store the configuration of the
restored virtual machine during the instant restore process. The name that you
specify must be unique. It cannot match the name of any of the original datastores
that were used by the virtual machine when it was backed up, and it cannot be the
same as the name specified on the optional –datastore option. If the –datastore
option is omitted, the virtual machine files are restored to the datastores that they
used when the virtual machine was backed up.
By default, virtual machines that are instantly restored are provisioned with thick
disks. You can change this behavior and provision thin disks by adding the
–VMDISKProvision=THIN option to the command line, or in the client options file.
Important: For instant restore operations, ensure that both the temporary datastore
that you specify with the vmtempdatastore option and the VMware datastore that
is specified by the datastore option on the restore VM command have enough
free storage to save the virtual machine that you are restoring, and the snapshot
file that contains changes that were made to the data. If you are restoring a virtual
machine and you specify thin or thick provisioning (-vmdiskprovision=thin or
-vmdiskprovision=thick), the datastore that you restore the VM to must have
enough free space to accommodate the total capacity of the VM disk, and not just
the amount of disk that is used. For example, if a VM has 300 GB total capacity for
its disk, you cannot restore that VM to a datastore that has less than 300 GB
available, even if only a portion of the total capacity is being used.
Full VM instant restore cleanup and repair scenarios
When an instant restore operation fails after the VM is powered on, manual
cleanup and repair tasks are required.
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments: Data Protection for VMware.
An instant restore operation that fails with storage vMotion running creates either
of the following situations:
v The instant restore operation generates an error message.
v The instant restore operation suspends indefinitely and the VM is not
responsive.
To determine the cause of the problem, perform a detailed query of the VM by
using the following command:
dsmc q vm * -vmrestoretype=instantrestore -detail
In the output that is produced by this command, for each VM in the output, look
for the line that contains Action Needed. Use the following Action Needed
paragraphs to recover from failed instant restore operation, depending on the
Action Needed status.
Action Needed: Cleanup
In the output of the query vm * -vmrestoretype=instantrestore -detail
command, verify that the storage vMotion status is successful (vMotion Status:
210
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Successful) and that all VM disks are physical disks (Disk Type: Physical). This
status confirms that the VM was restored and cleanup of orphaned components,
such as iSCSI mounts, is needed.
This type of failure occurs as a result of either of the following situations:
v The instant restore failed and Storage vMotion is running. VMware vSphere
continues the vMotion process.
v Storage vMotion finished successfully, but the automatic cleanup of the iSCSI
mounts fails.
To clean up any orphaned components, run the restore vm command with the
-VMRESToretype=VMCLeanup parameter. For example:
dsmc restore vm original_vmname -vmname=new_vm_name -VMRESToretype=VMCLeanup
Action Needed: Repair
In the output of the query vm * -vmrestoretype=instantrestore -detail
command, verify that the iSCSI device that is attached to the VM is dead (status is
Disk Path: Dead).
This type of failure occurs as a result of one of the following three situations:
v The VM that is used as a data mover or the physical data mover machine failed.
v A network failure occurred between the data mover and the ESX host or the
data mover and the IBM Spectrum Protect server.
v The Data Protection for VMware Recovery Agent Service failed.
The iSCSI device must be returned to an active state before any other instant
operation is attempted.
To attempt to recover from a data mover failure, complete the following steps:
1. Investigate that cause of the failure and restart the data mover machine if it
does not start automatically. This action starts an automatic recovery of the
mounted iSCSI disks.
2. In the output of the query vm * -vmrestoretype=instantrestore -detail
command, verify that the VM disks are active (Disk Path: Active). This status
means that the VM was restored and is available for use.
3. Restart storage vMotion in the vSphere client and monitor its progress in the
vSphere client status bar.
4. If storage vMotion processing completed successfully, run the restore vm
command with the -vmrestoretype=VMCLeanup parameter to clean up the iSCSI
disks. For example:
dsmc restore vm original_vmname -vmname=new_vm_name -VMRESToretype=VMCLeanup
To attempt recovery after a network failure, complete the following steps:
1. Repair the network issue so that communication between the data mover and
the ESX host, and the data mover and the IBM Spectrum Protect server
resumes.
2. In the output of the query vm * -vmrestoretype=instantrestore -detail
command, verify that the VM disks are active (Disk Path: Active). This status
means that the VM was restored and is available for use.
3. If the network failure did not cause storage vMotion to time out, no action is
required.
Chapter 5. Restoring your data
211
4. If the network failure caused storage vMotion to time out, and the error
message indicates that the source disk is not responding, restart storage
vMotion in the vSphere client. When storage vMotion processing completes,
run the restore vm command with the -vmrestoretype=VMCLeanup parameter to
clean up the iSCSI disks. For example:
dsmc restore vm original_vmname -vmname=new_vm_name -VMRESToretype=VMCLeanup
To attempt recovery after a Data Protection for VMware Recovery Agent service
failure, complete the following steps:
1. Investigate that cause of the failure and restart the Data Protection for VMware
Recovery Agent service if it does not start automatically. This action starts an
automatic recovery of the mounted iSCSI disks.
2. In the output of the query vm * -vmrestoretype=instantrestore -detail
command, verify that the VM disks are active (Disk Path: Active). This status
means that the VM was restored and is available for use.
3. If the Data Protection for VMware Recovery Agent service failure did not cause
storage vMotion to time out, no action is required.
4. If the Data Protection for VMware Recovery Agent service failure caused
storage vMotion to time out, and the error message indicates that the source
disk as not responding, restart storage vMotion in the vSphere client. When
storage vMotion processing completes, run the restore vm command with the
-vmrestoretype=VMCLeanup parameter to clean up the iSCSI disks. For example:
dsmc restore vm original_vmname -vmname=new_vm_name -VMRESToretype=VMCLeanup
Full cleanup
If you are not able to recover from a failure and want to remove the VM and its
components, run the restore vm with the -vmrestoretype=VMFULLCLeanup
parameter. For example:
dsmc restore vm original_vmname -vmname=new_vm_name -VMRESToretype=VMFULLCLeanup
A VMFULLCLeanup operation forces removal of the VM and all of its components,
regardless of the state of the virtual machine. Do not start a full clean up operation
while vMotion is still migrating a virtual machine.
Recovering from non-standard error conditions
Problems with iSCSI devices can prevent you from performing an instant access or
instant restore operation.
About this task
When an ESX server cannot access a datastore on an iSCSI disk, a VMware
message is issued to indicate that a "permanent device loss" error occurred. You
should be offered an option to either cancel or retry the iSCSI connection attempt.
Choose the option to try the operation again to see whether the error is transient
and if recovery is possible. If the retry is not successful, try the following
troubleshooting steps. If they are successful, then try the instant restore or instant
access operation again.
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments: Data Protection for VMware.
212
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Procedure
1. Examine the ESX server Task and Event log for an All Paths Down (APD) error.
It can take time for this error to display in the logs, but it must be present
before you continue to the next steps. If you do not wait for the error before
you attempt more troubleshooting, you might bring the ESX server down.
2. Power off the virtual machine.
3. Rescan the HBA. Rescanning the HBA on the ESX server might reactivate the
failed device. If VMware kernel locks prevent you from rescanning the HBA,
perform the following steps:
a. In the vCenter interface, select the ESX host.
b. Click Configuration.
c. Right click iSCSI Software Adapter and select Properties.
d. Click Static Discovery.
e. Delete any static addresses and click Close.
f. Rescan the HBA.
Scenario: Restoring file-level VM backups
On Microsoft Windows systems, you can restore specific files from a file-level
backup of a VMware virtual machine. A file-level restore is useful for restoring
individual files that might be lost or damaged. You cannot use this method to
restore files that were part of a full VM backup. Before you can restore files from
the off-host backup server onto the VMware virtual machine, the off-host backup
server must be configured as a proxy server.
Before you begin
File-level backups were created with the version 7.1 or earlier backup-archive
clients.
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments: Data Protection for VMware.
Important: Use the restore command to run a file-level restore. Do not use the
restore vm command.
The following assumptions are made for this scenario of a file-level restore:
v The goal is to restore files that were previously backed up to the IBM Spectrum
Protect server.
v The files were previously backed up on a VMware virtual machine called Orion,
with the host name orion. For this scenario, the Orion VM fails and some of the
files must be restored.
v Files on Orion were backed up to file spaces that match the lowercase form of
the computer host name. The file space names are expressed in Universal
Naming Convention (UNC) format, for example:
– Files that are backed up from the C: drive on Orion, are stored in the
\\orion\c$ file space.
– If Orion has a D: drive, files that are backed up from that drive are stored in
the \\orion\d$ file space.
Chapter 5. Restoring your data
213
v In this scenario, the files are restored from the C:\mydocs directory that was on
Orion to the C:\restore_temp directory on a different computer. The computer
that you restore file to can be another VMware virtual machine or a physical
computer.
v The computer that runs the restore has a different host name and node name
than the virtual machine Orion. During the restore, you must specify the source
file specification in the complete UNC format and use one of the following
parameters to access Orion:
-virtualnodename
Specifies the client node for which you are restoring a backup. Use this
parameter if you are restoring files to the computer where you are
currently logged on.
-asnodename
Specifies the client node for which you are restoring a backup. Use this
parameter if you are restoring files to a computer for which you have
proxy authority.
Complete the following steps to run a file-level restore for the computer Orion:
Procedure
1. Query the IBM Spectrum Protect server to determine the file spaces that are
registered for Orion:
dsmc query filespace -virtualnode=orion
2. Restore files for the Orion file space, by running one of the following
commands:
Restore files to the computer where you are currently logged on:
Assume that you are currently logged on to the computer called Orion.
Run one of the following commands:
a. If you know the password for the node that you are restoring, use
the -virtualnodename option in the restore command. For example,
run the following command to restore the files to Orion:
dsmc restore \\orion\c$\mydocs\ c:\restore_temp\ -sub=yes
-virtualnodename=orion
b. If you have proxy authority, you can restore files on behalf of the
target node. Proxy authority must be granted from the agent node,
in other words the node of the computer that the restore is run
from. You must know the password for the agent node so that you
can access the target node. For example, run the following
command to restore the files to Orion:
dsmc restore \\orion\c$\mydocs\ c:\restore_temp\ -sub=yes
-asnodename=orion
Table 27. Components for the restore command when you restore files to the same computer
214
Command component
Description
\\orion\c$\mydocs\
Source file specification on the IBM Spectrum
Protect server. This location contains the
backed up files that you are restoring. The
files are backed up for the orion VM, so the
file specification must be in UNC format.
c:\restore_temp\
Destination file specification on the computer
where you are currently logged on. The files
are restored to this location.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 27. Components for the restore command when you restore files to the same
computer (continued)
Command component
Description
-sub=yes
Specifies that all subdirectories in the source
file specification are included when you run
the restore operation.
-virtualnodename=orion
Notifies the IBM Spectrum Protect server that
the backup is running from the node orion.
-asnodename=orion
Notifies the IBM Spectrum Protect server that
the backup is running from the node orion.
Restore files to a different computer:
To restore the files from the IBM Spectrum Protect server to a computer
other than the one you are logged on to, run the following command.
You can use this command only if you are logged in with authority to
write to the remote computer as controlled by the operating system.
dsmc restore \\orion\c$\mydocs\ \\orion\c$\restore_temp\ -sub=yes
-virtualnode=orion
Table 28. Components for the restore command when you restore files to a different
computer
Command component
Description
\\orion\c$mydocs\
Identifies the source file specification on the
IBM Spectrum Protect server. This location
contains the backed up files that you are
restoring. The files are backed up for the
orion VM, so the file specification must be in
UNC format.
\\orion\c$\restore_temp\
Identifies the destination file specification on
a computer other than the computer where
you are logged on. The You are restoring the
files to the orion VM over the network, by
using a Microsoft feature that identifies
network locations in UNC notation.
-sub=yes
Specifies that all subdirectories in the source
file specification are included when you run
the restore operation.
-virtualnodename=orion
Notifies the IBM Spectrum Protect server that
the backup is running from the node orion.
Related concepts:
“Restoring data from a VMware backup” on page 202
Related tasks:
“Restoring full VM backups that were created with VMware Consolidated Backup”
on page 216
“Restoring full VM backups” on page 203
Related reference:
“Query Filespace” on page 714
“Restore” on page 737
Chapter 5. Restoring your data
215
Restoring full VM backups that were created with VMware
Consolidated Backup
You can restore a full VMware backup to re-create all of the files for a VMware
virtual machine (VM). Complete these steps to restore full VM backups that were
created by using VMware Consolidated Backup (VCB) running on IBM Spectrum
Protect Version 6.2.0 or earlier.
Before you begin
To restore a full VMware backup that was created by using IBM Spectrum Protect
Version 6.2.2 or later, see the topic "Restoring full VM backups".
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments: Data Protection for VMware.
Procedure
1. Depending on the target location for the restore, complete the appropriate step:
v If the restore of the full VM backup is going to overwrite the existing
VMware virtual machine, delete the existing virtual machine.
v If you restore the full VM backup to a new virtual machine, you do not need
to delete the existing virtual machine. You can delete the existing virtual
machine, otherwise proceed to the next step.
2. Query the virtual machine for full VMware backups, by completing the
following steps:
a. From the off-host backup server, run the following command:
dsmc q vm *
The command lists the available backups, for example:
#
Backup Date
Mgmt Class
---------------------1
12/03/2009 03:05:03
DEFAULT
2
09/02/2010 10:45:09
DEFAULT
3
09/02/2010 09:34:40
DEFAULT
4
09/02/2010 10:10:10
DEFAULT
5
12/04/2009 20:39:35
DEFAULT
6
09/02/2010 11:15:18
DEFAULT
7
09/02/2010 02:52:44
DEFAULT
8
08/05/2010 04:28:03
DEFAULT
9
08/05/2010 05:20:27
DEFAULT
10
08/12/2010 04:06:13
DEFAULT
11
09/02/2010 00:47:01
DEFAULT
12
09/02/2010 01:59:02
DEFAULT
13
09/02/2010 05:20:42
DEFAULT
ANS1900I Return code is 0.
ANS1901I Highest return code was 0.
Type
A/I Virtual Machine
---- --- --------------VMFULL A vm_guest1
VMFULL A vm_guest11
VMFULL A vm_guest12
VMFULL A vm_guest13
VMFULL A vm_guest14
VMFULL A vm_guest15
VMFULL A vm_guest16
VMFULL A vm_guest17
VMFULL A vm_guest18
VMFULL A vm_guest19
VMFULL A vm_guest7
VMFULL A vm_guest8
VMFULL A vm_guest9
b. From the results that are returned by the query command, identify a virtual
machine to restore.
3. Restore the full VMware backup, by using the restore vm command. To restore
a virtual machine from a specific point in time, include the -pitdate and
-pittime options, for example:
dsmc restore vm my_vm_name destination -pitdate=date -pittime=hh:mm:ss
Where:
216
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
my_vm_name
Name of the virtual machine that you are restoring.
destination
Directory location for the restored vmdk file.
-pitdate
Date that the backup was created.
-pittime
Time that the backup was created.
4. When the restore is completed, the following message is returned. Enter Y.
Virtual Infrastructure Client or VMware Converter tool
can be used to redefine virtual machine to the VMware Virtual Center Inventory.
Would you like to launch VMware Converter now? (Yes (Y)/No (N))
Tip: If you enter N, the command-line returns without opening the VMware
Converter. However, you must convert the image before the image can be
restored.
5. To convert the restored VCB image into a virtual machine on a VMware server
by using the VMware vCenter Converter tool, complete following steps:
a. From the Windows Start menu, open the Converter tool.
b. From the Converter tool, click Convert Machine.
c. In the Virtual machine file field, enter the location of the restored .vmx file.
Tip: The .vmx file is restored to the directory specified by the vmbackdir
option of the restore vm command.
d. Follow the remaining steps in the wizard to convert the full VM backup.
6. When the restore is complete, the virtual machine is powered off. Start the
virtual machine from the VMware vCenter.
Related tasks:
“Restoring full VM backups” on page 203
Related reference:
“Query VM” on page 729
“Restore VM” on page 760
Restore Windows individual Active Directory objects
You can restore individual Active Directory objects to recover from accidental
corruption or deletion of Active Directory objects without requiring a shutdown or
restart of the Active Directory server.
On the Windows Server client, use the restore adobjects command to restore local,
deleted Active Directory objects (tombstone objects). You can also restore
individual Active Directory objects from system state backups on the IBM
Spectrum Protect server.
Related tasks:
“Restoring Windows system state” on page 191
Related reference:
“Restore Adobjects” on page 745
Chapter 5. Restoring your data
217
Reanimate tombstone objects or restoring from a system
state backup
Tombstone reanimation is a process to restore an object that had been deleted from
the Active Directory. When an object is deleted from Active Directory, it is not
physically erased, but only marked as deleted. It is then possible to reanimate
(restore) the object.
When an object is reanimated, not all object attributes are preserved. When an
object becomes a tombstone object, many attributes are automatically stripped from
it, and the stripped attributes are lost. It is possible, however, to change the Active
Directory schema so that more attributes are preserved when the object is deleted.
User-group links are not preserved in tombstones. For example, when a user object
is reanimated, the user account is not a member of any group. All of this
information must be recreated manually by the Active Directory administrator.
When an Active Directory object is restored from a system state backup on the IBM
Spectrum Protect server, virtually all of its attributes and its group membership are
restored. This is the best restore option using a Windows Server domain controller.
When an object is restored from the server:
v The Active Directory database is extracted from a system state backup and
restored into a temporary location.
v The restored database is opened.
v Select which objects you want to restore. For each object:
– A search for the matching tombstone is performed. The Globally Unique
Identifier (GUID) of the restored object is used to search for the tombstone.
– If the matching tombstone is found, it is reanimated. In this case, the restored
object retains the original Globally Unique Identifier (GUID) and the Security
Identifier (SID).
– If the matching tombstone is not found, a new object is created in the
database. In this case, the new object has a new GUID and a new SID that are
different than the original object.
v Missing attributes are copied from the backup into the reanimated or recreated
object. Existing attributes that have been changed since the backup was taken
are updated to match the value in the backup. New attributes that have been
added since the backup was taken are removed.
v Group membership is restored.
Although all attributes that can be set and the group links are recreated, the
restored objects might not be immediately available after the restore operation. An
Active Directory administrator might have to manually update the restored objects
in order to make them available. Make sure to read “Restrictions and limitations
when restoring Active Directory objects” on page 219 before performing the
restore.
Related concepts:
“Preserve attributes in tombstone objects” on page 221
Chapter 5, “Restoring your data,” on page 185
“Restrictions and limitations when restoring Active Directory objects” on page 219
Related tasks:
“Restoring Windows system state” on page 191
Related reference:
218
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
“Restore Adobjects” on page 745
Restoring Active Directory objects using the GUI and
command line
To restore individual Active Directory objects, you must run the backup-archive
client on a domain controller and your user account must be a member of the
Administrators group. The Active Directory objects are not displayed in the
directory tree if your user account is not a member of the Administrators group.
You can restore active directory objects or tombstone objects using either the GUI
or the command line.
To restore individual objects from the GUI:
1. Click Restore in the IBM Spectrum Protect window. The Restore window
opens.
2. Expand the directory tree if necessary. To expand an object in the tree, click the
plus sign (+) next to the object.
3. Locate the Active Directory node in the directory tree. Expand it to reveal Local
Deleted Objects. The Server object is also available.
v To restore tombstone objects, expand Local Deleted Objects, navigate to the
tombstone objects that you want to restore, and select the tombstone objects.
v To restore Active Directory objects that are backed up to the IBM Spectrum
Protect server:
a. Expand the Server object. A window opens displaying a list of system
state backups (with different time stamps) on the server.
b. Select a system state backup from the list. The Active Directory database
from that system state is restored in the background, and the tree is
populated with Active Directory objects.
c. Navigate to the Active Directory objects that you want to restore and
select the Active Directory objects.
Tip: To see the attributes for an Active Directory object, keep expanding each
Active Directory object in the tree until you reach the one you want. The
attributes for an object are displayed in the display area that is adjacent to
the tree. You can search or filter the tree for an Active Directory object based
on its name.
4. Click Restore to begin the restore operation. The Task List window opens and
shows the progress of the restore operation.
On the command line, use the query adobjects command to query and the restore
adobjects command to restore individual Active Directory objects.
Related reference:
“Query Adobjects” on page 703
“Restore Adobjects” on page 745
Restrictions and limitations when restoring Active Directory
objects
There are some restrictions and limitations to be aware of when restoring Active
Directory objects.
Understand the following restrictions before restoring objects:
Chapter 5. Restoring your data
219
v Do not restore the Active Directory as part of a system-state restore operation,
unless it is intended to be used for a disaster recovery-level restore operation of
the full Active Directory. This type of restore operation requires the Active
Directory Server to be stopped and restarted.
v You cannot perform a point-in-time restore of tombstone objects. You can
perform a point-in-time restore of Active Directory objects that are backed up to
the server.
v You cannot restore Active Directory objects from backup sets.
Understand the following limitations before restoring objects:
v Restoring Active Directory objects from the IBM Spectrum Protect server
requires temporary space on your local hard disk drive. You can use the
stagingdirectory option to specify a directory on your local hard disk for
storing temporary data from the server. Depending on the size of the temporary
data, network bandwidth, and both client and server performance, this operation
can take anywhere from 20 seconds to over an hour. There might be a delay in
refreshing the Restore window when displaying the Active Directory tree.
v User passwords cannot be restored by default. A restored user object is disabled
until the administrator resets the password and re-enables the account. Also, if
an account was deleted from the domain and is then restored by the
backup-archive client, it must be manually joined to the domain after the restore
operation. Otherwise, users on the target computer cannot log on to the domain.
In order to have a user or a computer object fully operational after restore, you
must modify schema attribute Unicode-Pwd as described in Preserve attributes in
tombstone objects.
v The Active Directory schema is not recreated when the Active Directory object is
restored. If the schema was modified after the backup, the restored object might
no longer be compatible with the new schema, and some Active Directory object
attributes might no longer be valid. The client issues a warning message if some
attributes cannot be restored.
v Group Policy Objects and their links to organizational units (OU) cannot be
restored.
v Local policies for restored Active Directory objects are not restored.
v When you restore an object from the IBM Spectrum Protect server, if the target
object already exists in the Active Directory and you replace it with its backup
version, the object is not deleted and recreated. The existing object is used as a
base, and its attributes are overwritten by the backup version. Some attributes,
such as the GUID and the SID, stay with the existing object and are not
overwritten by the backup version.
v If there are multiple tombstone objects for the same container, reanimate them
from the backup-archive client command line using the object GUID, in which
case the command-line client only reanimates the container object and not its
children. In the backup-archive client GUI, the entire container can be selected to
reanimate.
v When you restore an object from the IBM Spectrum Protect server, if the live
Active Directory object exists and has the prevent deletion bit on, the client can
modify the attributes of the object. However, if there is a tombstone object of the
same name but a different object GUID, the Directory Services returns the access
denied error.
v When you restore an object from the IBM Spectrum Protect server and the
container of the object has been renamed, the client recreates the container using
the original name at the time of the backup. When restoring a tombstone object,
220
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
the client restores it to the renamed container because the lastKnownParent
attribute of the tombstone object has been updated to reflect the new container
name.
Related concepts:
“Preserve attributes in tombstone objects”
Chapter 5, “Restoring your data,” on page 185
Related reference:
“Restore Adobjects” on page 745
“Stagingdirectory” on page 548
Preserve attributes in tombstone objects
To specify an attribute to be preserved in the tombstone object, first locate this
attribute in the Active Directory schema, then update the searchFlags attribute of
the schema object.
There is vendor-acquired software (for example, ADSI Edit) that allows you to
update the searchFlags attribute of the schema object.
Usually none of the bits in the searchFlags bit mask are set (the value is 0). Set
searchFlags to 8 (0x00000008) if you want Active Directory to save the particular
attribute in the tombstone object when the original object is deleted.
Related concepts:
Chapter 5, “Restoring your data,” on page 185
Related reference:
“Restore Adobjects” on page 745
Modifying the client acceptor and agent services to use the
web client
You cannot restore individual Active Directory objects using the web client by
default. The web client services (client acceptor and agent) run under the Local
System account by default. The Local System account does not have enough
privileges to restore Active Directory objects.
To enable this restore operation in the web client, follow these steps:
1. Modify the client acceptor and agent services to use an administrative account
such as Administrator when logging on to Windows.
2. You can edit the properties for the client acceptor and agent services (typically
called TSM Client Acceptor and TSM Remote Client Agent) in the Control
Panel.
3. Modify the client acceptor and the agent services in the Login Options page of
the IBM Spectrum Protect configuration wizard when you set up the web client
If the web client is already set up, follow these steps:
1. Click Start.
2. Click Control Panel → Administrative Tools → Services.
3. Select the scheduler service from the list of Windows services.
4. Click the Log On tab.
5. Click This Account in the Login As section.
6. Enter an administrative account, or click Browse to locate the domain account.
7. Enter the password for the domain account.
Chapter 5. Restoring your data
221
8. Click OK and then click Start.
Related reference:
“Restore Adobjects” on page 745
Restoring or retrieving data during a failover
When the client fails over to the secondary server, you can restore or retrieve
replicated data from the secondary server.
Before you begin
Before you begin to restore or retrieve data during a failover:
v Ensure that the client is configured for automated client failover.
v Ensure that you are connected to an IBM Spectrum Protect server that replicates
client nodes. For more information about failover requirements, see
“Requirements for automated client failover” on page 57.
Restriction: In failover mode, you cannot back up or archive data to the secondary
server.
Procedure
To restore or retrieve data during a failover, complete the following steps:
1. Verify the replication status of the client data on the secondary server. The
replication status indicates whether the most recent backup was replicated to
the secondary server.
2. Restore or retrieve your data as you would normally do from the client GUI or
from the command-line interface.
Tip: Restartable restore operations function as expected when you are
connected to the secondary server. However, restore operations that are
interrupted when the primary server goes down cannot be restarted after the
client fails over. You must run the whole restore operation again after the client
fails over to the secondary server.
Results
If the replicated data on the secondary server is not current, you are prompted to
continue or to stop the restore or retrieve operation.
For example, to restore the build.sh directory at the command-line interface, you
issue the following command:
dsmc res C:\build.sh
The following output is displayed:
222
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
IBM Spectrum Protect
Command Line Backup-Archive Client Interface
Client Version 8, Release 1, Level 0.0
Client date/time: 11/16/2016 12:05:35
(c) Copyright by IBM Corporation and other(s) 1990, 2016. All Rights Reserved.
Node Name: MY_NODE_NAME
ANS2106I Connection to primary IBM Spectrum Protect server 192.0.2.1 failed
ANS2107I Attempting to connect to secondary server TARGET at
192.0.2.9 : 1501
Node Name: MY_NODE_NAME
Session established with server TARGET: Windows
Server Version 8, Release 1, Level 0.0
Server date/time: 11/16/2016 12:05:35 Last access: 11/15/2016 14:13:32
Session established in failover mode to secondary server
ANS2108I Connected to secondary server TARGET.
Restore function invoked.
ANS2120W The last store operation date reported by the server TARGET of
05/16/2013 22:38:23 does not match the last store operation date of
05/21/2013 21:32:20 stored by the client.
Continue (Yes (Y)/No (N))
If you respond with N, the following message is displayed:
ANS1074W The operation was stopped by the user.
If you respond with Y, restore processing continues as normal, but the data that
you restore might not be the most current.
Related concepts:
“Automated client failover configuration and use” on page 56
Related tasks:
“Determining the status of replicated client data” on page 61
Authorizing another user to restore or retrieve your files
You can authorize a user on another node to restore your backup versions or
retrieve your archive copies. In this way, you can share files with other people or
with other workstations that you use with a different node name.
About this task
You can also authorize other nodes to access the automated system recovery (ASR)
file space.
Another node can be used to create the ASR diskette so that the workstation can
be recovered using ASR and the backup-archive client. Use the other node if a
problem occurs with the workstation and the ASR diskette of the workstation is
not available.
To authorize another node to restore or retrieve your files:
Procedure
1. Click Utilities → Node Access List from the main window.
2. In the Node Access List window, click the Add button.
Chapter 5. Restoring your data
223
3. In the Add Access Rule window, select an item in the Permit Access field to
specify the type of data that the other user can access. You can select either
Backed up Objects or Archived Objects.
4. Type the node name of the user in the Grant Access to Node field. Type the
node name of the host workstation of the user in the Grant Access to Node
field.
5. Type the user ID on the host workstation in the User field.
6. In the Filespace and Directory field, select the file space and the directory
that the user can access. You can select one file space and one directory at a
time. If you want to give the user access to another file space or directory, you
must create another access rule.
7. If you want to limit the user to specific files in the directory, type the name or
pattern of the files on the server that the other user can access in the Filename
field. You can make only one entry in the Filename field. It can either be a
single file name or a pattern that matches one or more files. You can use a
wildcard character as part of the pattern. Your entry must match files that
have been stored on the server.
8. If you want to give access to all files that match the file name specification
within the selected directory including its subdirectories, click Include
subdirectories.
9. Click OK to save the access rule and close the Add Access Rule window.
10. The access rule that you created is displayed in the list box in the Node
Access List window. When you have finished working with the Node Access
List window, click OK. If you do not want to save your changes, click Cancel
or close the window.
Results
For example, to give the node user2 access to all backup files and subdirectories
under the d:\user1 directory, create a rule with the following values:
Permit Access to: Backed up Objects
Grant Access to Node: user2
Filespace and Directory: d:\user1
Filename: *
Include subdirectories: Selected
The node you are authorizing must be registered with your IBM Spectrum Protect
server.
On the command line of the client, use the set access command to authorize
another node to restore or retrieve your files. You can also use the query access
command to see your current list, and delete access to delete nodes from the list.
Related reference:
“Delete Access” on page 679
“Query Access” on page 703
“Set Access” on page 778
Restoring or retrieving files from another client node
After users grant you access to their files on the server, you can restore or retrieve
those files to your local system.
224
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
About this task
You can display file spaces for another user on the server, restore the backup
versions of files for another user, or retrieve the archive copies for another user to
your local file system, by following these steps:
Procedure
1. Click Utilities from the main window.
2. Click Access Another Node.
3. Type the node name of the host workstation of the user in the Node name field
and click Set.
Results
If you are using commands, use the fromnode option to indicate the node. You
must also use the file space name, rather than the drive letter, to select the
restore-retrieve drive that you want to access. Include the file space name in braces
and specify it as you would specify a drive letter. For example, to restore the files
from the cougar node \projx directory on the d–disk file space to your own \projx
directory, enter:
dsmc restore -fromnode=cougar
\\cougar\d$\projx\* d:\projx\
Use the query filespace command to display a list of file spaces. For example, to
display a list of the file spaces of cougar, enter:
dsmc query filespace -fromnode=cougar
Important: The backup-archive client can use file space information when
restoring files. The file space information can contain the name of the computer
from which the files were backed up. If you restore files from another client node
and do not specify a destination for the restored files, the client uses the file space
information to restore the files. In this case, the client attempts to restore the files
to the drive on the original computer. If the restoring computer has access to the
drive of the original computer, you can restore files to the original drive. If the
restoring computer cannot access the drive of the original computer, the client
returns a network error message. If you want to restore the original directory
structure but on a different computer, specify only the target drive when you
restore the files. This is true when restoring files from another node and when
retrieving files from another node.
Related reference:
“Fromnode” on page 416
“Restore” on page 737
“Retrieve” on page 769
Restoring or retrieving your files to another workstation
When you are using a different workstation, you can restore or retrieve files you
backed up from your own workstation.
Your backup versions and archive copies are stored according to your node, not
your specific workstation. Your IBM Spectrum Protect password protects your data.
To restore or retrieve files to another workstation, use the virtualnodename option
to specify the node name of the workstation from which you backed up the files.
You can use the virtualnodename option when starting IBM Spectrum Protect or
Chapter 5. Restoring your data
225
place the option in your client options file, dsm.opt, on the workstation. If you are
using a workstation other than your own, use the virtualnodename option with the
dsm command. For example, if your node name is cougar, enter:
start dsm -virtualnodename=cougar
You can then restore or retrieve files as if you were working from your original
workstation.
You can also use virtualnodename option on commands. For example, to restore
your \projx files to your local c:\myfiles directory, enter:
dsmc restore -virtualnodename=cougar \\cougar\d$\projx\*.* c:\myfiles\
If you do not want to restore or retrieve the files to the same directory name on
the alternate workstation, enter a different destination.
Restoring or retrieving files to another type of workstation
You can restore or retrieve files from one system type to another. This is called
cross-client restore.
Restriction: You must have the appropriate permissions to access the file space of
the other workstation.
NTFS and ReFS drives permit file and directory names that are longer than those
permitted on FAT drives. If you are recovering files to a FAT drive with long file
names, specify a destination file specification for each file.
When you use the Windows client to recover files with long names to an NTFS or
ReFS file system, the long names are preserved, even if you are recovering the file
to a different type of drive than the source drive.
Related tasks:
“Authorizing another user to restore or retrieve your files” on page 223
“Restoring or retrieving files from another client node” on page 224
Deleting file spaces
If your IBM Spectrum Protect administrator grants you authority, you can delete
entire file spaces from the server.
About this task
You cannot delete individual backup copies that are kept on the server. When you
delete a file space, you delete all the files, both backup copies and archive copies,
that are contained within the file space. For example, if you delete the file space
for your C drive, you are deleting every backup copy for every file on that disk
and every file that you archived from that disk.
Attention:
Carefully consider what you are doing before you delete a file space.
You can delete file spaces using the GUI or the command-line client. To delete
network-attached storage (NAS) file spaces, use the web client or command-line
client.
To delete a file space using the GUI client, perform the following steps:
226
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Procedure
1. From the main window, click Utilities → Delete Filespaces.
2. Select the file spaces you want to delete.
3. Click Delete. The client prompts you for confirmation before deleting the file
space.
Results
You can also delete a file space using the delete filespace command. Use the class
option with the delete filespace command to delete NAS file spaces.
Related reference:
“Class” on page 337
“Delete Filespace” on page 685
Restoring data to a point in time
Use a point-in-time restore to restore files to the state that existed at a specific date
and time.
About this task
A point-in-time restore can eliminate the effect of data corruption by restoring data
from a time prior to known corruption, or recover a basic configuration to a prior
condition.
You can perform a point-in-time restore of system state data, a file space, a
directory, or a file. You can also perform a point-in-time restore of image backups.
Perform incremental backups to support a point-in-time restore. During an
incremental backup, the backup-archive client notifies the server when files are
deleted from a client file space or directory. Selective and incremental-by-date
backups do not notify the server about deleted files. Run incremental backups at a
frequency consistent with possible restore requirements.
If you request a point-in-time restore with a date and time that is before the oldest
version maintained by the IBM Spectrum Protect server, the object is not restored
to your system. Files that were deleted from your workstation before the
point-in-time specified are not restored.
Note:
1. Your administrator must define copy group settings that maintain enough
inactive versions of a file to guarantee that you can restore that file to a specific
date and time. If enough versions are not maintained, the client might not be
able to restore all objects to the point-in-time you specify.
2. If you delete a file or directory, the next time you run an incremental backup,
the active backup version becomes inactive and the oldest versions that exceed
the number specified by the versions data deleted attribute of the management
class are deleted.
When you perform a point-in-time restore, consider the following information:
v The client restores file versions from the most recent backup before the specified
point-in-time date. Ensure the point-in-time that you specify is not the same as
the date and time this backup was performed.
Chapter 5. Restoring your data
227
v If the date and time you specify for the object you are trying to restore is earlier
than the oldest version that exists on the server, the client cannot restore that
object.
v Point-in-time restore restores files that were deleted from the client workstation
after the point-in-time date but not files that were deleted before this date.
v The client cannot restore a file that was created after the point-in-time date and
time. When a point-in-time restore runs, files that were created on the client after
the point-in-time date are not deleted.
Procedure
To perform a point-in-time restore by using the client GUI, complete the following
steps:
1. Click the Restore button in the main window. The Restore window appears.
2. Click the Point-in-Time button from the Restore window. The Point in Time
Restore window appears.
3. Select the Use a Point-in-Time Date selection box. Select the date and time and
click OK. The point in time that you specified appears in the Point in Time
display field in the Restore window.
4. Display the objects that you want to restore. You can search for an object by
name, filter the directory tree, or work with the directories in the directory tree.
5. Click the selection boxes next to the objects you want to restore.
6. Click the Restore button. The Restore Destination window is displayed. Enter
the appropriate information.
7. Click the Restore button to start the restore. The Restore Task List window
displays the restore processing status.
Results
Note: If there are no backup versions of a directory for the point-in-time you
specify, files within that directory are not restorable from the GUI. However, you
can restore these files from the command line.
You can start point-in-time restore from the command-line client by using the
pitdate and pittime options with the query backup and restore commands. For
example, when you use the pitdate and pittime options with the query backup
command, you establish the point-in-time for which file information is returned.
When you use pitdate and pittime with the restore command, the date and time
values you specify establish the point-in-time for which files are returned. If you
specify pitdate without a pittime value, pittime defaults to 23:59:59. If you
specify pittime without a pitdate value, it is ignored.
Related concepts:
Chapter 9, “Storage management policies,” on page 261
Related reference:
“Backup Image” on page 654
Restore NAS file systems
You restore NAS file system images using the web client or command line
interface. The web client interface is available only for connections to the IBM
Spectrum Protect Version 8.1.1, V8.1.0, or V7.1.7 or earlier servers.
|
|
|
228
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
You can restore full or differential NAS file system images that were backed up
previously. If you restore a differential image, IBM Spectrum Protect automatically
restores the full backup image first, followed by the differential image. It is not
necessary for a client node to mount a NAS file system to perform backup or
restore operations on that file system.
Related concepts:
“Web client configuration overview” on page 27
Restoring NAS file systems using the web client
This section lists the steps to follow to restore NAS file systems using the web
client GUI.
Before you begin
|
|
The web client interface is available only for connections to the IBM Spectrum
Protect Version 8.1.1, V8.1.0, or V7.1.7 or earlier servers.
Procedure
1. Click the Restore button from the main window. The Restore window appears.
2. Expand the directory tree if necessary. To expand a node in the tree, click the
plus sign (+) next to an object in the tree. Nodes shown are those that have
been backed up and to which your administrator has authority. The root node
called Nodes is not selectable. This node only appears if a NAS plug-in is
present on the client workstation. NAS nodes display on the same level as the
node of the client workstation. Only nodes to which the administrator has
authority appear.
3. Expand the NAS node to reveal the Image object.
4. Expand the Image object to display volumes that you can restore. You cannot
expand Volume objects.
5. Click the selection boxes next to the volumes under the Image object that you
want to restore. If you want to restore a NAS image that was backed up on a
particular date, click the Point In Time button. After you select a date, the last
object that was backed up on or prior to that date appears, including any
inactive objects. If you want to display all images (including active images and
inactive images), before you select them, select View → Display active/inactive
files from the menu bar.
6. Click Restore. The Restore Destination window appears. Enter the information
in the Restore Destination window. If you choose to restore to a different
destination, you can only restore one volume at a time to a different
destination. You can restore NAS file system images to any volume on the NAS
file server from which they were backed up. You cannot restore images to
another NAS file server.
7. Click Restore. The NAS Restore Task List window displays the restore
processing status and progress bar. If there is a number next to the progress
bar, it indicates the size of the restore, if known. After the restore completes, the
NAS Restore Report window displays processing details. If you must close the
web browser session, current NAS operations continue after you disconnect.
You can use the Dismiss button on the NAS Restore Task List window to quit
monitoring processes without ending the current operation.
8. (Optional) To monitor processing of an operation, select the Actions > IBM
Spectrum Protect Activities from the main window.
Chapter 5. Restoring your data
229
Results
Considerations:
v Workstation and remote (NAS) backups are mutually exclusive in a Restore
window. After selecting an item for restore, the next item you select must be of
the same type (either NAS or non NAS).
v Details will not appear in the right-frame of the Restore window for NAS nodes
or images. To view information about a NAS image, highlight the NAS image
and select View > File Details from the menu.
v To delete NAS file spaces, select Utilities > Delete Filespaces. You can delete
both workstation and remote objects.
Restoring NAS files and directories using the web client
You can use the toc option with the include.fs.nas option in your client options
file to specify whether the client saves Table of Contents (TOC) information for
each file system backup.
About this task
If you save TOC information, you can use web client to examine the entire file
system tree and select files and directories to restore. Creation of a TOC requires
that you define the TOCDESTINATION attribute in the backup copy group for the
management class to which this backup image is bound. Note that TOC creation
requires additional processing, network resources, storage pool space, and possibly
a mount point during the backup operation. If you do not save TOC information,
you can still restore individual files or directory trees using the RESTORE NODE
server command, provided that you know the fully qualified name of each file or
directory and the image in which that object was backed up.
To restore NAS files and directories:
Procedure
1. Click Restore from the main window. The Restore window appears.
2. Expand the directory tree if necessary. To expand a node in the tree, click the
plus sign (+) next to an object in the tree. Nodes shown are those that have
been backed up and to which your administrator has authority. The root node
called Nodes is not selectable. This node only appears if a NAS plug-in is
present on the client workstation. NAS nodes appear on the same level as the
node of the client workstation. Only nodes to which the administrator has
authority appear.
3. Expand the NAS node to display the File Level object.
4. Expand the File Level object to display the volumes, directories, and files that
were last backed up. When you expand the volume object, and complete TOC
information is available on the server for the latest backup, the Load Table of
Contents dialog appears. If complete TOC information is not available for the
latest backup, no objects appear below the volume object. The next step
explains how to display objects from backups other than the latest backup.
Complete TOC information is provided if you performed either of the
following operations: (1) A differential image backup with TOC information
and its corresponding full image backup with TOC information, or (2) A full
image backup with TOC information.
5. Click the selection boxes next to the directories or files that you want to restore.
230
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
a. If you want to restore files from a NAS image that was backed up on a
particular date or display files from several older versions, highlight the
volume you want to restore and click the Point In Time button.
b. If you select Use a Point in Time Date in the Point in Time Restore
windows, files from the image backed up on that date, and if it is a
differential image, files from its corresponding full image appear under the
File Level object.
c. If you click Use Selected Images in the Point in Time Restore window, the
Selected Images window appears for you to select images. The contents of
the selected images appear in the File Level object.
6. Click Restore. The Restore Destination window appears. Enter the information
in the Restore Destination window. If you choose to restore to a different
destination, you can only restore one volume at a time to a different
destination.
7. Click Restore. The NAS Restore Task List window displays the restore
processing status and progress bar. If there is a number next to the progress
bar, it indicates the size of the restore, if known. After the restore completes, the
NAS Restore Report window displays processing details. If you must close the
web browser session, current NAS operations continue after you disconnect.
You can use the Dismiss button on the NAS Restore Task List window to quit
monitoring processes without ending the current operation.
8. (Optional) To monitor processing of an operation, select the Actions > IBM
Spectrum Protect Activities from the main window.
Results
Considerations:
v Workstation and remote (NAS) backups are mutually exclusive in a Restore
window. After selecting an item for restore, the next item you select must be of
the same type either (either workstation or NAS).
v To view information about objects in a NAS node, highlight the object and select
View > File Details from the menu.
v To delete NAS file spaces, select Utilities > Delete Filespaces. You can delete
both workstation and remote objects.
Related reference:
“Toc” on page 562
Options and commands to restore NAS file systems from the
command line
This topic lists some examples of options and commands you can use to restore
NAS file system images from the command line.
Table 29. NAS options and commands
Option or command
Definition
Page
query node
Displays all the nodes for which a particular “Query Node” on
administrative user ID has authority to
page 722
perform operations. The administrative user
ID should have at least client owner
authority over both the NAS node and the
client workstation node they are using either
from command line or from the web client.
Chapter 5. Restoring your data
231
Table 29. NAS options and commands (continued)
Option or command
Definition
Page
query backup
Use the query backup command with the
class option to display information about
file system images backed up for a NAS file
server.
“Query Backup” on
page 707
query filespace
Use the query filespace command with the
class option to display a list of file spaces
belonging to a NAS node.
“Query Filespace” on
page 714
restore nas
Restores the image of a file system
belonging to a Network Attached Storage
(NAS) file server.
“Restore NAS” on
page 758
monitor process
Displays current backup and restore
processes for all NAS nodes for which an
administrative user has authority. The
administrative user can then select one
process to monitor.
“Monitor Process” on
page 700
cancel process
Displays current backup and restore
processes for all NAS nodes for which an
administrative user has authority. From the
display, the administrative user can select
one process to cancel.
“Cancel Process” on
page 678
delete filespace
Use the delete filespace with the class
option to display a list of file spaces
belonging to a NAS node so that you can
choose one to delete.
“Delete Filespace” on
page 685
A NAS file system specification uses the following conventions:
v Regardless of client platform, NAS file system specifications use the forward
slash (/) separator, as in this example: /vol/vol0.
v NAS file system designations on the command line require brace delimiters {}
around the file system names, such as: {/vol/vol0}.
Note: When you initiate a NAS restore operation using the command line client or
the web client, the server starts a process to initiate, control, and monitor the
operation. It might take several moments before you notice progress at the client
command line interface because the server must perform a mount and other
necessary tasks before data movement occurs. The IBM Spectrum Protect command
line client might display an Interrupted ... message when the mount occurs. You
can ignore this message.
232
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chapter 6. Archive and retrieve your data (Windows)
You can archive infrequently used files to the IBM Spectrum Protect server and
retrieve them when necessary. Archiving and retrieving files is similar to backing
up and restoring files.
Unless otherwise specified, references to Windows refer to all supported Windows
operating systems.
All the primary archive and retrieve procedures also apply to the web client,
except for the following functions:
v Preferences editor
v Setup wizard
You can complete the following primary archive and retrieve tasks:
v “Archiving data with the GUI” on page 234
v “Archive data examples by using the command line” on page 235
v “Deleting archive data” on page 238
v “Retrieving archives with the GUI” on page 239
v “Retrieve archive copies by using the command line” on page 239
Related concepts:
“When to back up and when to archive files” on page 133
Related tasks:
“Starting a web client session” on page 117
Archive files
To archive files, select the files that you want to archive. You can select the files by
name or description, or select them from a directory tree.
Your administrator might set up schedules to automatically archive certain files on
your workstation. The following sections contain information about how to archive
files without using a schedule.
You must assign an archive description for all archived files. An archive
description identifies data through a meaningful description that you can use later
to identify files and directories. You can enter as many as 254 characters to
describe your archived data. If you do not enter a description, the following
default archive description is assigned:
Archive Date: mm/dd/yyyy
where mm/dd/yyyy is the current date.
When you select the archive function from the backup-archive GUI, a list of all
previously used archive descriptions are displayed. You can assign these archive
descriptions to future archives.
Incremental backup might recall migrated files, while selective backup and archive
always recall migrated files, if you do not use the skipmigrated option.
Related concepts:
© Copyright IBM Corp. 1993, 2017
233
Options for backing up migrated files: skipmigrated, checkreparsecontent,
stagingdirectory
Related tasks:
“Setting the client scheduler process to run as a background task and start
automatically at startup” on page 246
Snapshot backup or archive with open file support
If open file support has been configured, the backup-archive client runs a snapshot
backup or archive of files that are locked (or "in use") by other applications.
The snapshot allows the archive to be taken from a point-in-time copy that
matches the file system at the time the snapshot is taken. Subsequent changes to
the file system are not included in the archive. You can set the snapshotproviderfs
parameter of the include.fs option to none to specify which drives do not use
open file support.
Note:
1. You can use the include.fs option to set snapshot options on a per file system
basis.
2. Open file support is only available for local fixed volumes (mounted to either
drive letters or volume mount points) formatted with FAT, FAT32, NTFS, or
ReFS file systems. This support includes SAN-attached volumes that meet these
requirements.
3. If the client is unable to create a snapshot, failover to non-OFS backup occurs;
the same backup support that would be done if the OFS feature was not
installed.
4. To enable open file support in a cluster environment all workstations in the
cluster should have the OFS feature configured.
5. When using the open file support feature with VSS, the client adds the
snapshot volume name to the path of the objects being processed. The snapshot
volume name can be up to 1024 bytes. The complete path (snapshot volume
name plus object path) can be 8192 bytes or less.
For information about open file support restrictions and issues, search for TSM
Client Open File Support (OFS) at the IBM support website.
Related concepts:
Chapter 11, “Processing options,” on page 291
Related tasks:
“Configuring Open File Support” on page 78
Archiving data with the GUI
You can archive specific files or entire directories from a directory tree. You can
also assign a unique description for each group of files you archive (archive
package).
About this task
To archive your files, complete the following steps:
Procedure
1. Click Archive in the GUI main window. The Archive window displays.
234
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
2. Expand the directory tree by clicking the plus sign (+) or a folder icon in the
tree. To search or filter files, click the Search icon from the toolbar.
3. Enter a description, accept the default description, or select an existing
description for your archive package in the Description field.
4. To modify specific archive options, click Options. Any options that you change
are effective during the current session only.
5. Click Archive. The Archive Status window displays the progress of the archive
operation.
Archive data examples by using the command line
You can archive data when you want to preserve copies of files in their current
state, either for later use or for historical or legal purposes.
You can archive a single file, a group of files, or all the files in a directory or
subdirectory. After you archive a file, you can delete the original file from your
workstation. Use the archive command to archive files.
The following table shows examples of how to use the archive command to
archive objects.
Table 30. Command-line archive examples
Task
Command
Considerations
Archive all files in the
c:\plan\proj1 directory with a
file extension of .txt.
dsmc archive c:\plan\proj1\*.txt
Use wildcards to archive more than one
file at a time.
Archive all files in the
c:\small\testdir directory and
delete the files on your
workstation.
dsmc archive c:\small\testdir\*
-deletefiles
Retrieve the archived files to your
workstation whenever you need them
again. For more information about the
deletefiles option, see “Deletefiles”
on page 357.
Archive the c:\proj1\h1.doc file
and the c:\proj2\h2.doc file
dsmc archive c:\proj1\h1.doc
c:\proj2\h2.doc
You can specify as many files to be
archived as the resources and operating
system limits permit. Separate the files
to be archived with a space. For more
information about the filelist option,
see “Filelist” on page 410.
Archive a list of files in the
c:\filelist.txt file.
dsmc archive -filelist=c:\
filelist.txt
Use the filelist option to process a
list of files. For more information about
the filelist option, see “Filelist” on
page 410.
Archive the a:\ch1.doc file and
dsmc archive a:\ch1.doc
assign a description to the archive. -description="Chapter 1, first
version"
If you do not specify a description with
the archive command, the default is
Archive Date:x, where x is the current
system date. For more information
about the description option, see
“Description” on page 358.
Archive all the files in the d:\proj dsmc archive d:\proj\ -subdir=yes
directory and its subdirectories.
For more information about the subdir
option, see “Subdir” on page 549.
Use the v2archive option with the dsmc archive c:\relx\dir1\
archive command to archive only -v2archive
files in the c:\relx\dir1 directory.
IBM Spectrum Protect archives only
files in the c:\relx\dir1 directory.
Directories that exist in the path are not
processed. For more information about
the v2archive option, see “V2archive”
on page 570.
Chapter 6. Archive and retrieve your data (Windows)
235
Table 30. Command-line archive examples (continued)
Task
Command
Use the archmc option with the
archive command to specify the
available management class for
the policy domain to which you
want to bind your archived files.
dsmc archive –archmc=RET2YRS c:\plan For more information about the archmc
\proj1\ budget.jan\*
option, see “Archmc” on page 319. For
more information about management
classes, see Chapter 9, “Storage
management policies,” on page 261.
Assume that you initiated a
dsmc archive c:\dir1\sub1\*
snapshot of the C:\ drive and
-subdir=yes -snapshotroot=\\
mounted the snapshot as the
florence\c$\snapshots\snapshot.0
logical volume \\florence\c$\
snapshots\ snapshot.0. You
archive the c:\dir1\sub1 directory
tree from the local snapshot and
manage it on the IBM Spectrum
Protect server under the file space
name C:\.
Considerations
For more information, see
“Snapshotroot” on page 537.
Related reference:
“Archive” on page 643
Associate a local snapshot with a server file space (Windows)
You can associate the data on the local snapshot with the real file space data that is
stored on the IBM Spectrum Protect server.
To associate the data on the local snapshot with the real file space data on the IBM
Spectrum Protect server, use the snapshotroot option with the archive command,
with a vendor-acquired application that provides a snapshot of a logical volume.
The snapshotroot option cannot provide any facilities to take a volume snapshot, it
can manage only data that is created by a volume snapshot.
Related reference:
“Snapshotroot” on page 537
Archiving data with client node proxy
Archives of multiple nodes that share storage can be consolidated to a common
target node name on the IBM Spectrum Protect server.
About this task
This is useful when the workstation responsible for performing the archive can
change over time, such as with a cluster. The asnodename option also allows data to
be restored from a different system than the one that performed the backup. Use
the asnodename option with the appropriate command to back up, archive, restore,
and retrieve data under the target node name on the IBM Spectrum Protect server.
Tivoli Storage Manager FastBack clients are also backed up using client node
proxy.
To enable this option, follow these steps:
1. Install the backup-archive client on all nodes in a shared data environment.
2. Register each node with the IBM Spectrum Protect server, if it does not exist.
Register the common target node name to be shared by each of the agent nodes
used in your shared data environment.
236
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
3. Register each of the nodes in the shared data environment with the IBM
Spectrum Protect server. This is the agent node name that is used for
authentication purposes. Data is not stored using the node name when the
asnodename option is used.
4. The IBM Spectrum Protect administrator must grant proxy authority to all
nodes in the shared environment to access the target node name on the IBM
Spectrum Protect server, using the GRANT PROXYNODE server command.
5. Use the QUERY PROXYNODE administrative client command to display the
client nodes of the authorized user, granted by the GRANT PROXYNODE
command.
Follow these steps to set up encryption with the encryptkey=save option:
Procedure
1. Specify encryptkey=save in the options file.
2. Back up at least one file with asnode=ProxyNodeName to create a local encryption
key on each agent node in the multiple node environment.
Results
Follow these steps to set up encryption with the encryptkey=prompt option:
1. Specify encryptkey=prompt in the options file.
2. Ensure that users of the agent nodes in the multiple node environment are
using the same encryption key.
v If you change the encryption key, you must repeat the previous steps.
v Use the same encryption key for all files backed up in the shared node
environment.
Follow these steps to enable multinode operation from the GUI:
1. Verify that the client node has proxy authority to a target node (or authorized
to act as the target node) using the QUERY PROXYNODE administrative client
command.
2. Select Edit > Preferences to open the preferences window.
3. Select the General tab and fill in the As Node Name field with the name of the
proxy authorized target node.
4. Click Apply and then OK to close the preferences window.
Follow these steps to verify that your client node is now accessing the server as
the target node:
1. Open the tree window and check that the target node name specified by the As
Node Name field appears, or
2. Verify the target node name in the Accessing As Node field in the Connection
Information window.
To return to single node operation, delete the As Node Name from the Accessing
As Node field in the General > Preferences tab.
Considerations for a proxied session:
v A proxy operation uses the settings for the target node (such as maxnummp and
deduplication) and schedules that are defined on the IBM Spectrum Protect
server. The IBM Spectrum Protect server node settings and schedules for the
agent node are ignored.
Chapter 6. Archive and retrieve your data (Windows)
237
v All agent nodes in the multiple node environment must be of the same platform
type.
v Do not use target nodes as traditional nodes. Use them only for multiple node
processing.
v You cannot perform a system object or system state backup or restore.
v You cannot access another node (either from GUI drop down or use of the
fromnode option).
v You cannot use the clusternode option.
v You cannot perform NAS backup or restore.
Related reference:
“Asnodename” on page 320
“Session settings and schedules for a proxy operation” on page 322
Deleting archive data
You can delete individual archive objects from the IBM Spectrum Protect server,
without having to delete the entire file space to which they belong.
Before you begin
Your IBM Spectrum Protect administrator must grant you the authority to delete
archived objects. To determine whether you have this authority, select File >
Connection Information from the backup-archive client GUI or from the main
menu in the web client. Your archive delete authority status is listed in the Delete
Archive Files field. If this field shows No, you cannot delete archived objects
unless your administrator grants you the authority to delete them.
Procedure
To delete an archived object from the server, perform the following steps in the
web client or GUI. As an alternative to using the web client or GUI, you can also
delete archived objects from the command line by using the delete archive
command.
1. Select Delete Archive Data from the Utilities menu.
2. In the Archive Delete window, expand the directory tree by clicking the plus
sign (+) or folder icon next to the object you want to expand. Objects on the
tree are grouped by archive package description.
3. Select the archived objects that you want to delete.
4. Click Delete. The client prompts you for confirmation before it starts to delete
the selected objects. The Archive Delete Task List window shows the progress
of the delete operation.
Related reference:
“Delete Archive” on page 679
Retrieve archives
Select the Retrieve function to recover an archive copy of a file or a directory.
Note: When you retrieve a directory, its modification date and time is set to the
date and time of the retrieve, not to the date and time the directory had when it
was archived. This is because a retrieve operation retrieves the directories first, and
then adds the files to the directories.
238
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
You can also retrieve archive copies from the directory tree, filter the directory tree,
and retrieve archive copies of files owned by someone else. To do any of these,
click the Retrieve button on the main window of the backup-archive client GUI
and follow the directions provided in the task help of the GUI.
Important: When you retrieve a file without any specifications, and more than one
version of the archive copy exists on the server, all of the copies are retrieved.
After the first copy is retrieved, the second copy is retrieved. If there is an existing
copy on your client workstation, you are prompted to replace, skip, or cancel.
Related concepts:
“Duplicate file names” on page 185
Retrieving archives with the GUI
You can retrieve your archived files with the backup-archive client GUI.
Procedure
1. Click Retrieve on the GUI main window. The Retrieve window displays.
2. Expand the directory tree by clicking the plus sign (+) or the folder icon next
to an object you want to expand. To search or filter files, click the Search icon
from the toolbar.
3. Enter your search criteria in the Find Files window.
4. Click Search. The Matching Files window displays.
5. Click the selection boxes of the files that you want to retrieve and close the
Matching Files window.
6. Enter your filter criteria in the Find Files window.
7. Click Filter. The Retrieve window displays the filtered files.
8. Click the selection boxes of the filtered files or directories that you want to
retrieve.
9. To modify specific retrieve options, click Options. Any options that you
change are effective during the current session only.
10. Click Retrieve. The Retrieve Destination window displays. You can retrieve
files to a directory or drive other than the one from where they were
originally archived. You can also select how much of the parent directory
structure is re-created at the retrieve location.
11. Click Retrieve. The Retrieve Status window displays the processing status.
Retrieve archive copies by using the command line
You retrieve a file when you want to return an archive copy from the server to
your workstation. Some examples of how to retrieve archived files by using the
command line are shown.
You can retrieve a single file, a group of files, or all the files in a directory or
subdirectory. When you retrieve a file, the IBM Spectrum Protect server sends you
a copy of that file. The archived file remains in storage.
Use the retrieve command to retrieve files. The following table shows examples of
using the retrieve command.
Chapter 6. Archive and retrieve your data (Windows)
239
Table 31. Command line examples of retrieving archives
Task
Command
Considerations
Retrieve the c:\doc\h2.doc file to its
original directory.
dsmc retrieve c:\doc\h2.doc
If you do not specify a destination,
the files are retrieved to their original
location.
Retrieve the c:\doc\h2.doc file under
a new name and directory.
dsmc retrieve c:\doc\h2.doc
c:\proj2\h3.doc
None
Retrieve all files that are archived
with a specific description to a
directory named retr1 at a new
location
dsmc retrieve c:\* d:\retr1\
-sub=yes -desc="My first archive"
None
Retrieve all files from the c:\projecta dsmc retrieve c:\projecta\*.bak
directory that end with the characters c:\projectn
.bak to the c:\projectn directory.
None
Use the pick option display a list of
archives from which you can select
files to retrieve.
For more information about the pick
option, see “Pick” on page 477.
dsmc retrieve c:\project\* -pick
Retrieve a file that is originally
dsmc retrieve {workathome}\doc\
archived from the diskette that is
h2.doc a:\doc\h2.doc
labeled workathome on the a: drive, to
a diskette in the a: drive labeled
extra.
If you are retrieving a file to a disk
that has a different label other than
the disk from which the file was
archived, use the file space name
(label) of the archive disk rather than
the drive letter.
Retrieve the c:\doc\h2.doc file to its
original directory on the workstation,
named star.
For the purposes of this manual, the
workstation name is part of the file
name. Therefore, if you archive files
on one workstation and you want to
retrieve them to another workstation,
you must specify a destination. This
requirement is true even if you are
retrieving to the same physical
workstation, but the workstation has
a new name.
dsmc retrieve c:\doc\h2.doc
\\star\c$\
To retrieve the file to star, which was
renamed meteor, enter:
dsmc retrieve \\star\c$\
doc\h2.doc \\meteor\c$\
You can also enter:
dsmc retrieve \\star\c$\
doc\h2.doc c:\
This example is valid because if the
workstation name is not included in
the specification, the local workstation
is assumed (meteor, in this case).
Related reference:
“Retrieve” on page 769
240
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chapter 7. IBM Spectrum Protect scheduler overview
The IBM Spectrum Protect central scheduler allows client operations to occur
automatically at specified times.
To understand scheduling with IBM Spectrum Protect, several terms need to be
defined:
schedule definition
A schedule definition on the IBM Spectrum Protect server specifies critical
properties of an automated activity, including the type of action, the time
the action should take place, and how frequently the action takes place.
Numerous other properties can be set for a schedule. For information
about the DEFINE SCHEDULE, see the IBM Spectrum Protect server
documentation.
schedule association
A schedule association is an assignment to a specific schedule definition
for a client node. Multiple schedule associations allow single schedule
definitions to be used by many client nodes. Because schedule definitions
are included with specific policy domains, it is only possible for nodes that
are defined to a certain policy domain to be associated with schedules
defined in that domain.
scheduled event
A scheduled event is a specific occurrence of when a schedule is run for a
node. The following conditions must be met before automatic scheduled
events take place for a client:
v A schedule definition must exist for a specific policy domain.
v A schedule association must exist for the required node, which belongs
to that policy domain.
v The client scheduler process must be running on the client system.
When creating a schedule definition on the IBM Spectrum Protect server, schedule
actions that you can take include incremental, selective, archive, restore, retrieve,
imagebackup, imagerestore, command, and macro. The scheduled action that is
most frequently used is incremental with the objects parameter left undefined.
With this setting, the IBM Spectrum Protect client performs a domain incremental
backup of all drives defined by the client domain option. A schedule definition
using the command action allows an operating system command or shell script to be
executed. When automating tasks for IBM Spectrum Protect for Data Protection
clients, you must use command action schedule definitions, which invoke the
command-line utilities for those applications.
The schedule startup window indicates the acceptable time period for a scheduled
event to start. The startup window is defined by these schedule definition
parameters: startdate, starttime, durunits, and duration. The startdate and
starttime options define the beginning of the startup window for the very first
scheduled event. The beginning of the startup windows for subsequent scheduled
events vary depending on the period and perunit values of the schedule
definition. The duration and durunits parameters define the length of the startup
window. The schedule action is required to start within the startup window. To
illustrate, consider the results of the following schedule definition:
© Copyright IBM Corp. 1993, 2017
241
define schedule standard test1 action=incremental starttime=12:00:00 period=1
perunits=hour dur=30 duru=minutes
Event
Window start
Window end
Actual start (just an
example, times vary)
1
12:00:00
12:30:00
12:05:33
2
13:00:00
13:30:00
13:15:02
3
14:00:00
14:30:00
14:02:00
and so on
The variation in actual start times is a result of the randomization feature provided
by the IBM Spectrum Protect central scheduler which helps to balance the load of
scheduled sessions on the IBM Spectrum Protect server.
Examples: Blank spaces in file names in schedule definitions
When you define or update a schedule objects parameter or the schedule options
parameter with file specifications that contain blank spaces, put quotation marks
(") around each file specification that contains blanks, then add single quotes (')
around the entire specification.
The following examples show how to delimit schedule object parameters when
file specifications contain space characters:
objects='"c:\home\proj1\Some file.doc"'
objects='"c:\home\proj1\Some file.doc" "c:\home\Another file.txt"
c:\home\noblanks.txt'
objects='"c:\home\My Directory With Blank Spaces\"'
objects='"c:\Users\user1\Documents\Some file.doc"'
objects='"c:\Users\user1\Documents\Some file.doc"
"c:\Users\user5\Documents\ Another file.txt" c:\Users\user3\Documents\noblanks.txt'
objects='"c:\Users\user1\My Directory With Blank Spaces\"'
This syntax ensures that a file specification containing a space, such as
c:\home\proj1\Some file.doc, is treated as a single file name, and not as two
separate files (c:\home\proj1\Some, and file.doc)
The following examples show how to delimit schedule options parameters when
file specifications contain space characters:
options=’-preschedulecmd="c:\home\me\my files\bin\myscript"
-postschedulecmd="c:\home\me\my files\bin\mypostscript" -quiet’
options=’-presched="c:\home\me\my files\bin\precmd" -postsched=finish’
You can also refer to the objects and options parameter information for the
DEFINE SCHEDULE and UPDATE SCHEDULE commands. For descriptions of
these commands and parameters, see the IBM Spectrum Protect server
documentation..
Related concepts:
“Specifying input strings that contain blank spaces or quotation marks” on page
116
Preferential start times for certain nodes
Occasionally, you might want to ensure that a particular node begins its scheduled
activity as close as possible to the defined start time of the schedule. The need for
this typically arises when prompted mode scheduling is in use.
242
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Depending on the number of client nodes associated with the schedule and where
the node is in the prompting sequence, the node might be prompted significantly
later than the start time for the schedule.
In this case, you can perform the following steps:
1. Copy the schedule to a new schedule with a different name (or define a new
schedule with the preferred attributes).
2. Set the new schedule priority attribute so that it has a higher priority than the
original schedule.
3. Delete the association for the node from the original schedule, then associate
the node to the new schedule.
Now the IBM Spectrum Protect server processes the new schedule first.
Scheduler processing options
Scheduler processing options determine what operations are performed when a
scheduler job is started.
You can define most of these scheduler processing options in the client options file.
However, some of these options can be set on the IBM Spectrum Protect server, so
they affect all clients.
The following table shows which options are defined by the client and server, and
which options are overridden by the server. An X in a column indicates where the
option can be specified.
Option
Client defined
managedservices
X
maxcmdretries
X
Server defined
Server global override
SET MAXCMDRETRIES
command
X
maxschedsessions
postschedulecmd,
postnschedulecmd
X
preschedulecmd,
prenschedulecmd
X
queryschedperiod
X
SET
QUERYSCHEDPERIOD
command
X
randomize
retryperiod
X
schedcmddisabled
X
schedlogname
X
schedlogretention
X
schedmode
X
sessioninitiation
X
SET RETRYPERIOD
command
SET SCHEDMODES
command
X
UPDATE NODE command
Chapter 7. IBM Spectrum Protect scheduler overview
243
Option
Client defined
Server defined
tcpclientaddress
X
X
(also defined on server
when
sessioninit=serveronly as
part of the node
definition)
tcpclientport
X
X
(also defined on server
when
sessioninit=serveronly as
part of the node
definition)
Server global override
Client defined options are defined in the dsm.opt file. The IBM Spectrum Protect
server can also define some options in a client options set, or as part of the options
parameter of the schedule definition. The IBM Spectrum Protect server can also set
some options globally for all clients. By default, the client setting for these options
is honored. If the global override on the IBM Spectrum Protect server is set, the
client setting for the option is ignored. Defining client options as part of the
schedule definition is useful if you want to use specific options for a scheduled
action that differ from the option settings normally used by the client node, or are
different for each schedule the node executes.
The schedmode option controls the communication interaction between the IBM
Spectrum Protect client and server. There are two variations on the schedule mode:
client polling and server prompted. These variations are explained in the IBM
Spectrum Protect server documentation.
Evaluate schedule return codes in schedule scripts
You can use environment variables to determine the current IBM Spectrum Protect
return code before you run a script by using either the preschedulecmd or
postschedulecmd client options.
IBM Spectrum Protect provides the current value of the return code in the
environment variable called TSM_PRE_CMD_RC. The TSM_PRE_CMD_RC
variable is the current value of the IBM Spectrum Protect return code before you
run a schedule script. The value of the TSM_PRE_CMD_RC variable is not
necessarily the same as the return code issued by IBM Spectrum Protect following
the execution of the schedule script. The TSM_PRE_CMD_RC variable can be used
in schedule scripts to determine the current state of the schedule.
The TSM_PRE_CMD_RC variable is set on each of the following schedule options:
preschedule, prenschedule, postschedule, and postnschedule. TSM_PRE_CMD_RC
affects those schedules that have the ACTION=COMMAND option specified.
An example of the TSM_PRE_CMD_RC variable in use:
if [[ -n ${TSM_PRE_CMD_RC} ]] ; then
if [[ ${TSM_PRE_CMD_RC} == 0 ]] ; then
echo "The TSM_PRE_CMD_RC is 0"
elif [[ ${TSM_PRE_CMD_RC} == 4 ]] ; then
echo "The TSM_PRE_CMD_RC is 4"
elif [[ ${TSM_PRE_CMD_RC} == 8 ]] ; then
244
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
echo "The TSM_PRE_CMD_RC is 8"
elif [[ ${TSM_PRE_CMD_RC} == 12 ]] ; then
echo "The TSM_PRE_CMD_RC is 12"
else
echo "The TSM_PRE_CMD_RC is an unexpected value: ${TSM_PRE_CMD_RC}"
fi
else
echo "The TSM_PRE_CMD_RC is not set"
fi
Return codes from preschedulecmd and postschedulecmd
scripts
The return codes that you might see when you use the preschedulecmd and
postschedulecmd options are described.
v If the command specified by the preschedulecmd option ends with a nonzero
return code, IBM Spectrum Protect assumes that the command failed. In this
case, the scheduled event and any postschedulecmd or postnschedulecmd
command cannot run. The administrative query event command with
format=detailed option shows that the event failed with return code 12.
v If the command specified by the postschedulecmd option ends with a nonzero
return code, IBM Spectrum Protect considers the command to be failed. The
administrative query event command with format=detailed option shows that
the event completed with return code 8. The exception is if the scheduled
operation completed with a higher return code, in which case the higher return
code takes precedence. Therefore, if the scheduled operation completes with
return code 0 or 4 and the postschedulecmd command fails, the administrative
query event command shows that the event completed with return code 8. If the
scheduled operation completes with return code 12, that return code takes
precedence, and query event shows that the event failed with return code 12.
When you interpret the return code from a command, IBM Spectrum Protect
considers 0 to mean success, and anything else to mean failure. While this behavior
is widely accepted in the industry, it is not 100% guaranteed. For example, the
developer of the widget.exe command might exit with return code 3, if widget.exe
ran successfully. Therefore, it is possible that the preschedulecmd or
postschedulecmd command might end with a nonzero return code and still be
successful. To prevent IBM Spectrum Protect from treating such commands as
failed, you can wrap these commands in a script, and code the script so that it
interprets the command return codes correctly. The script should exit with return
code 0 if the command was successful; otherwise it should exit with a nonzero
return code. The logic for a script that runs widget.exe might look like this
example:
run ’widget.exe’
if lastcc == 3
exit 0
else
exit 1
Related reference:
“Postschedulecmd/Postnschedulecmd” on page 480
“Preschedulecmd/Prenschedulecmd” on page 483
Chapter 7. IBM Spectrum Protect scheduler overview
245
Client-acceptor scheduler services versus the traditional scheduler
services
You can configure the IBM Spectrum Protect client to manage the scheduler
process using the IBM Spectrum Protect client acceptor daemon.
The client acceptor daemon provides a light-weight timer which automatically
starts and stops the scheduler process as needed. Alternatively, the traditional
method keeps the IBM Spectrum Protect scheduler process running continuously.
Generally, using the client acceptor daemon to manage the scheduler is the
preferred method.
The following information is a comparison of the client acceptor daemon-managed
services and the traditional scheduler services methods.
Client acceptor daemon-managed services
v Defined using the managedservices schedule option and started with
client acceptor daemon services (dsmcad).
v The client acceptor daemon starts and stops the scheduler process as
needed for each scheduled action.
v Requires fewer system resources when idle.
v IBM Spectrum Protect client options and IBM Spectrum Protect server
override options are refreshed each time the client acceptor daemon
services start a scheduled backup.
v Cannot be used with SESSIONINITiation=SERVEROnly backups.
IBM Spectrum Protect traditional scheduler services
v Started with command dsmc sched command.
v Remains active, even after scheduled backup is complete.
v Requires higher use of system resources when idle.
v IBM Spectrum Protect client options and IBM Spectrum Protect server
override options are only processed once when dsmc sched is started; if
you delete an option from a client options set, you must restart the
scheduler so the scheduler is made aware of the deletion.
Tip: Restart the traditional scheduler periodically to free system resources
previously used by system calls.
Setting the client scheduler process to run as a background task and
start automatically at startup
You can configure the IBM Spectrum Protect client scheduler to run as a
background system task that starts automatically when your system is started.
About this task
You can complete this task whether you use the client acceptor to manage the
scheduler or whether you use the traditional method to start the scheduler client
scheduler.
For the scheduler to start unattended, you must enable the client to store its
password by setting the passwordaccess option to generate, and store the
password by running a simple client command such as dsmc query session. For
246
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
testing purposes, you can always start the scheduler in the foreground by running
dsmc sched from a command prompt (without a managedservices stanza set).
On Windows platforms, the scheduler and the client acceptor run as services. You
can create and manage these services by using either the setup wizard or the IBM
Spectrum Protect Client Service Configuration Utility, dsmcutil.exe.
v
To start the setup wizard, select Utilities > Setup Wizard in the backup-archive
GUI and select a Help me configure option for the appropriate service. Follow
the prompts to install, configure, and start the service.
v To start the Client Service Configuration Utility, open a command prompt
window and issue the following command to change to the directory that
contains dsmcutil.exe:
cd /d "c:\program files\tivoli\tsm\baclient"
Use dsmcutil to manage the client acceptor service or the scheduler service. Full
documentation on how to use dsmcutil is available by entering dsmcutil help.
The client scheduler can be managed by the client acceptor. When setting up
scheduler services to run with client acceptor management, two services must be
created: the scheduler service and the client acceptor service. When you install the
client acceptor service with dsmcutil.exe, use the /cadschedname: parameter to
identify which scheduler service the client acceptor manages. If you use the setup
wizard to install the scheduler, you can select the Use the client acceptor to
manage the scheduler check box, which automatically creates both services and
associates them.
Using the Client Service Configuration Utility, you can use either of the following
methods:
Client acceptor-managed method
1. In your client options file (dsm.opt), either set the managedservices
option to schedule or schedule webclient.
2. In your client options file (dsm.opt), set the passwordaccess option to
generate.
3. Create the scheduler service:
dsmcutil inst /name:"TSM Client Scheduler" /node:tsmclient1
/password:secret /autostart:no /startnow:no
4. Create the client acceptor and associate scheduler service with the client
acceptor:
dsmcutil inst CAD /name:"TSM Client Acceptor" /cadschedname:
"TSM Client Scheduler" /node:tsmclient1 /password:secret /autostart:yes
5. Manually start the client acceptor service:
net start "TSM Client Acceptor"
Traditional method
1. In your client options file (dsm.opt), either remove the managedservices
entirely (it defaults to webclient) or set it to webclient.
2. In your client options file (dsm.opt), set the passwordaccess option to
generate.
3. Create the scheduler service:
dsmcutil inst /name:"TSM Client Scheduler" /node:tsmclient1
/password:secret /autostart:yes
To increase the reliability of the client scheduler service on Windows, set the
services to automatically recover from a failure as follows:
Chapter 7. IBM Spectrum Protect scheduler overview
247
v Start the Windows services management console (Start > Settings > Control
Panel > Administrative Tools > Services)
v Right-click the TSM Client Scheduler service and select Properties.
v Click the Recovery tab.
v Define the recovery action as Restart the service for first, second, and
subsequent failures.
If you are using the client acceptor to manage the scheduler, you must set the
recovery properties for the TSM Client Acceptor service, but leave the recovery
settings for the TSM Client Scheduler service as Take No Action for the first,
second, and subsequent failures. The same recovery settings can also be defined to
increase the reliability of the TSM Journal Service.
Related reference:
“Cadlistenonport” on page 334
Examples: Display information about scheduled work
Schedules can be classic or enhanced, depending on how the interval to the next
execution is defined.
Classic schedules allow the period to be as small as an hour. Enhanced schedules
allow actions to be executed on specific days.
To view schedules that are defined for your client node, enter:
dsmc query schedule
The backup-archive client displays detailed information about all scheduled work
for your client node. Table 32 on page 249 displays sample classic query schedule
output.
248
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 32. Sample classic query schedule output
Schedule Name:
Description:
Schedule Style:
Action:
Options:
Objects:
Priority:
Next Execution:
Duration:
Period:
Day of Week:
Month:
Day of Month:
Week of Month:
Expire:
DAILY_INC
Daily System-wide backup
Classic
Incremental
QUIET
Schedule Name:
Description:
Schedule Style:
Action:
Options:
Objects:
Priority:
Next Execution:
Duration:
Period:
Day of Week:
Month:
Day of Month:
Week of Month:
Expire:
WEEKLY_INC
Weekly backup for project files
Classic
Incremental
QUIET
e: f:
1
60 minutes
8 Hours
7 Days
Friday
1
30 minutes
4 Hours
1 Day
Any
Never
Never
The schedule name, WEEKLY_INC, starts a weekly incremental backup on the e:
and f: drives.
The schedule name, DAILY_INC, starts a daily incremental backup. The next
incremental backup starts in 30 minutes. Because no objects are listed, the client
runs the incremental backup on your default domain. The schedule has no
expiration date.
To more accurately determine the status of scheduled events, the query schedule
output for an enhanced schedule, on IBM Spectrum Protect Version 5.3 client and
above, includes new fields. These fields are always displayed, even if it is a classic
schedule or a version 5.3 client session with a pre-version 5.3 server, but the new
fields are blank. Note that for a down-level (prior to verrsion 5.3) client, the server
reports the period as indefinite and the day of week as an illegal day. Table 33 on
page 250 displays sample enhanced query schedule output.
Chapter 7. IBM Spectrum Protect scheduler overview
249
Table 33. Sample enhanced query schedule output
Schedule Name: QUARTERLY_FULL
Description: Quarterly full backup
Schedule Style: Enhanced
Action: Selective
Options: subdir=yes
Objects: \* \volumes\fs2\*
Priority: 5
Next Execution: 1744 Hours and 26 Minutes
Duration: 1 Day
Period:
Day of Week: Friday
Month: March, June, September, December
Day of Month: Any
Week of Month: Last
Expire: Never
Display information about completed work
When you run the schedule command in the foreground, your screen displays
output from the scheduled commands.
Output is also directed to the dsmsched.log file in the installation directory unless
you change the directory and file name using the schedlogname option.
When you run the schedule command as a service, output from scheduled
commands displays in the application event log. Output is also directed to the
dsmsched.log file in the current directory unless you change the path and file
name using the schedlogname option. The amount of detail is determined by
whether verbose or quiet is set in the dsm.opt file. The scheduler service also posts
messages to the Windows event log.
After scheduled work is performed, check the schedule log to verify that all work
completed successfully.
When a scheduled command is processed the schedule log contains the following
entry:
Scheduled event eventname completed successfully
If the scheduled event does not complete successfully, you receive a message
similar to the following:
ANS1512E Scheduled event eventname failed. Return code = code.
The client indicates whether IBM Spectrum Protect successfully issued the
scheduled command associated with the eventname (action=command). No attempt
is made to determine the success or failure of the command. You can assess the
status of the command by evaluating the return code from the scheduled
command in the schedule log. The schedule log entry for the return code of the
command is prefaced with the following text:
Finished command. Return code is:
The schedule log continues to grow unless you prune it using the
schedlogretention option or specify a maximum size using the schedlogmax
option.
Related concepts:
“Specify scheduling options” on page 254
250
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Examples: event logs
The scheduler service logs information into the application event log and provides
an event identification (event ID) number for each event in the log. This topic
shows examples of events that are logged to the application event log.
Scheduler service
Event 4097 (informational message)
Example 1:
Event Type: Information
Event Source: AdsmClientService
Event Category: None
Event ID: 4097
Date: 10/31/2002
Time: 8:29:57 AM
User: DILE\Administrator
Computer: MIKEDILE
Description:
TSM 515 Scheduler halted.
Example 2:
Event Type: Information
Event Source: AdsmClientService
Event Category: None
Event ID: 4097
Date: 10/31/2002
Time: 8:29:57 AM
User: DILE\Administrator
Computer: MIKEDILE
Description:
Scheduler Terminated, service ending.
Example 3:
Event Type: Information
Event Source: AdsmClientService
Event Category: None
Event ID: 4097
Date: 10/31/2002
Time: 8:29:56 AM
User: DILE\Administrator
Computer: MIKEDILE
Description:
TSM Client Scheduler ’TSM 515 Scheduler’
Started.
Example 4:
Event Type: Information
Event Source: AdsmClientService
Event Category: None
Event ID: 4097
Date: 10/31/2002
Time: 8:29:56 AM
User: DILE\Administrator
Computer: MIKEDILE
Description:
Starting Scheduler.
Example 5:
Event
Event
Event
Event
Date:
Time:
Type: Information
Source: AdsmClientService
Category: None
ID: 4097
10/30/2002
8:06:09 PM
Chapter 7. IBM Spectrum Protect scheduler overview
251
User: DILE\Administrator
Computer: MIKEDILE
Description:
Incremental backup of volume ’\\MIKEDILE\C$’
Event 4098 (warning message)
Example 1:
Event Type: Warning
Event Source: AdsmClientService
Event Category: None
Event ID: 4098
Date: 10/31/2002
Time: 8:29:56 AM
User: DILE\Administrator
Computer: MIKEDILE
Description:
Error Initializing TSM Api, unable to verify
Registry Password, see dsierror.log.
Example 2:
Event Type: Warning
Event Source: AdsmClientService
Event Category: None
Event ID: 4098
Date: 9/20/2002
Time: 6:20:10 PM
User: DILE\Administrator
Computer: MIKEDILE
Description:
ANS1802E Incremental backup of ’\\mikedile\
c$’ finished with 3 failure
Event 4099 (error message)
Example 1:
Event Type: Error
Event Source: AdsmClientService
Event Category: None
Event ID: 4099
Date: 9/17/2002
Time: 6:53:13 PM
User: DILE\Administrator
Computer: MIKEDILE
Description:
Scheduler exited with a result code of 4.
Example 2:
Event Type: Error
Event Source: AdsmClientService
Event Category: None
Event ID: 4099
Date: 9/17/2002
Time: 6:27:19 PM
User: DILE\Administrator
Computer: MIKEDILE
Description:
ANS4987E Error processing ’\\mikedile\e$\
tsm520c\client\winnt\mak \dsmwin32.ncb’:
the object is in use by another process
Event 4100 (scheduler command message)
Event
Event
Event
Event
252
Type: Information
Source: AdsmClientService
Category: None
ID: 4100
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Date: 10/31/2002
Time: 8:29:56 AM
User: DILE\Administrator
Computer: MIKEDILE
Description:
Next Scheduled Event Obtained from Server
SNJEDS1 (MVS):
----------------------------------------Schedule Name: NIGHTLY_BACKUP
Action: Incremental
Objects: (none)
Options: (none)
Server Window Start: 19:00:00 on 10/31/2002
Event 4101 (backup or archive statistics)
Displays backup and archive statistics, which might be useful in
determining the success or failure of a command.
Event Type: Information
Event Source: AdsmClientService
Event Category: None
Event ID: 4101
Date: 10/30/2002
Time: 8:29:21 PM
User: DILE\Administrator
Computer: MIKEDILE
Description:
Backup/Archive Statistics for Schedule Backup
NIGHTLY_BACKUP :
--------------------------------------------Total number of objects inspected: 158,688
Total number of objects backed up: 2,486
Total number of objects updated: 0
Total number of objects rebound: 0
Total number of objects deleted: 0
Total number of objects expired: 12
Total number of objects failed: 0
Total number of bytes transferred: 1.15 GB
Data transfer time: 104.35 sec
Network data transfer rate: 11,564.84 KB/sec
Aggregate data transfer rate: 866.99 KB/sec
Objects compressed by: 100%
Elapsed processing time: 00:23:11
Event 4103 (backup-archive client service startup parameters)
Event Type: Information
Event Source: AdsmClientService
Event Category: None
Event ID: 4103
Date: 10/31/2002
Time: 8:29:56 AM
User: DILE\Administrator
Computer: MIKEDILE
Description:
Backup/Archive Client Service Startup
Parameters:
-------------------------------------Service Name : TSM 515 Scheduler
Last Update : Oct 14 2002
Client PTF Level : 5.1.5.2
Service Directory : D:\Program Files\
Tivoli\TSM515\baclient
Client Options File : E:\users\mikedile\
logfiles\dsm.opt
Client Node : MIKEDILE
Comm Method : (default or obtained from
client options file)
Chapter 7. IBM Spectrum Protect scheduler overview
253
Server : (default or obtained from client
options file)
Port : (default or obtained from client
options file)
Schedule Log : E:\users\mikedile\logfiles\
dsmsched.log
Error Log : E:\users\mikedile\logfiles\
dsmerror.log
MS Cluster Mode : (default or obtained
from client options file)
Journal based backup service events
4097:
4098:
4099:
4100:
4101:
4102:
Informational message
Warning message
Error message
Journal Based Backup service file monitor parameters
Journal Based Backup service database parameters
Journal Based Backup Service configuration parameters
Specify scheduling options
You can modify scheduling options in the client options file or the graphical user
interface (GUI).
However, if your administrator specifies a value for these options, that value
overrides the value in your client.
Related concepts:
“Scheduling options” on page 305
Enable or disable scheduled commands
You can use the schedcmddisabled option to disable the scheduling of commands
by the server.
Commands are scheduled by using the action=command option on the DEFINE
SCHEDULE server command.
The schedcmddisabled option does not disable the preschedulecmd and
postschedulecmd commands. However, you can specify preschedulecmd or
postschedulecmd with a blank or a null string to disable the scheduling of these
commands.
You can use the schedrestretrdisabled option to prevent the IBM Spectrum
Protect server administrator from executing restore or retrieve schedule operations.
You can use the srvprepostscheddisabled option to prevent the IBM Spectrum
Protect server administrator from executing pre-schedule and post-schedule
commands when performing scheduled operations.
You can use the srvprepostsnapdisabled option to prevent the IBM Spectrum
Protect server administrator from executing pre-snapshot and post-snapshot
commands when performing scheduled image snapshot backup operations.
Related reference:
“Schedcmddisabled” on page 509
“Schedrestretrdisabled” on page 518
“Srvprepostscheddisabled” on page 540
254
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
“Srvprepostsnapdisabled” on page 541
Change processing options used by the scheduler service
When you configure the IBM Spectrum Protect central-scheduling services (the
scheduler, the client acceptor, or the remote client agent), some of the processing
options that you specify are defined in the Windows registry.
The following options can also be specified in the client options file (dsm.opt).
v nodename
v httpport
v tcpserveraddress
v tcpport
v webports
When the client scheduler runs as a foreground process using the dsmc sched
command, the options in the client options file are used. However, when the
scheduler runs as a Windows service, the options in the registry are used instead.
If you are using the scheduler service and change an option in the dsm.opt file,
you must update the corresponding value in the registry as well.
To update the Windows registry value:
Use the Setup wizard in the client GUI. For more information, see
“Configuring the scheduler” on page 30.
Alternatively, you can use the dsmcutil utility to change the registry value.
For example: dsmcutil update scheduler /name: <service name> /node:
<new node name> /password: <new node password>.
Note: After updating the registry, you must restart the scheduler service
for the changes to take effect. If you are using client acceptor
daemon-managed scheduling this is not necessary because the scheduler is
restarted by the client acceptor daemon for each backup.
Manage multiple schedule requirements on one system
In certain situations it is preferable to have more than one scheduled activity for
each client system.
About this task
Normally, you can do this by associating a node with more than one schedule
definition. This is the standard method of running multiple schedules on one
system.
You must ensure that the schedule windows for each schedule do not overlap. A
single client scheduler process is not capable of executing multiple scheduled
actions simultaneously, so if there is overlap, the second schedule to start is missed
if the first schedule does not complete before the end of the startup window of the
second schedule.
Suppose that most of the drives on your client system must be backed up daily,
and that one drive containing critical data must be backed up hourly. In this case,
you would need to define two schedules to handle this requirement. To avoid
conflict between the hourly and daily backup schedule, the starttime of each
schedule needs to be varied.
Chapter 7. IBM Spectrum Protect scheduler overview
255
In certain cases, it is necessary to run more than one scheduler process on a
system. Multiple processes require a separate options file for each process and
must contain the following information:
v Define a unique node name for each process
v Specify unique schedule and error logs for each process
v When running in prompted mode, you must use the tcpclientport option to
specify a unique port for each process.
Note: When the scheduler runs as a service, processing options specified in the
Windows registry override the same options specified in the client options file.
The advantages of using multiple schedule processes:
v You can run more than one scheduled backup at the same time.
v You can specify different backup criteria for each schedule started, with the
client option file or IBM Spectrum Protect server override options.
The disadvantages of using multiple schedule processes:
v A unique file space for each node name on the IBM Spectrum Protect server is
created.
v When restoring the data, you must use the same node name associated with the
backup.
You must create a separate service for each schedule process. If you are using the
client acceptor daemon to manage the scheduler, a client acceptor daemon service
and schedule service are required for each schedule. The following is an example
of setting up two schedule processes to be managed by the client acceptor daemon:
dsmcutil inst /name:"TSM Client Scheduler1"
/optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt1"
/node:tsmcli_sched1 /password:secret /autostart:no /startnow:no
dsmcutil inst CAD /name:"TSM Client Acceptor1"
/optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt1"
/cadschedname:"TSM Client Scheduler1" /node:tsmcli_sched1 /password:secret
/autostart:yes
dsmcutil inst /name:"TSM Client Scheduler2"
/optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt2"
/node:tsmcli_sched2 /password:secret /autostart:no /startnow:no
dsmcutil inst CAD /name:"TSM Client Acceptor2"
/optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt2"
/cadschedname:"TSM Client Scheduler2" /node:tsmcli_sched2 /password:secret
/autostart:yes
Unique option files are required for each schedule instance, and must be identified
at the time of service creation:
Option file #1 (c:\program files\tivoli\tsm\baclient\dsm.opt1)
tcps
nodename
passwordaccess
schedlogname
errorlogname
schedmode
tcpclientport
domain
managedservices
tsmserv1.example.com
tsmcli_sched1
generate
"c:\program files\tivoli\tsm\baclient\dsmsched1.log"
"c:\program files\tivoli\tsm\baclient\dsmerror1.log"
prompted
1507
h:
schedule
Option file #2 (c:\program files\tivoli\tsm\baclient\dsm.opt2)
256
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
tcps
nodename
passwordaccess
schedlogname
errorlogname
schedmode
tcpclientport
domain
managedservices
tsmserv1.example.com
tsmcli_sched2
generate
"c:\program files\tivoli\tsm\baclient\dsmsched2.log"
"c:\program files\tivoli\tsm\baclient\dsmerror2.log"
prompted
1508
i:
schedule
Related concepts:
“Change processing options used by the scheduler service” on page 255
Chapter 7. IBM Spectrum Protect scheduler overview
257
258
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chapter 8. Client return codes
The backup-archive command-line interface and the scheduler exit with return
codes that accurately reflect the success or failure of the client operation.
Scripts, batch files, and other automation facilities can use the return code from the
command-line interface. For operations that use the IBM Spectrum Protect
scheduler, the return codes are shown in the output of the QUERY EVENT
administrative command.
In general, the return code is related to the highest severity message during the
client operation.
v If the highest severity message is informational (ANSnnnnI), then the return
code is 0.
v If the highest severity message is a warning (ANSnnnnW), then the return code
is 8.
v If the highest severity message is an error (ANSnnnnE or ANSnnnnS), then the
return code is 12.
An exception to these rules is made when warning or error messages indicate that
individual files could not be processed. For files that cannot be processed, the
return code is 4. Examine the dsmerror.log file to determine the cause of errors
that occur during client operations. Errors that occur during scheduled events are
recorded in the dsmsched.log file.
Table 34 describes the return codes and their meanings.
Table 34. Client return codes and their meanings
Code
Explanation
0
All operations completed successfully.
4
The operation completed successfully, but some files were not processed.
There were no other errors or warnings. This return code is common. Files
are not processed for various reasons; the following reasons are the most
common.
v The file satisfies an entry in an exclude list. Excluded files generate log
entries only during selective backups.
v The file was in use by another application and could not be accessed by
the client.
v The file changed during the operation to an extent prohibited by the copy
serialization attribute. See “Copy serialization attribute” on page 265.
8
The operation completed with at least one warning message. For scheduled
events, the status is Completed. Review the dsmerror.log file (and
dsmsched.log for scheduled events) to determine what warning messages
were issued and to assess their impact on the operation.
12
The operation completed with at least one error message (except for error
messages for skipped files). For scheduled events, the status is Failed.
Review the dsmerror.log file (and dsmsched.log for scheduled events) to
determine what error messages were issued and to assess their impact on the
operation. Generally, this return code means that the error was severe enough
to prevent the successful completion of the operation. For example, an error
that prevents an entire drive from being processed yields return code 12.
© Copyright IBM Corp. 1993, 2017
259
Table 34. Client return codes and their meanings (continued)
Code
Explanation
other
For scheduled operations where the scheduled action is COMMAND, the
return code is the return code from the command that was run. If the return
code is 0, the status of the scheduled operation is Completed. If the return
code is nonzero, then the status is Failed.
Some commands might issue a nonzero return code to indicate success. For
these commands, you can avoid a Failed status by wrapping the command
in a script that starts the command, interprets the results, and exits. The script
should produce return code 0 if the command was successful, or a nonzero
return code if the command failed. Then, ask your IBM Spectrum Protect
server administrator to modify the schedule definition to run your script
instead of the command.
The return code for a client macro is the highest return code that is issued among
the individual commands that comprise the macro. For example, suppose a macro
consists of these commands:
selective c:\MyTools\* -subdir=yes
incremental c:\MyPrograms\TestDriver\* -subdir=yes
archive e:\TSM\* -subdir=yes
If the first command completes with return code 0, and the second command
completes with return code 8, and the third command completed with return code
4, the return code for the macro is 8.
For more information about the QUERY EVENT command, see the IBM Spectrum
Protect server documentation.
260
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chapter 9. Storage management policies
Storage management policies are rules your administrator defines in order to
manage your backups and archives on the server.
Your data is associated (or bound) to these policies; then when the data is backed
up or archived, it is managed according to policy criteria. Policy criteria include a
policy domain, a policy set, a management class, and a copy group.
Policies determine:
v Whether a file is eligible for backup or archive services.
v How many backup versions to keep.
v How long to keep inactive backup versions and archive copies.
v Where to place the copies in storage.
v For incremental backup, policies also determine:
– How frequently a file can be backed up.
– Whether a file must change before it is backed up again.
This topic explains:
v Policy criteria (policy domains, policy sets, copy groups, and management
classes).
v How to display policies.
v How your data is associated with policies.
Policy domains and policy sets
A policy domain is a group of clients with similar requirements for backing up and
archiving data.
Policy domains contain one or more policy sets. An administrator uses policy
domains to manage a group of client nodes in a logical way.
For example, a policy domain might include:
v A department, such as Accounting.
v A physical location, such as a particular building or floor.
v A local area network, such as all clients associated with a particular file server.
IBM Spectrum Protect includes a default policy domain named Standard. At first,
your client node might be associated with the default policy domain. However,
your administrator can define additional policy domains if there are groups of
users with unique backup and archive requirements.
A policy set is a group of one or more management classes. Each policy domain can
hold many policy sets. The administrator uses a policy set to implement different
management classes based on business and user needs. Only one of these policy
sets can be active at a time. This is called the active policy set. Each policy set
contains a default management class and any number of additional management
classes.
© Copyright IBM Corp. 1993, 2017
261
Management classes and copy groups
A management class is a collection of backup and archive copy groups that
establishes and contains specific storage management requirements for backing up
and archiving data.
An administrator can establish separate management classes to meet the backup
and archive requirements for different kinds of data, such as:
v System data that is critical for the business.
v Application data that changes frequently.
v Report data that Management reviews monthly.
v Legal information that must be retained indefinitely, requiring a large amount of
disk space.
Most of the work you do with storage management policies is with management
classes. Each file and directory that you back up, and each file that you archive, is
associated with (or bound to) a management class, as follows:
v If your data is not associated with a management class, IBM Spectrum Protect
uses the default management class in the active policy set.
v When backing up directories, you can specify a management class with an
include statement or the dirmc option. If you do not specify a management class,
IBM Spectrum Protect uses the management class in the active policy set
specifying the longest "Retain Only" retention period. If there are multiple
management classes that meet this criteria, IBM Spectrum Protect uses the last
one found, in alphabetical order.
v For archiving directories, you can specify a management class with an
include.archive statement or the archmc option. If you do not specify a
management class, the server assigns the default management class to the
archived directory. If the default management class has no archive copy group,
the server assigns the management class that currently has the archive copy
group with the shortest retention time.
You can use include statements in your include-exclude list to associate files with
management classes. In your client options file, you can associate directories with a
management class, using the dirmc option.
Within a management class, the specific backup and archive requirements are in
copy groups. Copy groups define the specific storage management attributes that
describe how the server manages backed up or archived data. Copy groups
include both backup copy groups and archive copy groups. A management class can
have one backup copy group, one archive copy group, both, or neither.
A backup copy group contains attributes that are used during the backup process to
determine:
v How many days must elapse before a file is backed up again.
v How a file is processed during a backup if it is in use.
It also contains attributes to manage the backup versions of your files on the
server. These attributes control:
v On which media type the server stores backup versions of your files and
directories.
v How many backup versions the server keeps of your files and directories.
v How long the server keeps backup versions of your files and directories.
v How long the server keeps inactive backup versions.
v How long the last remaining inactive version of a file is kept.
262
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
An archive copy group contains attributes that control:
v Whether a file is archived if it is in use
v On which media type the server stores archived copies of your files
v How long the server keeps archived copies of your files
Related concepts:
“Select a management class for files” on page 267
“Retention grace period” on page 270
Display information about management classes and copy groups
You can display policy information with the command-line interface or with a
graphical user interface.
On a graphical user interface, click View policy information from the Utilities
menu. The Policy information window displays the available management classes.
On a command line, use the query mgmtclass command to view the available
management classes. The detail option provides more information.
Table 35 shows the default values for the backup and archive copy groups in the
standard management class.
Table 35. Default attribute values in the standard management class
Attribute
Backup default
Archive default
Copy group name
Standard
Standard
Copy type
Backup
Archive
Copy frequency
0 days
CMD (Command)
Versions data exists
Two versions
Does not apply
Versions data deleted
One version
Does not apply
Retain extra versions
30 days
Does not apply
Retain only version
60 days
Does not apply
Copy serialization
Shared static
Shared static
Copy mode
Modified
Absolute
Copy destination
Backuppool
Archivepool
Retain versions
Does not apply
365 days
Lan free
Destination
No
Deduplication enabled
No
No
Copy group name attribute
The copy group name attribute is the name of the copy group. The default value for
both backup and archive is standard.
Copy type attribute
The copy type attribute is the type of the copy group. The value for backup is
always backup, and the value for archive is always archive.
Chapter 9. Storage management policies
263
Copy frequency attribute
The copy frequency attribute is the minimum number of days that must elapse
between successive incremental backups. Use this attribute during a full
incremental backup.
Copy frequency works with the mode parameter. For example, if frequency=0 and
mode=modified, a file or directory is backed up only if it changed since the last
incremental backup. If frequency=0 and mode=absolute, an object is backed up
every time you run an incremental backup against it. If frequency=0 and
mode=absolute, changes and number of days since the last backup do not affect the
current backup operation. The frequency attribute is not checked for selective
backups.
For archive copy groups, copy frequency is always CMD (command). There is no
restriction on how often you archive an object.
Copy frequency is ignored during a journal-based backup.
Journal-based incremental backup differs from the traditional full incremental
backup because IBM Spectrum Protect does not enforce non-default copy
frequencies (other than 0).
Versions data exists attribute
The versions data exists attribute specifies the maximum number of different backup
versions retained for files and directories.
If you select a management class that permits more than one backup version, the
most recent version is called the active version. All other versions are called inactive
versions. If the maximum number of versions permitted is five, and you run a
backup that creates a sixth version, the oldest version is deleted from server
storage.
Versions data deleted attribute
The versions data deleted attribute specifies the maximum number of different
backup versions retained for files and directories that you deleted.
This parameter is ignored until you delete the file or directory.
If you delete the file or directory, the next time you run an incremental backup, the
active backup version is changed to inactive. The IBM Spectrum Protect server
deletes the oldest versions in excess of the number specified by this parameter.
The expiration date for the remaining versions is based on the retain extra versions
and retain only version parameters.
Retain extra versions attribute
The retain extra versions attribute specifies how many days all but the most recent
backup version is retained.
The most recent version is the active version, and active versions are never erased.
If Nolimit is specified, then extra versions are kept until the number of backup
versions exceeds the versions data exists or versions data deleted parameter settings. In
this case, the oldest extra version is deleted immediately.
264
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Retain only version attribute
The retain only version attribute specifies the number of days the last remaining
inactive version of a file or directory is retained.
If Nolimit is specified, the last version is retained indefinitely.
This parameter goes into effect during the next incremental backup after a file is
deleted from the client system. Any subsequent updates to this parameter will not
affect files that are already inactive. For example: If this parameter is set to 10 days
when a file is inactivated during an incremental backup, the file is deleted from
the server in 10 days.
Copy serialization attribute
The copy serialization attribute determines whether a file can be in use during a
backup or archive, and what to do if it is.
The value for this attribute can be one of the following:
v Static. A file or directory must not be modified during a backup or archive. If
the object is changed during a backup or archive attempt, it is not backed up or
archived.
v Shared static. A file or directory must not be modified during backup or
archive. The client attempts to perform a backup or archive as many as four
additional times, depending on the value specified on the changingretries
option in your options file. If the object is changed during every backup or
archive attempt, it is not backed up or archived.
v Dynamic. A file or directory is backed up or archived on the first attempt
regardless of whether it changes during a backup or archive.
v Shared dynamic. A file or directory is backed up or archived regardless of
whether it changes during a backup or archive. The client attempts to back up
or archive as many as four additional times. The number of attempts depend on
the value that was specified on the changingretries option in your options file,
without the file changing during the attempt. The file is backed up or archived
on the last try even if it has changed.
If you select a management class that permits a file to be backed up or archived
while it is in use, the backup version or archived copy that is stored on the
server might be a fuzzy copy. A fuzzy copy is a backup version or archived copy
that does not accurately reflect what is currently in the file. It might contain
some, but not all, of the changes. If that is not acceptable, select a management
class that creates a backup version or archive copy only if the file does not
change during a backup or archive. When you use static serialization,
applications cannot open a file for write access while the file is being backed up.
If you restore or retrieve a file that contains a fuzzy copy, the file might not be
usable. Do not use dynamic or shared dynamic serialization to back up files
unless you are certain that a fuzzy copy that is restored is usable.
Important: Be careful when you select a management class containing a copy
group that specifies shared dynamic or serialization dynamic backup.
Related concepts:
“Open file support for backup operations” on page 127
Related tasks:
“Configuring Open File Support” on page 78
Related reference:
Chapter 9. Storage management policies
265
“Snapshotproviderimage” on page 536
Copy mode parameter
The copy mode parameter determines whether a file or directory is considered for
incremental backup regardless of whether it changed or not since the last backup.
The client does not check the mode parameter when it runs selective backups.
The value for this parameter can be one of the following settings:
modified
The object is considered for incremental backup only if it has changed
since the last backup. An object is considered changed if any of the
following conditions are true:
v The date or time of the last modification is different.
v The size is different.
v The attributes, except for the archive attribute, are different.
v If only the metadata changes (such as access permissions), the client
might back up only the metadata.
absolute
The object is considered for incremental backup regardless of whether it
changed since the last backup. For archive copy groups, the mode is
always absolute, indicating that an object is archived regardless of whether
it changed since the last archive request.
Related reference:
“Absolute” on page 318
Copy destination attribute
The copy destination attribute names the destination where backups or archives are
stored.
The destination can be either a storage pool of disk devices or a storage pool of
devices that support removable media, such as tape.
Retain versions attribute
The retain versions attribute specifies the number of days an archived file remains
in storage.
When the specified number of days elapse for an archived copy of a file, it is
deleted from server storage.
Deduplicate data attribute
The deduplicate data attribute specifies whether redundant data is transferred to the
IBM Spectrum Protect server during backup and archive processing.
Related concepts:
“Client-side data deduplication” on page 48
Related reference:
“Deduplication” on page 356
“Enablededupcache” on page 384
“Exclude options” on page 395
266
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Select a management class for files
If the default management class meets the backup and archive requirements for all
the files on your workstation, it is not necessary to take any action to associate
your files with that management class. This is done automatically when you back
up or archive your files.
When selecting a different management class for your files, consider these
questions:
v Does the management class contain a backup copy group?
If you attempt to back up a file associated with a management class that does
not contain a backup copy group, the file is not backed up.
v Does the management class contain an archive copy group?
You cannot archive a file associated with a management class that does not
contain an archive copy group.
v Does the backup copy group contain attributes that back up your files often
enough?
Mode and frequency work together to control how often a file is backed up
when you use incremental backup. These attributes are not checked for selective
backup.
v What serialization method does the copy group use?
The serialization method determines how IBM Spectrum Protect functions when
a file changes while it is being backed up.
v Does the backup copy group specify an adequate number of backup versions to
keep, along with an adequate length of time to keep them?
v Does the archive copy group specify an adequate length of time to keep
archived copies of files?
Related concepts:
“Copy serialization attribute” on page 265
Assign a management class to files
A management class defines when your files are included in a backup, how long
they are kept on the server, and how many versions of the file the server should
keep.
The server administrator selects a default management class. You can specify your
own management class to override the default management class.
To assign a management class other than the default to directories, use the dirmc
option in your options file.
You can assign a management class for a file or file group by using an include
statement in your options file. You can also assign a management class by using an
include statement in include-exclude file specified by the inclexcl option.
Management class names are not case-sensitive.
Using the command-line client, to associate all files in the costs directory with the
management class named budget, you would enter:
include c:\adsm\proj2\costs\* budget
To specify a management class named managall to use for all files to which you do
not explicitly assign a management class, enter the following:
Chapter 9. Storage management policies
267
include ?:\...\* managall
The following examples show how to assign a management class to files:
exclude
include
include
include
include
?:\...\*.sno
c:\winter\...\*.ice
mcweekly
c:\winter\december\*.ice mcdaily
c:\winter\january\*.ice mcmonthly
c:\winter\february\white.sno
Processing follows these steps:
1. The file white.sno in the february directory in the winter directory is backed
up following bottom-up processing rules. Because you did not specify a
management class on this statement, the file is assigned to the default
management class.
2. Any file with an extension of ice in the january directory is assigned to the
management class named mcmonthly.
3. Any file with an extension of ice in the december directory is assigned to the
management class named mcdaily.
4. Any other files with an extension of ice in any directory under the winter
directory are assigned to the management class named mcweekly.
5. Any file with an extension of sno in any directory is excluded from backup.
The exception to this rule is white.sno in the february directory, which is in the
winter directory.
To specify your own default management class mgmt_class_name for files that are
not explicitly included, put the following statement at the top of your include list:
include ?:\...\* mgmt_class_name
Related reference:
“Dirmc” on page 363
“Include options” on page 426
Override the management class for archived files
When you archive a file, you can override the assigned management class using
the a graphical user interface (GUI), or by using the archmc option on the archive
command.
Overriding the management class using the GUI is equivalent to using the archmc
option on the archive command. To use the GUI, press the Options button on the
archive tree to override the management class and select a different management
class.
On the command line, to associate the file budget.jan with the management class
ret2yrs, enter this command:
dsmc archive –archmc=ret2yrs c:\plan\proj1\budget.jan
Select a management class for directories
If the management class in your active policy set containing the longest "Retain
only version" (RETONLY) setting meets your backup requirements for directories,
it might not be necessary to take any action to associate directories with that
management class. The management class association is done automatically when
it backs up your directories.
268
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
If there is more than one management class with the longest RETONLY setting, the
IBM Spectrum Protect client selects the management class whose name is last in
alphabetical order.
If the default management class does not meet your requirements, select a
management class with an adequate retention period specified by the retain only
version parameter. For example, if the management class happens to back up data
directly to tape, but you want your directory backups to go to disk, you must
choose a different management class. You should keep directories at least as long
as you keep the files associated with those directories.
For backup directories, use the dirmc option to specify the management class to
which directories are bound.
For archive directories, use the archmc option with the archive command.
You can use these methods to view the available management classes and their
attributes:
v GUI or web client: Select View Policy Information from the Utilities menu.
v Command-line client: Run dsmc query mgmtclass -detail.
Note: During expiration processing on the IBM Spectrum Protect server, if an
archived directory is eligible for expiration, the server checks if any existing
archived files require the archived directory to remain. If so, the archived directory
is not expired and the backup-archive client updates the insert date on the
archived directory to ensure that the directory is not expired before the files under
it.
Bind management classes to files
Binding associates a file with a management class.
When you back up a file for the first time, IBM Spectrum Protect binds it to either
the default management class or the management class specified in your
include-exclude list.
If the backup copy group for the management class specifies keeping multiple
backup versions of the file, and you request multiple backups, the server always
has one active backup version (the current version) and one or more inactive
backup versions of the file. All backup versions of a file are bound to the same
management class and are managed based on the attributes in the backup copy
group.
When you archive a file for the first time, IBM Spectrum Protect binds it to the
default management class, to the management class specified in your
include-exclude list, or to a management class you specify when modifying your
archive options during an archive.
Archived files are never rebound to a different management class. If you change
the management class for a file using an include.archive statement, the archmc
option, or through the backup-archive client GUI, any previous copies of the file
that you archived remain bound to the management class specified when you
archived them.
Chapter 9. Storage management policies
269
If a file is deleted on the client system then that inactive objects of the file are not
rebound.
For information about how to associate files and directories with management
classes, see the IBM Spectrum Protect server documentation.
Rebind backup versions of files
Rebinding associates a file or a logical volume image with a new management class.
Backups of files are bound again to a different management class in the following
conditions. In each condition, the files (active and inactive) are not bound again
until the next backup.
v You specify a different management class in an Include statement to change the
management class for the file. The backups are managed based on the old
management class until you run another backup.
v Your administrator deletes the management class from your active policy set.
The default management class is used to manage the backup versions when you
back up the file again.
v Your administrator assigns your client node to a different policy domain and the
active policy set in that domain does not have a management class with the
same name. The default management class for the new policy domain is used to
manage the backup versions.
For information about how to associate files and directories with management
classes, see the IBM Spectrum Protect server documentation.
Retention grace period
IBM Spectrum Protect also provides a backup retention grace period and an archive
retention grace period to help protect your backup and archive data when it is
unable to rebind a file to an appropriate management class.
The backup retention grace period is in the following cases:
v You change the management class for a file, but neither the default management
class nor the new management class contain a backup copy group.
v The management class to which a file is bound no longer exists, and the default
management class does not contain a backup copy group.
The backup retention grace period, defined in your policy domain, starts when you
run an incremental backup. The default is 30 days. However, your administrator
can lengthen or shorten this period.
When the IBM Spectrum Protect server manages a file using the backup retention
grace period, it does not create any new backup versions of the file. All existing
backup versions of the file expire 30 days (or the number of days specified in your
policy domain) from the day they are marked inactive.
Archive copies are never rebound because each archive operation creates a
different archive copy. Archive copies remain bound to the management class
name specified when the user archived them. If the management class to which an
archive copy is bound no longer exists or no longer contains an archive copy
group, the server uses the default management class. If you later change or replace
the default management class, the server uses the updated default management
270
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
class to manage the archive copy. If the default management class does not contain
an archive copy group, the server uses the archive retention grace period specified
for the policy domain.
Event-based policy retention protection
All management classes with an archive copy group must specify a retention
period, for example, the number of days that an archived object is stored on the
server before being deleted.
Event-based policy provides the option of beginning the retention period either at
the time the object is archived or at a later date when an activation event is sent to
the server for that object.
Setting the copy group value RETINIT=CREATE starts the data retention period when
the file is archived. Using the copy group value RETINIT=EVENT starts the data
retention period when the server is notified that the event has occurred.
The following example demonstrates this concept:
The user has two files, create.file and event.file. The user has available two
management classes; CREATE, with RETINIT=CREATE, and EVENT,
with RETINIT=EVENT. Both management classes have a 60-day retention period. The
user, on the same day, archives both files:
dsmc archive create.file -archmc=CREATE
dsmc archive event.file -archmc=EVENT
Ten days later, the user issues the set event -type=hold command for the
create.file file, so the file cannot be deleted. On the same day the user issues the
set event -type=activate for the event.file file. At this time, create.file has 50
days left on its retention period, and event.file has 60 days. If no other action is
taken, create.file remains on the server forever, and event.file is expired 70
days after it was created (60 days after its event occurred). However, if 20 days
after the initial archive, the user issues set event -type=release for the create.file
file. Thirty days of its retention period have passed, so the file is expired in 30
days (the hold does not extend the retention period).
For information about the RETINIT copy group value, see the IBM Spectrum
Protect server documentation.
Related reference:
“Set Event” on page 781
Archive files on a data retention server
Up to this point, there is no difference between archiving files on a normal server
or a data retention server.
The following example demonstrates the differences between the two servers, and
what can be done at day 5:
If the files were archived on a non-data retention server, the user can issue the
delete archive create.file event.file command and both files are deleted. If the files
were archived on a data retention server, the same command fails both files. The
data retention server forces the user to keep archives until the stated retention
criteria are met.
Chapter 9. Storage management policies
271
Now here is the difference at day 15 (after the hold):
The delete archive create.file event.file command on the non-data retention server
now deletes event.file, but returns a cannot delete error for create.file because it
is in hold status. That same command to a data retention server still rejects the
deletion of both files.
272
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chapter 10. IBM Spectrum Protect Client Service
Configuration Utility
The following client services can be installed when you install the backup-archive
client, or when you use the IBM Spectrum Protect Client Service Configuration
Utility after the backup-archive client is installed:
v Backup-Archive Scheduler Service
v Client Acceptor Service
v Remote Client Agent Service
v Journal Engine Service
For more information about using the IBM Spectrum Protect Client Service
Configuration Utility to install client services, see the related information about
using the dsmcutil command.
Related concepts:
“dsmcutil command” on page 277
Install the backup-archive scheduler service
You can use either the backup-archive client GUI or the IBM Spectrum Protect
Client Service Configuration Utility to install the scheduler.
About this task
v From the backup-archive client GUI, click Utilities, and then click Setup Wizard.
Select the Help me configure the Client Scheduler option.
v If you have an account that belongs to the Administrator/Domain Administrator
group, you can use the IBM Spectrum Protect Client Service Configuration
Utility to configure client services on both local and remote Windows
workstations.
Using the Client Service Configuration Utility (Windows)
This section provides the steps for using the Client Service Configuration Utility to
automate backups, manage existing scheduler services, create a new scheduler, and
associate a client acceptor to manage the scheduler.
About this task
This example illustrates the use of the IBM Spectrum Protect scheduler.
When the backup-archive client is registered with the IBM Spectrum Protect server,
the procedure involves the following steps:
Procedure
1. On the server:
a. Define a schedule for the policy domain to which the backup-archive client
is registered.
b. Associate the backup-archive client node to the defined schedule.
2. On the backup-archive client:
a. Install the scheduler as a Windows service for the backup-archive client.
© Copyright IBM Corp. 1993, 2017
273
b. Start the scheduler service installed for the backup-archive client.
Examples: Automating backups
Use the following sample procedure to automate your backups.
About this task
This example uses the following assumptions:
v The backup-archive client is registered to the IBM Spectrum Protect server with
a node name of mars and a password of marspswd in policy domain bacliwnt.
v The event to be scheduled is a daily incremental backup of file systems on client
workstations. The backup begins between 9:00 and 9:15 PM.
v The backup-archive client is installed to the c:\program files\tivoli\tsm\
baclient directory.
v The communication parameters in the backup-archive client options file
(dsm.opt) are appropriate for the IBM Spectrum Protect server.
Procedure
v On the server:
1. Enter the following command on the server console or from an
administrative client to define the schedule: def sched bacliwnt
wnt_daily_incr desc="Daily Incremental Backup" priority=2
starttime=21:00 duration=15 durunits=minutes period=1 perunits=days
dayofweek=any
The administrative client does not have to be running on the same system as
the IBM Spectrum Protect server.
The following message is displayed:
ANR2500I Schedule WNT_DAILY_INCR defined in policy domain BACLIWNT.
2. To associate the backup-archive client to this schedule, issue the following
command: define association bacliwnt wnt_daily_incr mars.
The following message is displayed:
ANR2510I Node MARS associated with schedule WNT_DAILY_INCR in policy domain
BACLIWNT.
A schedule that performs an incremental backup is defined on the IBM
Spectrum Protect server. The schedule starts around 9:00 PM. The schedule is
re-executed once a day and can start on any day of the week. If you want to
confirm that the schedule and association are set correctly, you can use the
Query Schedule command.
v On the backup-archive client:
This example assumes that you installed the backup-archive client in the
c:\program files\tivoli\tsm\baclient directory. It also assumes that the
options files in each of these directories are updated so that the communication
parameters point to the IBM Spectrum Protect server.
1. Log in using an account with administrative privileges.
2. Open a command prompt window and issue the following command: cd /d
"c:\program files\tivoli\tsm\baclient"
If the path contains a space, for example c:\program files\tivoli\tsm\
baclient, enclose the name in double quotation marks.
3. In the window, issue the following command: dsmcutil inst scheduler
/name:"TSM Client Scheduler" /node:mars /password:marspswd
274
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
/clientdir:"c:\program files\tivoli\tsm\baclient" /optfile:"c:\program
files\tivoli\tsm\baclient\dsm.opt" /autostart:yes
Your system is now ready to run automatic daily incremental backups. The
/autostart:yes option specifies that the scheduler service starts automatically
each time the system is rebooted. You can use the /startnow:[Yes|No] option
to specify whether to start the scheduler service after the command is
executed; the default is Yes.
If you specify /startnow:No you must start the service manually using the
Services Control Panel, or issue the following command: net start "TSM
Client Scheduler"
4. The scheduler uses the backup-archive client options file to validate the node
and password, and to contact the server for schedule information. This
example assumes that the dsm.opt file is updated so that the communication
parameters point to the IBM Spectrum Protect server.
If you see the following message:
A communications error occurred connecting to the IBM Spectrum Protect server.
Ensure that the options file contains entries that point to the correct IBM
Spectrum Protect server. Also, ensure that the server is running.
Use the dsmcutil update command to correct one of the parameters that was
incorrectly specified with the dsmcutil install command. For example, to
update the client directory and options file for the specified scheduler
service, enter: dsmcutil update scheduler /name:"TSM Central Scheduler
Service" /clientdir:"c:\program files\tivoli\tsm\baclient"
/optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt"
Then, reissue the net start "TSM Client Scheduler" command.
Results
Note:
v If any changes that affect the scheduler service are made to the backup-archive
client options file, the scheduler service must be restarted. If you are using client
acceptor-managed scheduling, the restart is not necessary since the scheduler is
restarted by the client acceptor for each backup and the changes are picked up.
For example, the IBM Spectrum Protect server address or the schedule mode
was changed in the options file. You can stop and restart the scheduler service
by issuing the following commands: net stop "TSM Client Scheduler" and then
net start "TSM Client Scheduler".
v The dsmsched.log file contains status information for the IBM Spectrum Protect
scheduler service. In this example, the file is located in this path: c:\program
files\tivoli\tsm\baclient\dsmsched.log. You can override this file name by
specifying the schedlogname option in the options file, dsm.opt.
v Output from scheduled commands is sent to the log file. After scheduled work
is performed, check the log to ensure that the work is completed successfully.
When a scheduled command is processed, the schedule log might contain the
following entry: Scheduled event eventname completed successfully.
This entry is merely an indication that the scheduled command that is associated
with the eventname was successfully issued. No attempt is made to determine the
success or failure of the command. You can assess the success or failure of the
command by evaluating the return code from the scheduled command in the
schedule log. The schedule log entry for the return code of the command is
prefaced with the following text: Finished command. Return code is:
Related tasks:
Chapter 10. Client Service Configuration Utility
275
“Dsmcutil valid options” on page 287
Related reference:
“Query Schedule” on page 725
Examples: Configuring the client acceptor to manage an existing
scheduler service
You can configure the client service configuration utility to use scheduler services.
About this task
This example assumes that the scheduler service name is TSM Central Scheduler
Service and the client acceptor service name is TSM Client Acceptor, which are
the default names. You can use the dsmcutil /name option to specify different
names.
To configure the client acceptor to manage an existing scheduler service:
Procedure
1. Stop the scheduler service and the client acceptor as follows:
a. Run the following command: dsmcutil stop /name:"tsm central scheduler
service"
b. Then, run the following command: dsmcutil stop /name:"tsm client
acceptor"
2. Set the managedservices option to schedule in the client options file (dsm.opt).
3. Update the scheduler service so that it does not start automatically after a
reboot: dsmcutil update /name:"tsm central scheduler service"
/autostart:no
4. Associate the scheduler service with the client acceptor: dsmcutil update cad
/name:"tsm client acceptor" /cadschedname:"tsm central scheduler
service" /autostart:yes
If this command is successful, the dsmwebcl.log file includes this message:
Command will be executed in 1 minute. After 1 minute, the client acceptor
starts the scheduler and you see information about the next scheduled event in
the dsmwebcl.log file.
Related concepts:
“Dsmcutil commands: Required options and examples” on page 278
Related tasks:
“Dsmcutil valid options” on page 287
Creating a new scheduler and associating a client acceptor to
manage the scheduler
Use step-by-step instructions to create a new scheduler and associate a client
acceptor to manage the scheduler.
Procedure
Complete the following steps to create a new scheduler and associate a client
acceptor:
1. Set the managedservices option to schedule in the client options file (dsm.opt).
2. Create the scheduler service:
dsmcutil install scheduler /name:"NEW_SCHEDULE_NAME" /node:yournode
/password:xxxxx /startnow:no
276
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
|
Do not use the /autostart:yes option when you install a scheduler that is
managed by the client acceptor.
3. Create the client acceptor service. The default name, tsm client acceptor, is
used:
dsmcutil install cad /node:yournode /password:xxxxx /autostart:yes
/startnow:no
4. Associate the scheduler with the client acceptor:
dsmcutil update cad /name:"tsm client acceptor"
/cadschedname:"NEW_SCHEDULE_NAME"
|
|
5. Start the client acceptor:
dsmcutil start /name:"tsm client acceptor"
Results
The client acceptor and scheduler start as described. Since the client acceptor is
controlling the scheduler, you do not see the scheduler running as a service, either
through the Services applet or the NET START command. To stop the scheduler,
you must stop the client acceptor service.
dsmcutil command
The IBM Spectrum Protect Client Service Configuration Utility, dsmcutil, can be
used to install backup-archive client services on local and remote Windows
workstations.
You can use the dsmcutil command to install the following client services:
v Backup-Archive Scheduler Service
v Client Acceptor Service
v Remote Client Agent Service
v Journal Engine Service
The Client Service Configuration Utility must be run from an account that belongs
to the Administrator/Domain Administrator group. The syntax for the command is
as shown in the following text:
►► dsmcutil
command
SCHEDuler
service
CAD
JOURnal
REMOTEagent
►◄
Note: Options that you specify with dsmcutil commands override option that you
specify in your options file (dsm.opt).
The account that runs the utility must have the appropriate user rights for
installing services and updating the Windows Registry on the target workstation.
If a remote workstation is specified, the account must be authorized to connect to
the Windows Registry of the specified workstation.
Note: For the commands and options that are documented here, the minimum
abbreviation that you can type is shown in uppercase letters.
Related concepts:
Chapter 10. Client Service Configuration Utility
277
Chapter 2, “Configure the IBM Spectrum Protect client,” on page 21
Dsmcutil commands: Required options and examples
Reference information for the dsmcutil commands and examples are provided.
The INSTall command installs and configures backup-archive client services.
INSTall Scheduler
Installs and configures the IBM Spectrum Protect Scheduler Service.
These are the required INSTall command options:
v /name:service_name
v /password:password
v /clusternode:Yes | No (required if running the Microsoft Cluster Server (MSCS)
or Veritas Cluster Server (VCS)).
v /clustername:cluster_name (required if running the MSCS or VCS).
Restriction: Do not specify a clustername of more than 64 characters. If you
specify more than 64 characters and you are using Veritas Storage Foundation with
High Availability or a Microsoft Cluster Server configuration, you might not be
able to install or start the scheduler service.
The /clientdir:client_dir option can also be used, the default is the current
directory.
The following files must exist in the directory specified by client_dir:
v dsmcsvc.exe
v dscenu.txt
v dsm.opt
v dsmntapi.dll
v tsmutil1.dll
Note: If the service is being installed on a remote workstation, the fully qualified
client directory path should be relative to the target workstation. UNC names are
not allowed for the local system account. Multiple services can be installed on the
same workstation.
Tip: In the commands that are provided in the following examples, the default
location of the client installation program (c:\program files\tivoli\tsm\baclient)
is used. If you installed the client to a different location, replace the default path
with your custom installation path. If the path contains a space, enclose the path in
double quotation marks (for example, "c:\program files\tivoli\tsm\baclient").
|
|
|
|
|
Task
Install a scheduler service that is named TSM Central Scheduler Service
on the local workstation. Start the service automatically at system boot
time. All required files must reside in the current directory and the client
options file must point to the IBM Spectrum Protect server where node
ALPHA1 is defined with password nodepw. The server is contacted to
verify that the specified node and password are valid. When the password
is validated it is generated (encrypted) into the password store:
Command:
278
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
dsmcutil install scheduler /name:"TSM Central Scheduler Service"
/node:ALPHA1 /password:nodepw /autostart:yes
Task
Install a scheduler service named TSM Central Scheduler Service on
remote workstation PDC. Start the service automatically at system boot
time. The required scheduler service files and the specified options file
must reside on the remote workstation in the c:\program
files\tivoli\tsm\baclient directory. The password is encrypted into the
password store. The IBM Spectrum Protect server is not contacted to
validate the password.
Command:
dsmcutil install scheduler /name:"TSM Central Scheduler Service"
/machine:PDC /clientdir:"c:\program files\tivoli\tsm\baclient"
/optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt"
/node:PDC /validate:no /autostart:yes /password:nodepassword
Task
Install a scheduler service named TSM Central Scheduler Service on
remote workstation PDC. Start the service automatically at system boot
time. The required scheduler service files and the specified options file
must reside on the remote workstation in the c:\program
files\tivoli\tsm\baclient directory. The password is encrypted into the
password store. The IBM Spectrum Protect server residing at the specified
TCP/IP host and port is contacted to validate the password.
Command:
dsmcutil install scheduler /name:"TSM Central Scheduler Service"
/machine:PDC /clientdir:"c:\program files\tivoli\tsm\baclient"
/optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt"
/node:PDC /autostart:yes /password:nodepassword
/commmethod:tcpip /commserver:alpha1.example.com
/commport:1521
Task
Install the TSM Central Scheduler Service on one node of a MSCS (or
VCS) cluster. For group-a from workstation node-1, ensure that node-1
currently owns group-a and then issue the following command.
Command:
Command:
dsmcutil install scheduler /name:"TSM Central Scheduler Service:
group-a" /clientdir:"c:\program files\tivoli\tsm\baclient"
/optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt"
/node:mscs-cluster-group-a /password:n
/validate:no /autostart:yes /startnow:yes
/clusternode:yes /clustername:mscs-cluster
INSTall CAD
Installs and configures the Client Acceptor Service. Required options are:
v /name:service_name
v /node:node_name
v /password:password
Other valid options are:
v /optfile:options_file
v /httpport:http_port
v /webports:web_ports
Task
Install a Client Acceptor Service called TSM CAD. The client acceptor uses a
Chapter 10. Client Service Configuration Utility
279
node called test to connect to the IBM Spectrum Protect server. Use the
options file c:\program files\tivoli\tsm\baclient\dsm.opt to connect to
the server.
Command:
dsmcutil install cad /name:"TSM CAD" /node:test /password:test
/optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt"
INSTall Journal
Installs a journaling engine service on all Windows clients. A journal database is
created that stores information the client uses to determine which files are eligible
for backup before an operation starts.
If necessary, you can use the nojournal option with the incremental command to
specify that you want to perform a traditional full incremental backup.
The journaling engine service is named TSM Journal Service and uses the
configuration file tsmjbbd.ini from the backup-archive client installation directory.
Note: The Journal Service is supported in a Microsoft Cluster Server environment.
Multiple journal services can be installed by specifying unique pipe names using
the JournalPipe journal config setting and client options.
There are no valid options for this command.
Task
Install the journal engine service (TSM Journal Service).
Command:
dsmcutil install journal
INSTall REMOTEAgent
Installs and configures a Remote Client Agent Service. Required options are:
v /name:service_name
v /node:node_name
v /password:password
v /partnername:partner_service_name
Other valid options are:
v /optfile:options_file
Task
Install a Remote Client Agent Service called TSM AGENT. The remote client
agent uses a node called test to connect to the IBM Spectrum Protect server.
The options file c:\program files\tivoli\tsm\baclient\dsm.opt is used to
connect to. The partner client acceptor service is TSM CAD.
Command:
dsmcutil install remoteagent /name:"TSM AGENT" /node:test
/password:test /optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt"
/partnername:"TSM CAD"
Note: Both the Remote Client Agent Service and the Client Acceptor Service must
be installed to run the web client. The Client Acceptor Service must be installed
before the Remote Client Agent Service. Use the /partnername: option to specify
the name of the partner Client Acceptor Service.
280
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
REMove
Remove an installed Client Service. The required option is /name:service_name.
Task
Remove the specified scheduler service from the local workstation.
Command:
dsmcutil remove /name:"TSM Central Scheduler Service"
Task
Remove the journaling engine service (TSM Journal Service) from the local
workstation.
Command:
dsmcutil remove /name:"TSM Journal Service"
UPDate
Updates Scheduler Service registry values. The required option for this command
is /name:service_name, and the registry values to update. Other valid options are:
v /clientdir:client_dir
v /optfile::options_file
v /eventlogging:Yes | No
v /node:node_name
v /autostart:Yes | No
v /clusternode:Yes | No (required if running the MSCS or VCS).
v /clustername:cluster_name (required if running the MSCS or VCS).
Task
Update the client directory and options file for the specified scheduler
service. All required client service files must reside in the specified
directory.
Note: The communication options specified with the dsmcutil command
here take precedence over those specified in the client options file.
Command:
dsmcutil update /name:"TSM Central Scheduler Service"
/clientdir:"c:\program files\tivoli\tsm\baclient"
/optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt"
Task
Update the specified scheduler service to use the TCP/IP protocol to
connect to the IBM Spectrum Protect server at the specified host name on
the specified port.
Command:
dsmcutil update /name:"TSM Central Scheduler Service"
/commserver:nt1.example.com /commport:1521 /commmethod:
tcpip
UPDate CAD
Updates Client Acceptor Service registry values. The required option for this
command is /name:service_name, and the registry values to update. Other valid
options are:
v /node:node_name
v /password:password
v /optfile:options_file
v /httpport:http_port
Chapter 10. Client Service Configuration Utility
281
v /webports:web_ports
v /cadschedname:scheduler_name
Task
Update the Client Acceptor Service to use the specified client password
and options file. All required client service files must reside in the specified
directory.
Command:
dsmcutil update cad /name:"TSM CAD" /password:test
/optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt"
UPDate REMOTEAgent
Updates Remote Client Agent Service registry values. The required option for this
command is /name:service_name, and the registry values to update. Other valid
options are:
v /node:node_name
v /password:password
v /optfile:options_file
v /partnername:partner_service_name
Task
Update a Remote Client Agent Service called TSM AGENT. The remote client
agent service uses a node called test to connect to the IBM Spectrum
Protect server. The options file c:\program files\tivoli\tsm\baclient\
dsm.opt is used to connect to the server. The partner client acceptor service
is TSM CAD.
Command:
dsmcutil update remoteagent /name:"TSM AGENT" /node:test
/password:test /optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt"
/partnername:"TSM CAD"
Query Scheduler
Query Scheduler Service registry values. Required options are: /name:service_name.
Other valid options are:
v /machine:machine_name
v /clientdir
v /optfile
v /eventlogging
v /node
v /commmethod
v /commport
v /commserver
v /errorlog
v /schedlog
Note: Do not specify a value for the non-required options. The client returns
option registry values for the scheduler service you specify.
Task
Query registry settings for the scheduler service you specify.
Command:
dsmcutil query /name:"TSM Central Scheduler Service"
282
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Task
Query the client directory registry setting for the scheduler service you
specify.
Command:
dsmcutil query /name:"TSM Central Scheduler Service"
Query CAD
Queries Client Acceptor Service registry values. The required option for this
command is /name:service_name. Other valid options are:
v /machine:machine_name
v /node
v /optfile
v /httpport
v /webports
v /clientdir
v /partnername
Note: Do not specify a value for these options.
Task
Query registry settings for the Client Acceptor Service you specify.
Command:
dsmcutil query cad /name:"TSM CAD"
Query Journal
Query the journaling engine service, TSM Journal Service, on a Windows system.
There are no valid options for this command.
Task
Query the journaling engine service, TSM Journal Service.
Command:
dsmcutil query journal
Query REMOTEAgent
Queries Remote Client Agent Service registry values. The required option for this
command is /name:service_name. Other valid options are:
v /machine:machine_name
v /node
v /optfile
v /partnername
v /clientdir
Note: Do not specify a value for these options.
Task
Query registry settings for the specified Remote Client Agent Service.
Command:
dsmcutil query remoteagent /name:"TSM AGENT"
List
Lists installed Client Services. There are no required options.
Chapter 10. Client Service Configuration Utility
283
Task
Locate and list the installed backup-archive client services on the local
workstation.
Command:
dsmcutil list
Task
List the installed backup-archive client services on remote workstation
PDC.
Command:
dsmcutil list /MACHINE:PDC
START
Use the Start command to start a client service. The Start command requires the
/name:service_name option.
Task
Start the journaling engine service, TSM Journal Service.
Command:
dsmcutil start /name:"TSM Journal Service"
STOP
Use the Stop command to stop a client service. The Stop command requires the
/name:service_name option.
Task
Stop the journaling engine service, TSM Journal Service.
Command:
dsmcutil stop /name:"TSM Journal Service"
UPDATEPW
Generate an encrypted IBM Spectrum Protect password. The UPDATEPW
command requires the /node:node_name, /password:password, and
/commserver:server_name options. If the clusternode option is set to YES, the
/optfile: parameter is also required.
|
|
|
|
Optionally, you can use the following options:
v /validate:Yes | No
v /clusternode:Yes | No (required if running the MSCS or VCS).
v /clustername:cluster_name (required if running the MSCS or VCS).
v /force:Yes | No
v /optfile: (for non-cluster operations)
v /commmethod:
v /commport:
The password is validated with the IBM Spectrum Protect server if /validate:Yes
is specified. The password is updated on the server if you specify
/updateonserver:Yes. If you specify this option, you must specify the current
password with the /oldpassword: option.
Task
Update the encrypted password for the specified node. Validate and
update the password on the specified IBM Spectrum Protect server which
resides on the specified TCP/IP hostname and port:
Command:
284
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
|
|
|
dsmcutil updatepw /node:alpha1 /commMethod:tcpip
/commServer:alpha1.example.com /commPort:1500
/password:newpw /oldpassword:oldpw /updateonserver:yes
/validate:yes /optfile:"c:\program files\tivoli\tsm\baclient\dsm.opt"
|
ADDACE
|
|
Grants access to the IBM Spectrum Protect backup-archive client password and the
client SSL certificates for non-administrators.
|
|
|
|
Beginning with IBM Spectrum Protect Version 8.1.2, stricter access control is
enforced for the IBM Spectrum Protect password storage on Windows operating
systems. By default, only the Administrator, SYSTEM, or LocalSystem account has
access to the password store and SSL certificates.
|
|
|
|
You can use the addace command to modify the access control list to allow
additional users, such as non-administrative users, or processes such as the IBM
Spectrum Protect Data Protection client processes to access the password store and
SSL certificates.
|
The following options are required:
|
v -entity:user | group
|
v -object:ALL | NODENAME | path\TSM.* | path\spclient.*
|
Where:
|
|
|
user | group
The Windows user or user group that is given read/write access to the
password store.
|
|
ALL
|
|
|
|
NODENAME
Grants access to all password files and SSL certificates that are found in the
subdirectories of the C:\ProgramData\Tivoli\TSM\baclient\Nodes\nodename
directory.
|
|
|
|
path\TSM.* | path\spclient.*
For cluster passwords that can exist on a shared resource directory, grants
access to the password files or certificate files in a specific directory for a
node.
|
|
For more information about the secure password locations on Windows, see Secure
password storage.
|
|
Tip: The dsmcutil deleteace command revokes access to password files and SSL
certificates.
|
|
|
|
Task
After you installed and configured the backup-archive client as
Administrator, you need to give Susan, a non-administrative user on your
Windows system, access to the password files and SSL certificates on the
client node Alpha1.
Command:
|
|
|
|
Grants access to all password files and SSL certificates in the subdirectories
of the C:\ProgramData\Tivoli\TSM\baclient directory.
dsmcutil addace -entity:Susan -object:Alpha1
Task
A non-administrative user of IBM Spectrum Protect for Databases: Data
Protection for Microsoft SQL Server configured the IBM Spectrum Protect
Chapter 10. Client Service Configuration Utility
285
|
|
|
passwords but the administrator also needs access to the passwords. The
Data Protection for Microsoft SQL Server user grants access to the
password files to the administrator by issuing the following command:
|
|
Command:
dsmcutil addace -entity:Administrator -object:all
Task
|
|
During a cluster configuration, the Windows administrator needs to give
the cluster node clusnode_A access to the client SSL certificates.
|
|
|
Command:
|
|
|
If the client certificates are not in the default location (C:\ProgramData\
Tivoli\TSM\baclient\Nodes\clusnode_A\), they are located in the same
directory as the dsm.opt file.
dsmcutil addace -entity:Group_A
-object:C:\ProgramData\Tivoli\TSM\baclient\Nodes\clusnode_A\spclient.*
|
DELETEACE
|
|
Revokes access to the IBM Spectrum Protect backup-archive client password and
the client SSL certificates for non-administrators.
|
|
|
|
You can use the deleteace command to modify the access control list to remove
access to the password store and client certificates for users, such as
non-administrative users or processes such as the IBM Spectrum Protect Data
Protection client processes.
|
The following options are required:
|
v -entity:user | group
|
v -object:ALL | NODENAME | path\TSM.* | path\spclient.*
|
Where:
|
|
|
user | group
The Windows user or user group for which access to the password store
and client certificates is removed.
|
|
ALL
|
|
|
|
NODENAME
Removes access to all password files and SSL certificates that are found in
the subdirectories of the C:\ProgramData\Tivoli\TSM\baclient\Nodes\
nodename directory.
|
|
|
|
path\TSM.* | path\spclient.*
For cluster passwords that can exist on a shared resource directory,
removes access to the password files or certificate files in a specific
directory for a node.
|
|
For more information about the secure password locations on Windows, see
“Secure password storage” on page 106.
|
|
Tip: The dsmcutil addace command grants access to password files and SSL
certificates.
|
|
|
Task
286
Removes access to all password files and SSL certificates in the
subdirectories of the C:\ProgramData\Tivoli\TSM\baclient directory.
Susan, a non-administrative user, left the company two days ago and the
administrator must revoke access to the password files and SSL certificates
on the client node Alpha1.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Command:
|
|
|
|
|
dsmcutil deleteace -entity:Susan -object:Alpha1
Task
Cluster node clusnode_Z is moved out of the cluster configuration and no
longer needs to access to the client SSL certificates. Issue the following
command to remove access for clusnode_Z.
|
|
|
Command:
|
|
|
If the client certificates are not in the default location (C:\ProgramData\
Tivoli\TSM\baclient\Nodes\clusnode_Z\), they are located in the same
directory as the dsm.opt file.
dsmcutil deleteace -entity:Group_Z
-object:C:\ProgramData\Tivoli\TSM\baclient\Nodes\clusnode_Z\spclient.*
Related concepts:
“Journal-based backup” on page 141
Related tasks:
“Dsmcutil valid options”
Related reference:
“Incremental” on page 691
|
Dsmcutil valid options
|
|
This section lists the valid dsmcutil options that you can specify to use the
scheduler service.
|
About this task
|
|
|
/autostart:[Yes|No]
Specifies whether the Scheduler Service starts automatically at system boot
time. The default is No.
|
|
|
|
|
/cadschedname:schedulername
Specifies the name of the scheduler service to manage with the client
acceptor. Use this option when the managedservices option is set to
schedule in the client options file dsm.opt. You can specify this option only
with the client acceptor service.
|
|
|
|
|
/clientdir:clientdir
The fully qualified directory path where the Client Service files reside. This
directory should be relative to the target workstation where the service is
installed. UNC names are not allowed if the local system account is set to
logon. The default is the current directory.
|
|
/clustername:clustername
This option replaces the /group option.
|
|
The /clustername option specifies the cluster name to which the system
belongs. You can determine the cluster name in any of the following ways:
|
|
|
|
v On MSCS, run the MSCS command, CLUSTER /LIST, from the
command line or use the Cluster Administrator utility. When the Cluster
Administrator utility starts, it displays a tree-like structure with the
cluster name at the top.
|
|
v On VCS, use the VCS Cluster Manager - Java Console or open the
main.cf file in the %VCS_HOME%\config directory.
|
|
v On VCS, use the following command:
haclus -display
Chapter 10. Client Service Configuration Utility
287
|
|
|
|
|
Restriction: Do not specify a clustername of more than 64 characters. If
you specify more than 64 characters and you are using Veritas Storage
Foundation with High Availability or a Microsoft Cluster Server
configuration, you might not be able to install or start the IBM Spectrum
Protect scheduler service.
|
|
|
|
This option must be used with the /clusternode:Yes option. This option
must be specified when using the INSTALL command in a cluster
environment. It must also be specified when using the UPDATE command
to modify the cluster settings (/clusternode and /clustername).
|
|
|
|
|
This option can also be specified when using the UPDATEPW command in
a cluster environment. Normally this is not required. However, if more
than one scheduler service with different cluster settings are defined for a
particular node, the utility cannot determine which settings are correct. In
this case, correct the discrepancies between the services.
|
|
|
Alternatively, you can specify this option with /clusternode:Yes and
/force:Yes, to force the utility to show or update the password with the
specified cluster settings.
|
This option is not required if /clusternode:No is specified.
|
|
|
|
|
|
|
/clusternode:Yes|No
Specifies whether to enable support for cluster resources. The default value
is No. You must be running the MSCS or VCS to specify /clusternode:Yes.
This option must be specified when using the INSTALL command in a
cluster environment. This option must also be specified when using the
UPDATE command to modify the cluster settings (/clusternode,
/clustername).
|
|
|
|
|
This option can also be specified when using the UPDATEPW command in
a cluster environment. Normally this is not required. However, if more
than one scheduler service with different cluster settings are defined for a
particular node, the utility cannot determine which settings are correct. In
this case, correct the discrepancies between the services.
|
|
|
Alternatively, you can specify this option with /clustername and /force:Yes,
to force the utility to show or update the password with the specified
cluster settings. If /clusternode:No is specified, /clustername is not required.
|
|
|
|
|
|
|
/commmethod:protocol
Specifies client communications protocol to communicate with the IBM
Spectrum Protect server. Valid protocols are: TCP/IP and Named Pipes. If
you do not specify a value, the value is obtained from the client options
file or set to the default client value. You can also use this option with the
UPDATEPW command to specify a communication protocol to connect to
a server when updating passwords.
|
|
|
|
|
|
|
/commport:serverport
Specifies the protocol specific IBM Spectrum Protect server port. For
TCP/IP, this is the port on the specified hostname. If this option is not
specified, the value is obtained from the client options file or set to the
default client value. You can also use this option with the UPDATEPW
command to specify a protocol specific server port to connect to for
updating passwords.
|
|
|
/commserver:servername
Specifies the protocol specific IBM Spectrum Protect server name.
Depending on the protocol used, this can be a TCP/IP hostname or a
288
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
|
Named Pipes name. If not specified, the value is obtained from the client
options file or set to the default client value.
|
|
This option can also be used with the UPDATEPW command to specify a
protocol specific server name to connect to for updating passwords.
|
|
|
|
/copyfiles
Specifies that the service installation is copied to another location prior to
installing the service. Use the /srcdir option to specify the fully qualified
source path.
|
|
/errorlog:errorlog
Specifies the fully qualified name of the client error log.
|
|
|
/eventlogging:[Yes|No]
Turns detailed event logging on or off for the specified scheduler service.
The default is Yes.
|
|
|
|
|
|
/force:[Yes|No]
This option can also be specified when using the UPDATEPW command in
a cluster environment. Normally this is not required. However, if more
than one scheduler service with different cluster settings is defined for a
particular node, the utility cannot determine which settings are correct. In
this case, correct the discrepancies between the services.
|
|
|
Alternatively, you can specify this option with /clusternode and
/clustername (if /clusternode:Yes is specified), to force the utility to show or
update the password with the specified cluster settings.
|
|
/httpport:httpport
Specifies a TCP/IP port address for the web client.
|
|
/machine:machinename
Specifies the name of a remote workstation to connect to.
|
|
|
/name:servicename
Specifies the name of the Client service. The name must be quote delimited
if it contains embedded spaces.
|
|
|
|
|
/node:nodename
Specifies the IBM Spectrum Protect node name the Client Service uses
when connecting to the IBM Spectrum Protect server. Also used when
displaying or updating the IBM Spectrum Protect password. The default is
the workstation name.
|
|
/ntaccount:ntaccount
Specifies the Windows account which the service logs in as.
|
|
/ntdomain:ntdomain
Specifies the Windows domain which the service logs in as.
|
|
|
/ntpassword:ntpassword
Specifies the Windows password for the account under which the service
logs in.
|
|
|
/oldpassword:oldpw
Current® IBM Spectrum Protect server password. Used in conjunction with
the /updateonserver option when updating a password on the server.
|
|
|
|
/optfile:optionsfile
The fully qualified path of the client options file. This is the options file the
specified Client Service uses to connect to the IBM Spectrum Protect server.
The utility also uses the file to connect to the IBM Spectrum Protect server
Chapter 10. Client Service Configuration Utility
289
to validate and update passwords. Note that although this option overrides
the default option file in the current directory (dsm.opt), the IBM Spectrum
Protect API requires that a default option file exists in the current directory.
UNC names are not allowed if the local system account is set to logon. The
default is the dsm.opt file in the /clientdir directory.
|
|
|
|
|
|
|
|
/partnername:partner service name
This option is used when installing a Remote Client Agent Service to
specify the partner Client Acceptor Service.
|
|
/password:password
The IBM Spectrum Protect password which is generated and encrypted.
|
|
/schedlog:schedlog
Specifies the fully qualified name of the client schedule log.
|
|
|
|
/srcdir:pathname
Use this option in conjunction with the /copyfiles option to specify the
fully qualified source path to copy the service installation to another
location prior to installing the service.
|
|
|
|
|
/startnow:[Yes|No]
Specifies whether dsmcutil starts the specified service after executing the
command; the default is Yes. If you specify No, you must start the service
manually using the services control panel applet, or the NET START name
of the service.
|
|
|
/updateonserver:[Yes|No]
Specifies whether the specified password is updated on the IBM Spectrum
Protect server. Requires using the /oldpassword option.
|
|
|
/validate:[Yes|No]
Specifies whether to perform validation when displaying or updating the
encrypted password. The default is Yes.
|
|
|
/webports: webports
Specifies the TCP/IP port number used by the Client Acceptor service and
the web client agent service for communications with the web GUI.
|
290
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Chapter 11. Processing options
You can use defaults for processing client options or you can tailor the processing
options to meet your specific needs. Read about an overview of processing options
and explore the options reference that provides detailed information about each
option.
Related concepts:
“Using options with commands” on page 309
Related reference:
“Reading syntax diagrams” on page xiv
Processing options overview
IBM Spectrum Protect uses processing options to control communications,
backup-archive processing, and other types of processing.
You can specify processing options in the client options file (dsm.opt) or on the
command line.
You can set the following types of options:
v Communication options
v Node options
v Backup and archive processing options
v Restore and retrieve processing options
v Scheduling options
v Format and language options
v Command processing options
v Authorization options
v Error processing options
v Transaction processing option
v Web client options
v Diagnostics options
The backup-archive client also includes a group of client command options that
you can enter only on the command line with specific commands. You can
override some of the options in your options file by entering them with
appropriate backup-archive commands.
Note: Some of the processing options that are used by the IBM Spectrum Protect
central scheduler are defined in the Windows registry when the schedule services
are configured. These options can also be specified in the client options file. When
the scheduler runs as a service, processing options that are specified in the registry
override the same options that are specified in the client options file.
Related concepts:
“Entering options with a command” on page 310
Related tasks:
“Creating and modifying the client options file” on page 23
© Copyright IBM Corp. 1993, 2017
291
Communication options
You use communication options to specify how your client node communicates
with the IBM Spectrum Protect server. This topic provides information about the
types of communication options you can use.
v TCP/IP
For all Windows clients, use one of the following protocols:
v TCP/IP
v Named pipes
v Shared memory
Use the commmethod option to specify the communication protocol.
Ask your IBM Spectrum Protect administrator for assistance in setting your
communication options.
Related reference:
“Commmethod” on page 343
TCP/IP options
To use the TCP/IP communication protocol, you must include the
tcpserveraddress option in your client options file.
The other TCP/IP options have default values that you can modify if you want to
change the default value. This topic provides information about the types of
communication options you can use.
Table 36. TCP/IP options
Option
Description
httpport “Httpport” on page
419
Specifies a TCP/IP port address for the web client.
lanfreetcpport
Specifies the TCP/IP port number where the IBM Spectrum
“Lanfreetcpport” on page 449 Protect storage agent is listening.
292
lanfreetcpserveraddress
“Lanfreetcpserveraddress”
on page 451
Specifies the TCP/IP address for the IBM Spectrum Protect
storage agent.
tcpbuffsize “Tcpbuffsize”
on page 554
Specifies the size, in kilobytes, of the internal TCP/IP
communication buffer.
tcpnodelay “Tcpnodelay” on
page 557
Specifies whether the server or client disables the delay of
sending successive small packets on the network.
tcpadminport “Tcpadminport”
on page 553
Specifies a separate TCP/IP port number on which the
server is waiting for requests for administrative client
sessions, allowing secure administrative sessions within a
private network.
tcpcadaddress
“Tcpcadaddress” on page 555
Specifies a TCP/IP address for dsmcad.
tcpport “Tcpport” on page
558
Specifies the TCP/IP port address for an IBM Spectrum
Protect server.
tcpserveraddress
“Tcpserveraddress” on page
559
Specifies the TCP/IP address for an IBM Spectrum Protect
server.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 36. TCP/IP options (continued)
Option
Description
tcpwindowsize
“Tcpwindowsize” on page 559
Specifies the size, in kilobytes, of the TCP/IP sliding
window for your client node.
webports “Webports” on page
631
Enables the use of the web client outside a firewall by
specifying the TCP/IP port number used by the client
acceptor service and the web client agent service for
communications with the web GUI.
Named Pipes option
This topic provides information about the namedpipename communication option.
Table 37. Named Pipes communication option
Option
Description
namedpipename
“Namedpipename” on page 467
Specifies the name of a named pipe to use for
communications between a client and IBM Spectrum Protect
server on the same Windows server domain.
Shared memory options
This topic provides information on the shared memory options that you can use.
Table 38. Shared memory communication options
Option
Description
lanfreeshmport
Specifies the unique number that is used by the client and
“Lanfreeshmport” on page 448 the storage agent to identify shared memory area used for
communications.
lanfreeshmport “Shmport” on
page 523
Specifies the unique number that is used by the client and
the server to identify shared memory area used for
communications.
Backup and archive processing options
You can specify client options to control some aspects of backup and archive
processing.
Table 39. Backup and archive processing options
Option
Description
archmc
“Archmc” on page 319
Use the archmc option with the archive
command to specify the available
management class for your policy
domain to which you want to bind your
archived files.
asnodename
“Asnodename” on page 320
Use the asnodename option to allow
agent nodes to back up or restore data
on behalf of another node (the target
node). This option enables concurrent
operations from multiple nodes to store
data to the same target node and file
space in parallel.
Chapter 11. Processing options
293
Table 39. Backup and archive processing options (continued)
294
Option
Description
autofsrename
“Autofsrename” on page 329
Specifies whether to rename an existing
file space on a Unicode-enabled server
so a Unicode-enabled file space can be
created for the current operation.
backmc
“Backmc” on page 331
Specifies the management class to apply
to the backup fastback subcommand
for retention purposes.
changingretries
“Changingretries” on page 336
Specifies the number of times the client
attempts to back up or archive a file
that is in use.
class
“Class” on page 337
Specifies whether to list the NAS or
client Application Server objects during
a query backup, query filespace, or
delete filespace operation.
compressalways
“Compressalways” on page 346
The compressalways option specifies
whether to continue compressing an
object if it grows during compression.
Use this option with the compression
option.
compression
“Compression” on page 347
The compression option compresses files
before you send them to the server.
Compressing your files reduces data
storage for backup versions and archive
copies of your files.
createnewbase
“Createnewbase” on page 350
The createnewbase option creates a base
snapshot and uses it as a source to run
a full incremental. Setting this option
ensures the backup of any files that
might have been skipped during the
snapshot difference incremental.
deduplication
“Deduplication” on page 356
Specifies whether to eliminate
redundant data on the client side when
the client transfers data to theIBM
Spectrum Protect server during backup
or archive processing.
dedupcachepath
“Dedupcachepath” on page 355
Specifies the location where the
client-side data deduplication cache
database is created, if the
enablededupcache=yes option is set
during backup or archive processing.
dedupcachesize
“Dedupcachesize” on page 355
Determines the maximum size of the
data deduplication cache file.
enablededupcache
“Enablededupcache” on page 384
Specifies whether you want to enable
client-side data deduplication cache, so
that the backup-archive client gets the
changed data from the cache.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 39. Backup and archive processing options (continued)
Option
Description
deletefiles
“Deletefiles” on page 357
Use the deletefiles option with the
archive command to delete files from
your workstation after you archive
them.
You can also use this option with the
restore image command and the
incremental option to delete files from
the restored image if they were deleted
after the image was created.
description
“Description” on page 358
The description option assigns or
specifies a description for files when the
client performs archive, delete, retrieve,
query archive, or query backupset
operations.
detail
“Detail” on page 359
Use the detail option to list
management class, file space, backup,
and archive information, depending on
the command with which it is used.
diffsnapshot
“Diffsnapshot” on page 360
Use the diffsnapshot option to
determine whether the client creates a
differential snapshot.
dirmc
“Dirmc” on page 363
Specifies the management class to use
for directories. If you do not specify this
option, the client uses the management
class in the active policy set of your
policy domain with the longest
retention period.
dirsonly
“Dirsonly” on page 364
Backs up, restores, archives, retrieves, or
queries directories only.
diskcachelocation
“Diskcachelocation” on page 366
Specifies the location where the disk
cache database is created if the option
memoryefficient=diskcachemethod
option is set during an incremental
backup.
domain
“Domain” on page 367
Specifies the drives to include in your
default client domain for an incremental
backup.
domain.image
“Domain.image” on page 370
Specifies the file systems and raw
logical volumes that you want to
include in your client domain for an
image backup. This option is valid for
all Windows clients.
domain.nas
“Domain.nas” on page 371
Specifies the volumes to include in your
default domain for NAS image backups.
domain.vmfull
“Domain.vmfull” on page 372
Specifies the virtual machines to include
in full image backups of VMware
virtual machines.
enablearchiveretentionprotection
Allows the client to connect to a data
“Enablearchiveretentionprotection” on page 383 retention server.
Chapter 11. Processing options
295
Table 39. Backup and archive processing options (continued)
296
Option
Description
enablelanfree
“Enablelanfree” on page 387
Specifies whether to enable an available
LAN-free path to a storage area
network (SAN) attached storage device.
exclude
exclude.backup
exclude.file
exclude.file.backup
Use these options to exclude a file or
group of files from backup services.
encryptiontype
“Encryptiontype” on page 388
Select AES-256 or AES-128 bit data
encryption. AES 256-bit data encryption
provides the highest level of data
encryption.
encryptkey
“Encryptkey” on page 389
Specifies whether to save the encryption
key password locally when the client
performs a backup-archive operation or
whether to prompt for the encryption
key password.
exclude.archive
“Exclude options” on page 395
Excludes a file or a group of files that
match the pattern from archive services
only.
exclude.compression
“Exclude options” on page 395
Excludes files from compression
processing if you set the compression
option to yes. This option applies to
backups and archives.
exclude.dir
“Exclude options” on page 395
Excludes a directory, its files, and all its
subdirectories and their files from
backup processing.
exclude.encrypt
“Exclude options” on page 395
Excludes specified files from encryption
processing.
exclude.fs.nas
“Exclude options” on page 395
Excludes file systems on the NAS file
server from an image backup when
used with the backup nas command.
exclude.image
“Exclude options” on page 395
Excludes mounted file systems and raw
logical volumes that match the specified
pattern from full image backup
operations. Incremental image backup
operations are unaffected by
exclude.image.
fbbranch
“Fbbranch” on page 402
Specifies the branch ID of the remote
FastBack server to back up or archive.
fbclientname
“Fbclientname” on page 403
Specifies the name of one or more
FastBack clients to back up from the
backup proxy.
fbpolicyname
“Fbpolicyname” on page 405
Specifies the name of one or more Tivoli
Storage Manager FastBack policies that
you want to back up from the backup
proxy.
fbreposlocation
“Fbreposlocation” on page 406
Specifies the location of the Tivoli
Storage Manager FastBack repository for
the IBM Spectrum Protect client proxy
to connect to issue MOUNT DUMP,
MOUNT ADD, and MOUNT DEL
commands.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 39. Backup and archive processing options (continued)
Option
Description
fbserver
“Fbserver” on page 408
Specifies host name of the FastBack
server workstation or the FastBack
Disaster Recovery Hub workstation that
owns the repository that is specified by
the fbreposlocation option.
fbvolumename
“Fbvolumename” on page 409
Specifies the name of one or more Tivoli
Storage Manager FastBack volumes to
back up from the backup proxy.
filelist
“Filelist” on page 410
Specifies a list of files to be processed
for the command. The client opens the
designated file list and processes the
files that are listed within according to
the command.
filesonly
“Filesonly” on page 414
Backs up, restores, retrieves, or queries
files only.
groupname
“Groupname” on page 418
Use this option with the backup group
command to specify the fully qualified
name of the group leader for a group.
ieobjtype
“Ieobjtype” on page 421
Specifies an object type for a client-side
data deduplication operation. This
option is used with the include.dedup
and exclude.dedup options.
imagegapsize
“Imagegapsize” on page 422
Specifies the minimum size of empty
regions on a volume that you want to
skip during backup. This option is valid
for all Windows clients.
inclexcl
“Inclexcl” on page 425
Specifies the path and file name of an
include-exclude options file.
“Include options” on page 426
Use these options to include files or
assign management classes for backup
processing.
include
include.backup
include.file
include.archive
“Include options” on page 426
Includes files or assigns management
classes for archive processing.
include.compression
“Include options” on page 426
Includes files for compression
processing if you set the compression
option to yes. This option applies to
backups and archives.
include.encrypt
“Include options” on page 426
Includes the specified files for
encryption processing. By default, the
client does not perform encryption
processing.
include.fs
“Include options” on page 426
Use the include.fs option to specify
processing options for a file system. Use
the include.fs option to specify which
drives use open file support and to
control how full file space incremental
backups are processed.
Chapter 11. Processing options
297
Table 39. Backup and archive processing options (continued)
298
Option
Description
include.fs.nas
“Include options” on page 426
Use the include.fs.nas option to bind a
management class to Network Attached
Storage (NAS) file systems. You can also
specify whether the client saves Table of
Contents (TOC) information during a
NAS file system image backup, by
using the toc option with the
include.fs.nas option in your client
options file (dsm.opt). For more
information, see “Toc” on page 562.
include.image
“Include options” on page 426
Specifies a file system or logical volume
to be included for image backup
processing. This option also provides a
way to specify an explicit management
class assignment for a specified file
system or logical volume. The backup
image command ignores all other
include options. Use the include.fs
option to specify which drives use open
file support and to control how full file
space incremental backups are
processed.
include.systemstate
“Include options” on page 426
Assigns management classes for backup
of the Windows system state. The
default is to bind the system object to
the default management class.
incrbydate
“Incrbydate” on page 442
Use with the incremental command to
request an incremental backup by date.
incremental
“Incremental” on page 443
Use with the restore image command to
ensure that any changes that were made
to the base image are also applied to the
restored image.
incrthreshold
“Incrthreshold” on page 443
The incrthreshold option specifies the
threshold value for the number of
directories in any journaled file space
that might have active objects on the
server, but no equivalent object on the
workstation.
memoryefficientbackup
“Memoryefficientbackup” on page 458
Specifies a memory-saving backup
algorithm for incremental backups when
used with the incremental command.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 39. Backup and archive processing options (continued)
Option
Description
mode
“Mode” on page 460
Use the mode option with these
commands, as follows:
backup image
To specify whether to perform
a selective or incremental
image backup of client file
systems.
backup nas
To specify whether to perform
a full or differential image
backup of NAS file systems.
backup group
To specify whether to perform
a full or differential group
backup that contains a list of
files from one or more file
space origins.
backup vm
To specify whether to perform
a full or incremental backup of
a VMware virtual machine
when vmbackuptype=fullvm,
and when you have installed
IBM Spectrum Protect for
Virtual Environments.
monitor
“Monitor” on page 464
Specifies whether you want to monitor
an image backup of file systems that
belong to a Network Attached Storage
(NAS) file server.
noprompt
“Noprompt” on page 470
Suppresses the confirmation prompt
that is presented by the delete group,
delete archive, expire, restore image,
and set event commands.
nojournal
“Nojournal” on page 470
Use this option with the incremental
command to specify that you want to
perform the traditional full incremental
backup, instead of the default
journal-based backup.
optfile
“Optfile” on page 474
Specifies the client options file you want
to use when you start a backup-archive
client session.
postsnapshotcmd
“Postsnapshotcmd” on page 482
During an online image backup or open
file support operation, this option
allows you to manually open an
application after the snapshot provider
starts a snapshot. This option is only
valid if the OFS or online image
support is enabled.
Chapter 11. Processing options
299
Table 39. Backup and archive processing options (continued)
300
Option
Description
preservelastaccessdate
“Preservelastaccessdate” on page 485
Use this option during a backup or
archive operation to specify whether to
reset the last access date of any
specified files to their original value
after a backup or archive operation. By
default, the client does not reset the last
access date of any backed up or
archived files to their original value
before the backup or archive operation.
presnapshotcmd
“Presnapshotcmd” on page 488
During an online image backup or open
file support operation, this option
allows you to manually quiesce an
application before the snapshot provider
starts a snapshot. This option is only
valid if the OFS or online image
support is enabled.
resetarchiveattribute
“Resetarchiveattribute” on page 502
Specifies whether the client resets the
Windows archive attribute on files that
are successfully backed up to the IBM
Spectrum Protect server. This option is
valid for all Windows clients.
skipntpermissions
“Skipntpermissions” on page 525
Specifies whether to back up, archive,
retrieve, or restore Windows security
information.
skipntsecuritycrc
“Skipntsecuritycrc” on page 526
Specifies whether to compute the
security CRC for permission comparison
during subsequent backups. Use this
option on all Windows clients.
snapdiff
“Snapdiff” on page 528
Specifies an incremental backup of the
files reported as changed by NetApp,
instead of scanning the volume and
looking for files that have changed. Use
this option with a NAS full volume
incremental backup.
snapshotproviderfs
“Snapshotproviderfs” on page 536
Use the snapshotproviderfs option to
enable snapshot-based file backup and
archive operations, and to specify a
snapshot provider.
snapshotproviderimage
“Snapshotproviderimage” on page 536
Use the snapshotproviderimage option
to enable snapshot-based online image
backup, and to specify a snapshot
provider.
snapshotroot
“Snapshotroot” on page 537
Use the snapshotroot option with the
incremental, selective, or archive
commands with an independent
software vendor application that
provides a snapshot of a logical volume,
to associate the data on the local
snapshot with the real file space data
that is stored on the IBM Spectrum
Protect server.
subdir
“Subdir” on page 549
Specifies whether to include
subdirectories of a named directory.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 39. Backup and archive processing options (continued)
Option
Description
tapeprompt
“Tapeprompt” on page 552
Specifies whether you want the client to
wait for a tape mount if it is required
for a backup, archive, restore, or retrieve
process, or to be prompted for a choice.
toc
“Toc” on page 562
Use the toc option with the backup nas
command or the include.fs.nas option
to specify whether the client saves Table
of Contents (TOC) information for each
file system backup. If you save TOC
information, you can use the QUERY
TOC server command to determine the
contents of a file system backup with
the RESTORE NODE server command
to restore individual files or directory
trees. You can also use the web client to
examine the entire file system tree and
select files and directories to restore.
type
“Type” on page 566
Use the type option with the query
node command to specify the type of
node to query.
v2archive
“V2archive” on page 570
Use the v2archive option with the
archive command to archive only files
to the server. The client does not
process directories that exist in the path
of the source file specification.
virtualfsname
“Virtualfsname” on page 572
(does not apply to Mac OS X)
Use this option with the backup group
command to specify the name of the
container for the group on which you
want to perform the operation.
vmchost
“Vmchost” on page 579
Used with the backup VM, restore VM,
or query VM commands to specify the
host name of the VMware VirtualCenter
or ESX server where the commands are
directed.
vmcpw
“Vmcpw” on page 580
Used with the backup VM, restore VM,
or query VM commands to specify the
password of the VirtualCenter or ESX
user that is specified with the vmcuser
option.
vmcuser
“Vmcuser” on page 582
Used with the backup VM, restore VM,
or query VM commands to specify the
user name for the VMware
VirtualCenter or ESX server where the
commands are directed.
vmmaxvirtualdisks
“Vmmaxvirtualdisks” on page 603
Used with the backup VM command to
specify the maximum size of the
VMware virtual machine disks
(VMDKs) to include in a backup
operation.
Chapter 11. Processing options
301
Table 39. Backup and archive processing options (continued)
Option
Description
vmskipmaxvirtualdisks
“Vmskipmaxvirtualdisks” on page 615
Used with the backup VM command to
specify how the backup operation
processes VMware virtual machine
disks (VMDKs) that exceed the
maximum disk size. In V7.1.3 and
earlier, the vmskipmaxvirtualdisks
option was named vmskipmaxvmdks.
The following options are backup-archive client options that apply only to IBM
Spectrum Protect HSM for Windows migrated files.
v Restorecheckstubaccess
v Restoremigstate
v Skipmigrated
Related concepts:
Options for backing up migrated files: skipmigrated, checkreparsecontent,
stagingdirectory
Options for restoring migrated files: restorecheckstubaccess, restoremigstate
Restore and retrieve processing options
You can use client options to control some aspects of restore and retrieve
processing.
Table 40 lists the restore and retrieve processing options that are available.
Table 40. Restore and retrieve processing options
302
Option
Description
asrmode “Asrmode” on page 323
Use this option with the restore, and restore
systemstate commands to specify whether to
perform a restore operation in system ASR recovery
mode. This option is used in the context of restore
commands that are generated in the asr.sif file by
the backup asr command only. Do not use this
option outside the context of ASR recovery mode.
backupsetname “Backupsetname” on
page 332
The backupsetname option specifies either the name
of the backup set, or the name of the file or tape
device that contains the backup set. This option is
used with the location option.
dirsonly “Dirsonly” on page 364
Qualifies the operation (backup, archive, restore,
retrieve) to process directories alone.
disablenqr “Disablenqr” on page 364
Specifies whether the backup-archive client can use
the no-query restore method for restoring files and
directories from the server.
filelist “Filelist” on page 410
Specifies a file that contains a list of files to be
processed by the specified command.
filesonly “Filesonly” on page 414
Qualifies the operation (backup, archive, restore,
retrieve) to process files alone.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 40. Restore and retrieve processing options (continued)
Option
Description
fromdate “Fromdate” on page 416
Use the fromdate option with the fromtime option
to specify a date and time from which you want to
search for backups or archives during a restore,
retrieve, or query operation.
fromnode “Fromnode” on page 416
Permits one node to perform commands for another
node. A user on another node must use the set
access command to give you permission to query,
restore, or retrieve files or images for the other
node.
fromtime “Fromtime” on page 417
Use the fromtime option with the fromdate option
to specify a beginning time from which you want
to search for backups or archives during a restore,
retrieve, or query operation.
ifnewer “Ifnewer” on page 422
Replaces an existing file with the latest backup
version only if the backup version is newer than
the existing file.
imagetofile “Imagetofile” on page
423
Use the imagetofile option with the restore image
command to specify that you want to restore the
source image to a file. You might need to restore
the image to a file in the event of bad sectors
present on the target volume, or if you want to do
some manipulations with the image data.
inactive “Inactive” on page 424
Displays a list of active and inactive files when
used with the pick option.
latest “Latest” on page 452
Restores the most recent backup version of a file
whether it is active or inactive.
localbackupset “Localbackupset” on
page 453
Specifies whether the backup-archive client GUI
bypasses initial logon with the server to restore a
local backup set on a stand-alone workstation.
monitor “Monitor” on page 464
Specifies whether you want to monitor an image
restore of one or more file systems that belong to a
network-attached storage (NAS) file server.
noprompt “Noprompt” on page 470
suppresses the confirmation prompt that is
presented by the delete group, delete archive,
expire, restore image, and set event commands.
optfile “Optfile” on page 474
Specifies the client options file you want to use
when you start a backup-archive client session.
pick “Pick” on page 477
Creates a list of backup versions, images, or archive
copies that match the file specification you enter.
From the list, you can select the versions to process.
Include the inactive option to view both active
and inactive objects.
pitdate “Pitdate” on page 478
Use the pitdate option with the pittime option to
establish a point in time for which you want to
display or restore the latest version of your
backups.
pittime “Pittime” on page 479
Use the pittime option with the pitdate option to
establish a point in time for which you want to
display or restore the latest version of your
backups.
Chapter 11. Processing options
303
Table 40. Restore and retrieve processing options (continued)
Option
Description
preservepath “Preservepath” on page
486
Specifies how much of the source path to reproduce
as part of the target directory path when you
restore or retrieve files to a new location.
replace “Replace” on page 494
Specifies whether to overwrite an existing file, or to
prompt you for your selection when you restore or
retrieve files.
showmembers “Showmembers” on page
524 (does not apply to Mac OS X)
Displays all members of a group.
subdir “Subdir” on page 549
Specifies whether you want to include
subdirectories of a named directory.
tapeprompt “Tapeprompt” on page 552
Specifies whether you want the backup-archive
client to wait for a tape that is required for a restore
or retrieve to be mounted, or to prompt you for
your choice.
todate “Todate” on page 563
Use the todate option with the totime option to
specify an ending date and time to which you want
to search for backups or archives during a restore,
retrieve, or query operation.
totime “Totime” on page 564
Use the totime option with the todate option to
specify an ending date and time to which you want
to search for backups or archives during a restore,
retrieve, or query operation.
type “Type” on page 566
Use the type option with the query node command
to specify the type of node to query.
verifyimage “Verifyimage” on page
571
Use the verifyimage option with the restore image
command to specify that you want to enable
detection of bad sectors on the destination target
volume. If bad sectors are detected on the target
volume, the client issues a warning message on the
console and in the error log.
The following options are backup-archive client options that apply to IBM
Spectrum Protect HSM for Windows migrated files. For more information about
these options, see the IBM Knowledge Center topics at http://www.ibm.com/
support/knowledgecenter/SSERFH_8.1.2/hsmwin/welcome.html.
v Checkreparsecontent
v Restorecheckstubaccess
v Restoremigstate
v Skipmigrated
The following options are backup-archive client options that apply to IBM
Spectrum Protect for Space Management migrated files. For more information
about these options, see the IBM Knowledge Center topics at http://
www.ibm.com/support/knowledgecenter/SSERBH_8.1.2/hsmul/welcome.html.
v Restoremigstate
v Skipmigrated
304
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Scheduling options
This topic discusses the options that you can use to regulate central scheduling.
The backup-archive client uses scheduling options only when the Scheduler is
running.
Table 41 lists the scheduling options that are available.
Table 41. Scheduling options
Option
Description
cadlistenonport “Cadlistenonport” on page
334
Specifies whether to open listening ports for
the client acceptor when the client acceptor is
used to manage schedules in polling mode.
managedservices “Managedservices” on page
454
Specifies whether the client acceptor manages
the web client, the scheduler, or both.
maxcmdretries “Maxcmdretries” on page 456
Specifies the maximum number of times the
client scheduler attempts to process a
scheduled command that fails.
postschedulecmd/postnschedulecmd
“Postschedulecmd/Postnschedulecmd” on
page 480
Specifies a command to process after running
a schedule.
preschedulecmd/prenschedulecmd
“Preschedulecmd/Prenschedulecmd” on page
483
Specifies a command to process before
running a schedule.
queryschedperiod “Queryschedperiod” on
page 490
Specifies the number of hours the client
scheduler waits between attempts to contact
the server for scheduled work.
retryperiod “Retryperiod” on page 507
Specifies the number of minutes the client
scheduler waits between attempts to process
a scheduled command that fails or between
unsuccessful attempts to report results to the
server.
runasservice “Runasservice” on page 508
Forces the client command process to
continue running, even if the account that
started the client logs off. Use this option on
all Windows clients.
schedcmddisabled “Schedcmddisabled” on
page 509
Specifies whether to disable the scheduling
of generic commands specified by your IBM
Spectrum Protect administrator.
schedlogmax “Schedlogmax” on page 512
Specifies the maximum size of the scheduler
log and web client log, in megabytes.
schedlogname “Schedlogname” on page 514
Specifies the path and file name where you
want to store schedule log information.
schedlogretention “Schedlogretention” on
page 515
Specifies the number of days to keep log file
entries in the schedule log and the web client
log, and whether to save pruned entries.
schedmode “Schedmode” on page 516
Specifies which schedule mode to use, polling
or prompted.
schedrestretrdisabled
“Schedrestretrdisabled” on page 518
Specifies whether to prevent the IBM
Spectrum Protect Server administrator from
executing restore or retrieve schedule
operations.
Chapter 11. Processing options
305
Table 41. Scheduling options (continued)
Option
Description
sessioninitiation “Sessioninitiation” on
page 520
Use the sessioninitiation option to control
whether the server or client initiates sessions
through a firewall. The default is that the
client can initiate sessions.
srvprepostscheddisabled
“Srvprepostscheddisabled” on page 540
Specifies whether to prevent the IBM
Spectrum Protect Server administrator from
executing pre-schedule and post-schedule
commands when performing scheduled
operations.
srvprepostsnapdisabled
“Srvprepostsnapdisabled” on page 541
Specifies whether to prevent the IBM
Spectrum Protect Server administrator from
executing pre-snapshot and post-snapshot
commands when performing scheduled
image snapshot backup operations.
tcpclientaddress “Tcpclientaddress” on
page 556
Specifies a TCP/IP address if your client
node has more than one address, and you
want the server to contact an address other
than the one that was used to make the first
server contact. The server uses this address
when it begins the server prompted
scheduled operation. See schedmode prompted
(“Schedmode” on page 516) for details.
tcpclientport “Tcpclientport” on page 557
Specifies a TCP/IP port number for the
server to contact the client when the server
begins the server prompted scheduled
operation. See schedmode prompted
(“Schedmode” on page 516) for details.
Format and language options
Format and language options allow you to select different formats for date, time
and numbers for different languages.
Table 42. Format and language options
Option
Description
dateformat “Dateformat” on
page 352
Specifies the format for displaying dates.
language “Language” on page
451
Specifies the language used for messages.
numberformat “Numberformat”
on page 472
Specifies the format for displaying numbers.
timeformat “Timeformat” on
page 561
Specifies the format for displaying time.
Command processing options
This topic explains the options that you can use with the backup-archive client
commands.
Command processing options allow you to control some of the formatting of data
on your terminal screen.
306
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 43. Command processing options
|
|
|
Option
Description
quiet “Quiet” on page 492
Limits the number of messages that are displayed on your
screen during processing. This option can be overridden by
the server.
scrolllines “Scrolllines” on
page 518
Specifies the number of lines of information that are
displayed on your screen at one time. Use this option only
when scrollprompt is set to yes.
scrollprompt “Scrollprompt”
on page 519
Specifies whether you want the backup-archive client to
stop and wait after displaying the number of lines of
information you specified with the scrolllines option, or
scroll through and stop at the end of the information list.
setwindowtitle
“Setwindowtitle” on page 522
Specifies whether to display the IBM Spectrum Protect
server name and host server name in the title of the
administrative client command window.
verbose “Verbose” on page 570 Specifies that processing information should be displayed
on your screen. The alternative is quiet. This option can be
overridden by the server.
|
Authorization options
|
Authorization options control access to the IBM Spectrum Protect server.
|
Table 44 lists the authorization options that are available.
|
Table 44. Authorization options
|
Option
|
|
autodeploy“Autodeploy” on page Specifies whether you want to enable or disable an
328
automatic deployment of the client if a restart is required.
|
|
password “Password” on page
474
Specifies the IBM Spectrum Protect password.
|
|
|
passwordaccess
“Passwordaccess” on page 476
Specifies whether you want to use a generated password
or be prompted for a password each time you start the
client.
|
|
|
|
revokeremoteaccess
“Revokeremoteaccess” on page
507
Restricts an administrator with client access privileges
from accessing your workstation through the web client.
Description
|
Error processing options
Error processing options specify the name of the error log file and how the
backup-archive client treats the entries in the log file.
Table 45 lists the error processing options that are available.
Table 45. Error processing options
Option
Description
errorlogmax “Errorlogmax”
on page 391
Specifies the maximum size of the error log, in megabytes.
errorlogname “Errorlogname”
on page 392
Specifies the fully qualified path and file name of the file
where you want to store information about errors that occur
during processing.
Chapter 11. Processing options
307
Table 45. Error processing options (continued)
Option
Description
errorlogretention
“Errorlogretention” on page
393
Specifies how many days to maintain error log entries
before pruning, and whether to save the pruned entries.
Transaction processing options
Transaction processing options control how transactions are processed between the
IBM Spectrum Protect client and server.
Table 46 lists the transaction processing options that are available.
Table 46. Transaction processing options
308
Option
Description
collocatebyfilespec
“Collocatebyfilespec” on
page 342
Specifies that you want the backup-archive client to use only
one server session to send objects generated from one file
specification. Setting the collocatebyfilespec option to yes
eliminates interspersing of files from different file
specifications, by limiting the client to one server session per
file specification. Therefore, if you store the data to tape,
files for each file specification are stored together on one
tape (unless another tape is required for more capacity).
commrestartduration
“Commrestartduration” on
page 344
Specifies the maximum number of minutes you want the
client to try to reconnect to the IBM Spectrum Protect server
after a communication error occurs.
commrestartinterval
“Commrestartinterval” on
page 345
Specifies the number of seconds you want the client to wait
between attempts to reconnect to the IBM Spectrum Protect
server after a communication error occurs.
diskbuffsize “Diskbuffsize”
on page 365
Specifies the maximum disk I/O buffer size (in kilobytes)
that the client can use when reading files.
largecommbuffers
“Diskbuffsize” on page 365
This option has been replaced by the diskbuffsize option.
At this time, largecommbuffers is still accepted by the
backup-archive client in order to ease the transition to the
new option. However, the value specified by
largecommbuffers is ignored in favor of the diskbuffsize
setting.
Important: Discontinue the use of largecommbuffers
because future releases of the client might not accept this
option.
resourceutilization
“Resourceutilization” on
page 504
Use the resourceutilization option in your client options
file dsm.opt to regulate the level of resources the IBM
Spectrum Protect server and client can use during
processing.
txnbytelimit “Txnbytelimit”
on page 565
Specifies the number of kilobytes the client program buffers
before it sends a transaction to the server.
usedirectory “Usedirectory”
on page 567
Provides a convenient way to simplify client communication
configuration by overriding commmethod parameters set in
the client options file and instead querying the Active
Directory for the communication method and server with
which to connect.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Web client options
Several backup-archive client options are used to configure the IBM Spectrum
Protect web client.
Table 47 lists the web client options that are available.
Table 47. Web client options
Option
Description
httpport “Httpport” on page 419
Specifies a TCP/IP port address for the web client.
managedservices
“Managedservices” on page 454
Specifies whether the client acceptor service manages the
web client, the scheduler, or both.
revokeremoteaccess
“Revokeremoteaccess” on page
507
Restricts administrator access on a client workstation
through the web client.
webports “Webports” on page 631
Enables the use of the web client outside a firewall by
specifying the TCP/IP port number used by the client
acceptor service and the web Client Agent service for
communications with the web client.
Diagnostics options
Use the query systeminfo command to gather IBM Spectrum Protect system
information and output this information to a file or the console.
The query systeminfo command is intended primarily as a diagnostic aid. You can
submit the resulting information to technical support personnel for problem
diagnosis.
Table 48 lists the diagnostics options that are available.
Table 48. Diagnostics options
Option
Description
console “Console” on page 348
Use the console option with the query systeminfo
command to output system information to the console.
filename “Filename” on page 413
Use the filename option with the query systeminfo
command to specify a file name in which to store the
system information.
Related reference:
“Query Systeminfo” on page 726
Using options with commands
You can override some of the options in your client options file (dsm.opt) file by
entering them with appropriate backup-archive client commands.
The client processes options in the following order (precedence):
1. Options defined on the server with server-enforced client options. The server
overrides client values.
2. Options entered locally on the command line.
3. Options defined on the server for a schedule using the options parameters.
4. Options entered locally in the options file.
Chapter 11. Processing options
309
5. Options received from the server with client option sets not set as forced by the
server. The server does not override client values if not forced.
6. Default option values.
The client also includes a group of client command options that you can enter only
on the command line with specific commands. For a complete list of command-line
options, a description, and where to go for more information, see Table 49 on page
311.
Entering options with a command
You must follow the general rules for entering options with a command.
v Enter a command, a dash (–), the option name, an equal sign (=), and the option
value or parameter. Do not include spaces on either side of the = sign.
Here are examples of this syntax on different clients:
dsmc archive -description="Project A" c:\devel\proj1\*
v For options that do not include parameters, enter a command, a dash (–), and
the option name. For example,
dsmc incremental -quiet
Note: Use a leading dash (-) to indicate that the following text is the name of an
option. If an object name begins with a dash, you must surround it in either
single quotation marks (') or quotation marks ("). Most operating system
command line processors strip the quotation marks before the command-line
arguments are submitted to the IBM Spectrum Protect client application. In such
cases, by using escape characters or doubling the quotation marks allows the
client to receive the quoted object name. In loop mode, surround such objects in
either single quotation marks (') or quotation marks (").
v Enter either the option name, or an abbreviation for the option name. For
example, to enter the latest option, enter either -lat or -latest. The capital
letters in the syntax of each option indicate the minimum abbreviation for that
option name.
v Enter options before or after command parameters. For example, you can enter
the option before or after a file specification:
dsmc selective -subdir=yes c:\devel\proj1\*
dsmc selective c:\devel\proj1\* -subdir=yes
v When you enter several options on a command, separate them with a blank
space.
v Enclose the value in quotation marks (" ") if the option value that you enter
contains a blank space. For example:
dsmc archive -description="Project A" c:\devel\proj1\*
v Most options that you enter on the command line override the value that is set
in the preferences file. However, when you use the domain option with the
incremental command, it adds to the domain specified in your client options file
rather than overriding the current value.
v The maximum number of bytes for a file name and file path is 6255 combined.
However, the file name itself cannot exceed 255 bytes and the path that leads to
the file cannot exceed 6000 bytes. Furthermore, directory names (including the
directory delimiter) within a path are limited to 255 bytes. The Unicode
representation of a character can occupy several bytes, so the maximum number
of characters that a file name might contain can vary.
Table 49 on page 311 lists client command options that you can enter only on the
command line with specific commands.
310
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 49. Client command options
Command option
Description
Commands
archmc “Archmc” on page
319
Use the archmc option with the archive command to
specify the available management class for your policy
domain to which you want to bind your archived files.
archive
class “Class” on page 337
Specifies whether to display a list of NAS objects or client
objects when you use the following commands.
query backup
delete filespace
query filespace
restore systemstate
restore backupset
console “Console” on page
348
Use the console option with the query systeminfo
command to output system information to the console.
deletefiles “Deletefiles”
on page 357
Deletes the local copy of files from your workstation after
they are archived on the server. Can also be used with
archive
the restore image command and the incremental option restore image
to delete files from the restored image that are deleted
from the file space after the image is created.
description “Description”
on page 358
Assigns or specifies a description for files when archive,
delete, retrieve, or query archive operations are
performed.
detail “Detail” on page
359
Displays management class, file space, backup, and
archive information, depending on the command with
which it is used.
dirsonly “Dirsonly” on
page 364
Backs up, restores, archives, retrieves, or queries
directories only.
filelist “Filelist” on
page 410
Specifies a list of files to be processed for the command.
The backup-archive client opens the designated file list
and processes the files that are listed within according to
the command.
filename “Filename” on
page 413
Use the filename option with the query systeminfo
command to specify a file name in which to store the
system information.
query systeminfo
archive
delete archive
query archive
query backupset
retrieve
delete
query
query
query
query
filespace
archive
backup
filespace
mgmtclass
archive
incremental
query archive
query backup
restore
restore backupset
retrieve
selective
archive
backup group
delete archive
delete backup
expire
incremental
query archive
query backup
restore
retrieve
selective
query systeminfo
Chapter 11. Processing options
311
Table 49. Client command options (continued)
Command option
Description
filesonly “Filesonly” on
page 414
Backs up, restores, retrieves, or queries files only.
fromdate “Fromdate” on
page 416
Use the fromdate option with the fromtime option to
specify a date and time from which you want to search
for backups or archives during a restore, retrieve, or
query operation.
fromnode “Fromnode” on
page 416
Permits one node to perform commands for another
node. A user on another node must use the set access
query archive
command to permit you to query, restore, or retrieve files query backup
or images for the other node.
query filespace
query group
query image
query mgmtclass
restore
restore group
restore image
retrieve
fromtime “Fromtime” on
page 417
Specifies a beginning time on the specified date. Use with
the fromdate option. This option is ignored if the
query archive
fromdate option is absent.
query backup
restore
restore group
retrieve
groupname “Groupname” on
page 418
Specifies the fully qualified name for a group.
ifnewer “Ifnewer” on page
422
Replaces existing files with the latest backup version only
if the backup version is newer than the existing version.
restore
restore backupset
restore group
retrieve
imagetofile “Imagetofile”
on page 423
Use the imagetofile option with the restore image
command to specify that you want to restore the source
image to a file. You might need to restore the image to a
file in the event of bad sectors present on the target
volume, or if you want to do some manipulations with
the image data.
312
Commands
archive
incremental
query archive
query backup
restore
restore backupset
retrieve
selective
delete backup
query archive
query backup
restore
restore group
retrieve
backup group
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
restore image
Table 49. Client command options (continued)
Command option
Description
Commands
inactive “Inactive” on
page 424
Displays a list of active and inactive files when used with
the pick option.
delete group
query backup
query group
query image
query nas
query systemstate
restore
restore group
restore image
restore nas
restore systemstate
incrbydate “Incrbydate”
on page 442
Requests an incremental backup by date.
incremental “Incremental”
on page 443
Applies changes to the base image by using information restore image
from incremental backups that are made after the original
image backup.
latest “Latest” on page
452
Restores the most recent backup version of a file whether
it is active or inactive.
restore
restore group
mode “Mode” on page 460
Use the mode option with these commands, as follows:
incremental
backup image
To specify whether to perform a selective or
incremental image backup of client file systems.
backup group
backup nas
backup image
restore nas
backup nas
To specify whether to perform a full or
differential image backup of NAS file systems.
backup group
To specify whether to perform a full or
differential group backup that contains a list of
files from one or more file space origins.
monitor “Monitor” on page
464
Specifies whether you want to monitor an image backup
or restore of one or more file systems that belong to a
network-attached storage (NAS) file server.
nojournal “Nojournal” on
page 470
Use this option with the incremental command to specify incremental
that you want to perform the traditional full incremental
backup, instead of the default journal-based backup.
noprompt “Noprompt” on
page 470
Suppresses the confirmation prompt that is presented by
the delete group, delete archive, expire, restore image,
and set event commands.
optfile “Optfile” on page
474
Specifies the client options file you want to use when you dsmc.exe
start a backup-archive client session.
backup nas
restore nas
delete archive
delete backup
delete group
expire
restore image
Chapter 11. Processing options
313
Table 49. Client command options (continued)
Command option
Description
pick “Pick” on page 477
Creates a list of backup versions, images, or archive
copies that match the file specification you enter. From
delete archive
the list, you can select the versions to process. Include the delete group
inactive option to view both active and inactive objects. expire
query nas
restore
restore asr
restore group
restore image
restore nas
retrieve
pitdate “Pitdate” on page
478
Use the pitdate option with the pittime option to
establish a point in time for which you want to display
or restore the latest version of your backups.
pittime “Pittime” on page
479
Use the pittime option with the pitdate option to
establish a point in time for which you want to display
or restore the latest version of your backups.
preservepath
“Preservepath” on page
486
Specifies how much of the source path to reproduce as
part of the target directory path when you restore or
retrieve files to a new location.
runasservice
“Runasservice” on page
508
Forces the client command process to continue running,
even if the account that started the client logs off. Use
this option on all Windows clients.
showmembers “Showmembers”
on page 524
Displays all members of a group.
314
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Commands
query backup
query group
query image
query nas
query systemstate
restore
restore group
restore image
restore nas
restore systemstate
All query and restore
system object
commands
query backup
query image
query nas
query systemstate
restore
restore image
restore nas
restore systemstate
All query and
restore system
object commands
restore
restore backupset
restore group
retrieve
schedule
query group
query systemstate
restore group
Table 49. Client command options (continued)
Command option
Description
Commands
todate “Todate” on page
563
Use the todate option with the totime option to specify
an ending date and time to which you want to search for query archive
backups or archives during a restore, retrieve, or query
query backup
operation.
restore
restore group
retrieve
totime “Totime” on page
564
Use the totime option with the todate option to specify
an ending date and time to which you want to search for query archive
backups or archives during a restore, retrieve, or query
query backup
operation.
restore
restore group
retrieve
type “Type” on page 566
Use the type option with the query node command to
specify the type of node to query.
v2archive “V2archive” on
page 570
Use the v2archive option with the archive command to
archive only files to the server. The client will not process archive
directories that exist in the path of the source file
specification.
verifyimage “Verifyimage”
on page 571
Use the verifyimage option with the restore image
restore image
command to specify that you want to enable detection of
bad sectors on the destination target volume. If bad
sectors are detected on the target volume, the client
issues a warning message on the console and in the error
log. This option is valid for all Windows clients.
virtualfsname
“Virtualfsname” on page
572
Specifies the name of the virtual file space for the group
on which you want to run the operation.
query node
backup group
Initial command-line-only options
A subset of client options is valid on the initial command line only. Many of these
options establish the runtime environment, such as the commmethod and optfile
options. Options in this category are not valid in interactive, macro, or scheduler
modes. They generate an error and cause processing to stop.
Table 50 on page 316 lists the options that are valid only on the initial command
line.
Chapter 11. Processing options
315
Table 50. Options that are valid on the initial command line only
Options valid on the initial command line
asrmode
preschedulecmd/prenschedulecmd (can be
backupregistry
included in the schedule definition)
commmethod
presnapshotcmd
computername
queryschedperiod
deduplication
resourceutilization
diskbuffsize
retryperiod
editor
runasservice
enablededupcache
schedlogmax
enablelanfree
schedlogname
errorlogmax
schedlogretention
errorlogname
schedmode
errorlogretention
sessioninitiation
incrthreshold
setwindowtitle
lanfreecommmethod
tcpbuffsize
lanfreeshmport
tcpcadaddress
lanfreetcpport
tcpclientaddress
maxcmdretries
tcpclientport
namedpipename
tcpport
nodename
tcpserveraddress
optfile
tcpwindowsize
password
txnbytelimit
postschedulecmd/postnschedulecmd (can
usedirectory
be included in the schedule definition)
virtualnodename
postsnapshotcmd
Client options that can be set by the IBM Spectrum Protect
server
Some client options can be set by the IBM Spectrum Protect server.
Table 51 on page 317 lists the options that can be set by the server.
316
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 51. Options that can be set by the IBM Spectrum Protect server
Options that can be set by the IBM
Spectrum Protect server
v “Casesensitiveaware” on page 335
v “Queryschedperiod” on page 490
v “Changingretries” on page 336
v “Quiet” on page 492
v “Collocatebyfilespec” on page 342
v “Resetarchiveattribute” on page 502
v “Compressalways” on page 346
v “Resourceutilization” on page 504
v “Compression” on page 347
v “Retryperiod” on page 507
v “Deduplication” on page 356
v “Schedmode” on page 516
v “Dirmc” on page 363
v “Scrolllines” on page 518
v “Disablenqr” on page 364
v “Scrollprompt” on page 519
v “Diskcachelocation” on page 366
v “Snapshotproviderfs” on page 536
v “Domain” on page 367
v “Snapshotproviderimage” on page 536
v “Domain.image” on page 370
v “Stagingdirectory” on page 548
v “Domain.nas” on page 371
v “Subdir” on page 549
v “Encryptiontype” on page 388
v “Tapeprompt” on page 552
v “Encryptkey” on page 389
v “Txnbytelimit” on page 565
v “Exclude options” on page 395
v “Verbose” on page 570
v “Inclexcl” on page 425
v “Vmchost” on page 579
v “Include options” on page 426
v “Vmcuser” on page 582
v maxcandprocsmaxcandprocs
v maxmigratorsmaxmigrators
v “Vmprocessvmwithindependent” on page
609
v “Memoryefficientbackup” on page 458
v “Vmprocessvmwithprdm” on page 611
v “Postschedulecmd/Postnschedulecmd” on
page 480
v “Postsnapshotcmd” on page 482
v “Preschedulecmd/Prenschedulecmd” on
page 483
v “Preservelastaccessdate” on page 485
v “Presnapshotcmd” on page 488
Note:
1. See IBM Spectrum Protect for Space Management product documentation on
IBM Knowledge Center at http://www.ibm.com/support/knowledgecenter/
SSERBH/welcome.
2. See IBM Spectrum Protect for Mail: Data Protection for Microsoft Exchange
Server product documentation on IBM Knowledge Center at
http://www.ibm.com/support/knowledgecenter/SSERBW/welcome.
Related tasks:
Controlling client operations through client option sets
Client options reference
The following sections contain detailed information about each of the IBM
Spectrum Protect processing options.
Information for each option includes the following information:
v A description
v A syntax diagram
Chapter 11. Processing options
317
v Detailed descriptions of the parameters
v Examples of using the option in the client options file (if applicable)
v Examples of using the option on the command line (if applicable)
Options with a command-line example of Does not apply cannot be used with
command line or scheduled commands.
Absolute
Use the absolute option with the incremental command to force a backup of all
files and directories that match the file specification or domain, even if the objects
were not changed since the last incremental backup.
This option overrides the management class copy group mode parameter for
backup copy groups; it does not affect the frequency parameter or any other
backup copy group parameters. This option does not override exclude statements,
so objects that are excluded from backup are not eligible for backup even when the
absolute option is specified.
Important: Before you use the absolute option, consider the following effects that
this option can have on backup and IBM Spectrum Protect server operations:
v Backups consume more server storage and database resources.
v Backups consume more network bandwidth.
v Server operations, such as inventory expiration, storage pool backup, storage
pool migration, reclamation, and node replication, require more time to
complete. Data deduplication might help mitigate some of these effects, but it
does not avoid the processing that is required to reconstitute the deduplicated
data back to its original form when the storage pool is migrated or backed up to
non-deduplicated storage.
This option is valid only as a command-line parameter for the incremental
command when you are performing the following operations:
v Full or partial progressive incremental backups of file systems or disk drives.
v Snapshot differential backups when createnewbase=yes is also specified.
To force a full backup of a file system that uses journal-based backup, specify both
the nojournal and absolute options on the incremental command.
During a domain incremental backup, where systemstate is specified as part of the
domain, the absolute option does not force a full backup of system state objects.
To force a domain incremental backup operation to create a full backup of system
state objects, you must add systemstatebackupmethod full to the client options
file.
To use the absolute option on scheduled incremental backups, the IBM Spectrum
Protect server administrator must create a separate backup schedule that includes
the absolute option on the schedule’s options parameter.
Supported Clients
This option is valid for all clients as a command-line parameter for the
incremental command. This option cannot be added to a client option set on the
IBM Spectrum Protect server.
318
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Syntax
►► ABSolute
►◄
Parameters
There are no parameters for this option.
Examples
Command line:
dsmc incr -absolute c:\foo\*.c
Adlocation
You can use the adlocation option with the query adobjects or restore adobjects
commands to indicate whether the Active Directory objects are to be queried or
restored from the local Active Directory Deleted Objects container or from a system
state backup on the IBM Spectrum Protect server.
Supported Clients
This option is valid for supported Windows Server clients. The IBM Spectrum
Protect API does not support this option.
Syntax
local
►► ADLOCation
►◄
server
Parameters
server
Specifies that the Active Directory objects are to be queried or restored from a
system state backup on the IBM Spectrum Protect server. Valid for all
supported Windows server clients.
local
Specifies that the Active Directory objects are to be queried or restored from
the local Active Directory Deleted Objects container. This is the default.
Example
Command line:
query adobjects "cn=Jim Smith" -adlocation=server
Archmc
Use the archmc option with the archive command to specify the available
management class for your policy domain to which you want to bind your
archived files and directories.
When you archive a file, you can override the assigned management class using
the archmc option on the archive command or by using the web client. Overriding
the management class using the web client is equivalent to using the archmc option
on the archive command.
Chapter 11. Processing options
319
If you do not use the archmc option, the server binds archived directories to the
default management class. If the default management class has no archive copy
group, the server binds archived directories to the management class with the
shortest retention period.
Supported Clients
This option is valid for all Windows clients. The IBM Spectrum Protect API does
not support this option.
Syntax
►► ARCHMc = managementclass
►◄
Parameters
managementclass
Specifies an available management class in the active policy set of your policy
domain. This management class overrides the default management class and
any include statements for the files and directories you are archiving.
Examples
Command line:
dsmc archive –archmc=ret2yrs c:\plan\proj1\budget.jan\*
Asnodename
Use the asnodename option to allow an agent node to back up, archive, restore,
retrieve, and query data on behalf of a target node.
An agent node is a client node that the IBM Spectrum Protect administrator grants
the authority to perform client operations on behalf of a target node. The target
node is the client node that the agent node performs the actions for. The
administrator uses the grant proxynode command on the IBM Spectrum Protect
server to grant this authority.
Agent nodes can be used to distribute the workload of backing up a computer’s
volumes, across multiple client systems. Each system that is involved in the
backup uses its own agent node name, but the backup data is stored in a common
file space that is owned by the target node.
For example, assume that you plan to back up four volumes that belong to a node
that is named SCORPIO, but the backup operation takes too long to run. You can
distribute part of the workload to three other machines: TAURUS, ARIES, and
LEO. SCORPIO and the three other machines each back up one of SCORPIO’s
volumes. Each node that is involved in the backup connects to the server by using
its own agent node name, and each node specifies a unique value for the
asnodename option. Do not use a computer name or cluster name for the
asnodename value. The following table illustrates an example configuration.
Table 52. Setting the value of the asnodename option to distribute backups.
Host
name
NODENAME
option value
ASNODENAME
option value
Volume
backed up
Server file space
name
SCORPIO
SCORPIO
TARGET_SCORPIO
\\scorpio\r$
\\target_scorpio\r$
320
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 52. Setting the value of the asnodename option to distribute backups. (continued)
Host
name
NODENAME
option value
ASNODENAME
option value
Volume
backed up
Server file space
name
TAURUS
TAURUS
TARGET_SCORPIO
\\scorpio\s$
\\target_scoprio\s$
ARIES
ARIES
TARGET_SCORPIO
\\scorpio\t$
\\target_scoprio\t$
LEO
LEO
TARGET_SCORPIO
\\scorpio\u$
\\target_scorpio\u$
To create the relationships between the target node and the proxy nodes, the IBM
Spectrum Protect server administrator needs to take the following actions:
1. Register nodes SCORPIO, TAURUS, ARIES, LEO, and TARGET_SCORPIO.
2. Grant nodes SCORPIO, TAURUS, ARIES, and LEO proxy authority to node
TARGET_SCORPIO
When you back up or archive data without the asnodename option, the backed up
data is stored in a file space on the server that matches the UNC name of the drive
on which the original data exists.
When you use the asnodename option to back up data on behalf of a target node,
the data is stored in a file space that is owned by the target node. However,
instead of using the host name in the file space name, the target node name is
used in the file space name. For example, if node TAURUS backs up data on
SCORPIO's S drive and sets the asnodename option value to
-asnodename=target_scorpio, the backup data is stored in a file space named
\\target_scorpio\s$. The file space is owned by the TARGET_SCORPIO node.
When you restore or retrieve data, the default behavior is to restore or retrieve the
data to a location that matches the file space name.
Continuing with the preceding example, if node SCORPIO uses
-asnodename=target_scorpio to restore data from \\target_scorpio\s$, the client
attempts to restore the data to the S drive on a computer named
TARGET_SCORPIO. This operation does not produce the expected result because,
in this sample configuration, there is no computer that is named
TARGET_SCORPIO.
In the following example, the restore command is entered on the SCORPIO node.
The command restores all files and subdirectories from the Users\andy\education
directory in the \\target_scorpio\s$ file space to the S drive on the computer that
is named SCORPIO:
dsmc restore \\target_scorpio\s$\users\andy\education\* s:\
-subdir=yes -asnodename=target_scorpio
The following considerations apply when you use a proxy node to back up or
restore data on other nodes:
v A proxy operation uses the settings for the target node (such as maxnummp and
deduplication) and schedules that are defined on the IBM Spectrum Protect
server. The IBM Spectrum Protect server node settings and schedules for the
agent node are ignored.
v You cannot use asnodename with the backup nas command.
v You cannot use asnodename with the fromnode option.
v If you use asnodename to backup and restore volumes that are in a cluster
configuration, do not use clusternode yes.
Chapter 11. Processing options
321
v You cannot use asnodename to back up or restore system state.
v If an agent node restores data from a backup set, the system state object in the
backup set is not restored.
v You can use asnodename with the backup image command, but you must specify
the volume by UNC name. You cannot use the drive letter.
v If you use the same asnodename value to back up files from different machines,
you need to keep track which files or volumes are backed up from each system
so that you can restore them to the correct location.
v All agent nodes in a multiple node environment should be of the same platform
type.
v Do not use target nodes as traditional nodes, especially if you encrypt your files
before backing them up to the server.
Supported Clients
This option is valid for all Windows clients.
Options File
Place this option in the dsm.opt file. You can set this option on the General tab of
the Preferences editor.
Syntax
►► ASNODEname
targetnode
►◄
Parameters
targetnode
Specifies the node name on the IBM Spectrum Protect server under which you
want to back up or restore data.
Examples
Options file:
asnodename target_scorpio
Command line:
This command backs up the entire F: drive to a server file space named
\\target_scorpio\f$.
dsmc incremental f: -asnodename=target_scorpio
This option is not valid in interactive mode, but it can be defined in the options
portion of a schedule definition.
Session settings and schedules for a proxy operation
A proxy operation occurs when an agent node uses the asnodename
target_node_name option to complete operations on behalf of the specified target
node.
A proxy operation uses the settings for the target node (such as maxnummp,
cloptset, and deduplication) and schedules that are defined on the IBM Spectrum
Protect server. The server node settings and schedules for the agent node are
ignored.
322
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
The following considerations apply to proxy operations.
v All operations use the policy domain settings and constructs of the target node,
even if the agent node belongs to a different domain. The policy domain settings
and constructs of the agent node are ignored.
v The agent node authenticates to the IBM Spectrum Protect server by using the
agent node's password.
v In order to run proxy operations, the agent node and target node must not be
locked on the server.
v Proxy node relationships are not transitive. If a target node is itself defined as a
proxy node for some other node, the agent node cannot be used to run
operations on that other node unless the agent is also defined as a proxy node
for that other node.
For example, assume the following proxy definitions among nodes TAURUS,
SCORPIO, and GEMINI:
– TAURUS is a proxy node for SCORPIO.
– TAURUS is not a proxy node for GEMINI.
– SCORPIO is a proxy node for GEMINI.
The proxy definitions yield the following results:
– TAURUS can run operations on behalf of SCORPIO.
– SCORPIO can run operations on behalf of GEMINI.
– TAURUS cannot run operations on behalf of GEMINI.
Asrmode
Use the asrmode option with the restore and restore systemstate commands to
specify whether to perform a restore operation in system ASR recovery mode.
This option is used in the context of restore commands generated in the asr.sif
file by the backup asr command only.
Supported Clients
This option is valid for supported Windows clients that are running in a Windows
Preinstallation Environment; both BIOS and UEFI boot architectures are supported.
Syntax
►► ASRMODE =
►◄
No
Yes
Parameters
No Specifies that the client does not perform the restore operation in system ASR
recovery mode.
Yes
Specifies that the client performs the restore operation in ASR recovery mode.
This is the default for Windows clients during ASR recovery. These clients are
running in Windows Preinstallation Environment (WinPE) during ASR
recovery.
Chapter 11. Processing options
323
Examples
Command line:
restore systemstate -asrmode=yes
restore systemstate -asrmode=yes -inactive -pick
This option is valid for an interactive session, but cannot be changed by
entering the option while running an interactive session.
Auditlogging
Use the auditlogging option to generate an audit log that contains an entry for
each file that is processed during an incremental, selective, archive, restore, or
retrieve operation.
The audit log can be configured to capture either a basic level of information or a
more inclusive (full) level of information.
The basic level of the audit logging feature captures the information that is in the
schedule log and it records information that a file has been backed up, archived,
updated, restored, retrieved, expired, deleted, skipped or failed during an
incremental backup, selective backup, archive, restore or retrieve operation. In
addition, the basic level of audit logging captures the input command for
commands run through the backup-archive command line or scheduler clients.
The full level of audit logging records an action for each file that is processed by
the backup-archive client. In addition to all of the events recorded by the basic
level of audit logging, the full level of audit logging records information for a file
that has been excluded or not sent during a progressive incremental backup
operation because the file had not changed.
The following is an example of the messages that are issued when the audit log is
configured to capture the basic level of information:
04/21/07 15:25:05 ANS1650I
sel c:\test\file.txt
04/21/07 15:25:05 ANS1651I
\\spike\c$\test\file.txt
04/21/07 15:25:05 ANS1652I
\\spike\c$\test\file.txt
04/21/07 15:25:05 ANS1653I
\\spike\c$\test\file.txt
04/21/07 15:25:05 ANS1654E
\\spike\c$\test\file.txt
04/21/07 15:25:05 ANS1655I
\\spike\c$\test\file.txt
04/21/07 15:25:05 ANS1656I
\\spike\c$\test\file.txt
04/21/07 15:25:05 ANS1657I
\\spike\c$\test\file.txt
04/21/07 15:25:05 ANS1658I
\\spike\c$\test\file.txt
04/21/07 15:25:05 ANS1659I
\\spike\c$\test\file.txt
Command:
Backed Up:
Archived:
Updated:
Failed:
Restored:
Retrieved:
Expired:
Deleted:
Skipped:
The following is an example of the messages that are issued when the audit log is
configured to capture the full level of information (in addition to all messages
issued for the basic level of audit logging):
324
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
04/21/07 15:25:05 ANS1660I Excluded:
\\spike\c$\test\file.txt
04/21/07 15:25:05 ANS1661I Unchanged:
\\spike\c$\test\file.txt
The audit log is not a substitute or a replacement for the standard error log
(dsmerror.log) or for the schedule log (dsmsched.log). If an error occurs that
prevents a file from being processed, a message indicating that an error has
occurred is written to the audit log, but the message will not indicate the nature of
the error. For problem diagnostics the standard error log must still be used.
The audit log entries only contain a time stamp and object name. There is no
information to distinguish between files and directories or any information about
the size of an object.
When using the Windows backup-archive client, all object names are written in the
UNC format. The Windows backup-archive client creates the audit log as a
Unicode file.
By default, the name of the audit log is dsmaudit.log and it is contained in the
same directory as the error log, dsmerror.log. The name and location of the audit
log can be configured using the auditlogname option. There are no parameters to
control the size of the audit log or to prune the audit log. The auditlogname option
cannot be set as an option in an IBM Spectrum Protect server client options set.
The auditlogging command is not supported with backup commands which
interact with image-level objects such as backup image or restore image. The
auditlogging command is supported with backup commands that interact with
file-level objects such as backup groups, and backup systemstate.
If you have enabled audit logging for an operation and there is a failure trying to
write to the audit log (for example, the disk on which the audit log resides is out
of space), the audit logging is disabled for the rest of the operation and the return
code for the operation is set to 12, regardless of the outcome of the operation.
Supported Clients
This option is valid for all clients.
Options File
Place this option in the dsm.opt file.
Syntax
off
►► AUDITLOGGing
►◄
basic
full
Parameters
off
Specifies that the audit logging facility is not engaged. This is the default.
basic
Specifies that the audit log captures a basic level of information.
Chapter 11. Processing options
325
full
Specifies that the audit log captures a more extensive level of information.
Examples
Run an incremental backup with audit logging enabled.
Command line:
dsmc i -auditlogging=basic
Back up a list of files using the maximum level of auditing, which enables
a separate application, such as a Perl script, to verify the results.
dsmc i -filelist=file.lst -auditlogging=full
-auditlogname="c:\program files\tivoli\tsm\baclient\
temp_audit001.log"
Auditlogname
The auditlogname option specifies the path and file name where you want to store
audit log information. This option applies when audit logging is enabled.
Supported Clients
This option is valid for all clients.
Options File
Place this option in the dsm.opt file.
Syntax
►► AUDITLOGName
filespec
►◄
Parameters
filespec
Specifies the path and file name where you want the backup-archive client to
store audit log information.
If you specify a file name only, the file is stored in your current directory. The
default is the installation directory with a file name of dsmaudit.log. The
dsmaudit.log file cannot be a symbolic link.
In Uniform Naming Convention (UNC) format, the path must contain a drive
letter. In the following example, the path contains the drive letter D$:
\\computer7\D$\logs\tsmaudit.log.
Examples
Run an incremental backup with audit logging enabled.
Options file:
Store the audit log in a non-default path.
auditlogname c:\mypath\myaudit.log
Command line:
Back up a list of files using the maximum level of auditing, which would
enable a separate application, such as a Perl script, to verify the results:
326
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
dsmc i -filelist=file.lst -auditlogging=full
-auditlogname="c:\program files\tivoli\tsm\baclient\
temp_audit001.log"
Sample output
The following is a sample execution and output file:
C:\Program Files\Tivoli\TSM\baclient>dsmc i
c:\test\* -sub=yes -auditlogging=full
IBM Spectrum Protect
Command Line Backup-Archive Client Interface
Client Version 8, Release 1, Level 0.0
Client date/time: 11/16/2016 12:05:35
(c) Copyright by IBM Corporation and other(s) 1990, 2016.
All Rights Reserved.
Node Name: PATMOS
Session established with server PATMOS_5331: Windows
Server Version 8, Release 1, Level 0.0
Server date/time: 11/16/2016 12:05:35
Last access: 11/15/2016 15:52:06
Incremental backup of volume ’c:\test\*’
Normal File-->
1,048,576 \\patmos\c$\test
\dir1\file1 [Sent]
Normal File-->
1,048,576 \\patmos\c$\test
\dir1\file2 [Sent]
Normal File-->
1,024 \\patmos\c$\test
\dir1\file3 [Sent]
Normal File-->
1,048,576 \\patmos\c$\test
\dir2\file1 [Sent]
Normal File-->
1,048,576 \\patmos\c$\test
\dir2\file2 [Sent]
Normal File-->
1,024 \\patmos\c$\test
\dir2\file3 [Sent]
Successful incremental backup of ’\\patmos\c$\test\*’
Total number of objects inspected:
12
Total number of objects backed up:
6
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:
400.85 KB
Data transfer time:
0.00 sec
Network data transfer rate:
0.00 KB/sec
Aggregate data transfer rate:
382.85 KB/sec
Objects compressed by:
91%
Elapsed processing time:
00:00:01
ANS1900I Return code is 0.
ANS1901I Highest return code was 0.
The following are the audit log contents:
04/21/2007 15:52:25 ANS1650I
i c:\test\*
04/21/2007 15:52:26 ANS1661I
\\patmos\c$\test
04/21/2007 15:52:26 ANS1661I
\\patmos\c$\test\dir1
04/21/2007 15:52:26 ANS1661I
\\patmos\c$\test\dir2
04/21/2007 15:52:26 ANS1661I
\\patmos\c$\test\file1
04/21/2007 15:52:26 ANS1661I
\\patmos\c$\test\file2
04/21/2007 15:52:26 ANS1661I
Command:
Unchanged:
Unchanged:
Unchanged:
Unchanged:
Unchanged:
Unchanged:
Chapter 11. Processing options
327
\\patmos\c$\test\file3
04/21/2007 15:52:26 ANS1651I Backed
\\patmos\c$\test\dir1\file1
04/21/2007 15:52:26 ANS1651I Backed
\\patmos\c$\test\dir1\file2
04/21/2007 15:52:26 ANS1651I Backed
\\patmos\c$\test\dir1\file3
04/21/2007 15:52:26 ANS1651I Backed
\\patmos\c$\test\dir2\file1
04/21/2007 15:52:26 ANS1651I Backed
\\patmos\c$\test\dir2\file2
04/21/2007 15:52:26 ANS1651I Backed
\\patmos\c$\test\dir2\file3
Up:
Up:
Up:
Up:
Up:
Up:
Related information
For more information about the audit logging facility refer to “Auditlogging” on
page 324.
Autodeploy
Use the autodeploy option to enable or disable an automatic deployment of the
client if a restart is required.
Supported Clients
This option is valid for Windows clients
Options File
You can set this option by including it in your client options file. You can also set
in using the Java GUI by clicking Edit > Client Preferences and selecting the
appropriate option on the General tab.
Syntax
Yes
►► AUTODEPLOY
►◄
No
NOReboot
Parameters
Yes
Specifies that the client is automatically deployed from the server. Yes is the
default.
Important:
v When you set autodeploy to yes, if a restart of the client workstation is
required to complete the deployment, you cannot disable the restart. The
client workstation will be restarted. If it is important that the workstation is
not automatically restarted, set autodeploy to noreboot. The deployment will
be canceled if a restart is required. The current client is not affected.
v If a restart is required, the deployment manager initiates a restart for the
client computer and exits. However, it is possible that you cancel or
interrupt the restart. Since the deployment manager is already terminated, a
328
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
message is not sent to the server to indicate the failure of the restart. The
deployment result is still successful. You must restart the computer so that
the new client deployment completes.
No Specifies that the client is not automatically deployed from the server.
NOReboot
Specifies that the deployment manager never automatically restarts the client
computer, even if a restart is required. If a restart is required, allowing
automatic deployment to many machines with the NOReboot parameter can
result in only a partial update of, potentially, many clients.
To alleviate this problem, the deployment manager tries to detect if a restart is
required. If a restart is required, the deployment manager cancels the
deployment before the new client installation. This guarantees that the client
computer still has a working backup-archive client, and the new client
deployment can be rescheduled.
There are rare cases where the deployment manager cannot detect the restart;
for example, if client processes are started from a script. In these cases, the new
client installation will continue, but a manual restart of the client computer is
required.
Examples
Options file:
autodeploy no
Command line:
Does not apply.
Options file:
autodeploy noreboot
Command line:
Does not apply.
Important: Use schedmode prompted with the autodeploy option, to enable the
scheduler to process the client deployment schedule immediately.
Related concepts:
“Automatic backup-archive client deployment” on page 1
Autofsrename
The autofsrename option renames an existing file space that is not Unicode-enabled
on the IBM Spectrum Protect server so that a Unicode-enabled file space with the
original name can be created for the current operation.
When you specify autofsrename yes in your client options file, and the server
value of autofsrename is set to client, the IBM Spectrum Protect server generates a
unique name by appending _OLD to the file space name you specify in the current
operation. For example, the server renames the file space \\your-node-name\h$ to
\\your-node-name\h$_OLD. If the new file space name is too long, the suffix
replaces the last characters of the file space name, as follows:
\\your-node-name_OLD
If the new file space name already exists on the server, the server renames the new
file space \\your-node-name_OLDx, where x is a unique number.
Chapter 11. Processing options
329
The server creates new Unicode-enabled file spaces that contain only the data
specified in the current operation. For example, to archive files from your H: disk
named \\your-node\h$, issue the following archive command:
arc h:\logs\*.log
Before the archive takes place, the server renames the file space to
\\your-node\h$_OLD. The archive places the data specified in the current operation
into the Unicode-enabled file space named \\your-node\h$. The new
Unicode-enabled file space now contains only the \logs directory and the *.log
files specified in the operation. All subsequent full and partial incremental,
selective backup, and archive data are stored in the new Unicode-enabled file
spaces.
Renamed file spaces remain on the server as stabilized file spaces. These file spaces
contain all the original data, which you can restore as long as they remain on the server.
Note: When an existing file space is renamed during Unicode conversion, any
access rules defined for the file space remain applicable to the original file space.
New access rules must be defined to apply to the new Unicode file space.
After installation, perform a full incremental backup and rename all existing file
spaces that are not Unicode-enabled and back up the files and directories within
them under the new Unicode-enabled file spaces. This operation requires increased
processing time and storage on the server.
File spaces that are not Unicode-enabled can be viewed in the character set of the
locale from which the files were backed up. A workstation running in a different
locale might be unable to view or restore from these file spaces. Unicode-enabled
file spaces that are backed up in one locale are visible in all other locales, provided
that the workstation has the proper fonts installed.
To restore or retrieve from a file space that is not Unicode-enabled, specify the
source on the server and the destination on the client. See
Supported Clients
This option is valid for all Windows clients. The server can define the
autofsrename option and override the autofsrename setting on the client. The IBM
Spectrum Protect API does not support this option.
Options File
Place this option in the client options file (dsm.opt) file. You can set this option on
the General tab, Rename non-Unicode filespaces during backup/archive
drop-down list box of the Preferences editor.
Syntax
Prompt
►► AUTOFsrename
►◄
Yes
No
330
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Parameters
Yes
Specifies that the IBM Spectrum Protectserver automatically renames all file
spaces that are not Unicode-enabled in the current backup or archive
operation.
No Specifies that the server does not rename file spaces that are not
Unicode-enabled in the current backup or archive operation.
Prompt
Specifies that you are prompted whether to rename the file spaces that are not
Unicode-enabled in the current operation. This is the default.
Considerations:
v This option applies only when the server sets the autofsrename option to client.
v When the client scheduler is running, the default behavior is to not prompt you.
The next interactive session prompts you to rename the file space.
v The client prompts you only one time per file space. If you specify no at the
prompt, the client cannot rename the file spaces later. However, the IBM
Spectrum Protect administrator can rename the file spaces on the server.
v When backing up files to a file space that is not Unicode-enabled, the
Unicode-enabled client skips the files and directories with names containing
characters from a code page that is different from the current locale.
v If files and directories with names containing characters from a code page other
than the current locale were previously backed up with a client that was not
Unicode-enabled, they might be expired. The Unicode-enabled client expires
these files if you do not migrate the file space to a Unicode-enabled file space.
You can back up and archive these files to a Unicode-enabled file space.
Examples
Options file:
autofsrename yes
Related concepts:
“Restore from file spaces that are not Unicode-enabled” on page 744
Backmc
The backmc option specifies the management class to apply to the backup fastback
command for retention purposes.
Use the backmc option with the backup fastback command.
If you back up an object more than once and specify a different management class
for each backup, all backup versions of the object are rebound to the last
management class specified.
Supported Clients
This option is valid for all Windows clients.
Options File
None. You can specify this option only on the command line or on the scheduler.
Chapter 11. Processing options
331
Syntax
►► BACKMc=
management_class_name
►◄
Parameters
management_class_name
Specifies the management class name.
Examples
Command line:
dsmc backup fastback -fbpolicyname=policy1 -fbserver=server1
-backmc=ret2yrs
Backupsetname
The backupsetname option specifies the name of a backup set from the IBM
Spectrum Protect server.
You can use backupsetname option with the following commands:
v query backup
v query filespace
v query image
v query systemstate
v restore image
Note: The following commands take backupsetname as a positional parameter. The
backupsetname positional parameter behaves differently from the backupsetname
option. See the command explanations for a discussion of how the backupsetname
positional parameter affects each of these commands:
query backupset
restore
restore backupset
Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support
this option.
Options File
None. You can specify this option only on the command line.
Syntax
►► BACKUPSETName
backupsetname
►◄
Parameters
backupsetname
Specifies the name of a backup set from the IBM Spectrum Protect server. You
cannot use wildcards.
332
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Examples
Command line:
dsmc query image -backupsetname=WEEKLY_BSET.21435678
dsmc query backup c:\* -subdir=yes
-backupsetname=weekly_accounting_data.32145678
dsmc restore image e:
-backupsetname=weekly_backup_data.12345678
Related information
“Restore data from a backup set” on page 196
Basesnapshotname
The basesnapshotname option specifies the snapshot to use as the base snapshot,
when you perform a snapshot differential (snapdiff) backup of a NetApp filer
volume. If you specify this option, you must also use the snapdiff option or an
error occurs. If basesnapshotname is not specified, the useexistingbase option
selects the most recent snapshot on the filer volume as the base snapshot.
If the specified snapshot cannot be found, an error is reported and the backup
operation fails.
Supported Clients
This option can be used with supported Windows clients.
Options File
This option can be specified in the client options file or on the command line.
Syntax
►► BASESNAPSHOTName
snapshot_name
►◄
Parameters
snapshot_name
Specifies the name of an existing snapshot to use as the base snapshot. The
name specified can be a snapshot name, such as vol1_snap, or it can be the
name of a scheduled NetApp backup that has a name like nightly.x, where x
is the sequence number (where nightly.0 is the oldest snapshot).
You can also use a pattern with wildcard characters to select a snapshot. The
wildcard characters can be either of the following:
*
An asterisk (*) matches any character.
?
A question mark (?) matches a single character.
The wildcards are useful if your snapshots follow a pattern, such as including
the date or data and time as part of the snapshot name. For example, a
snapshot created on November 12 2012 at 11:10:00 AM could be saved as
UserDataVol_121103111000_snapshot. The most recent snapshot that matches
the pattern is selected as the existing base. For example, if there are two saved
snapshots (UserDataVol_121103111000_snapshot and
Chapter 11. Processing options
333
UserDataVol_121103231000_snapshot, the UserDataVol_121103231100_snapshot
is selected because it is 12 hours newer than the other snapshot.
-basesnapshotname="UserDataVol_*_snapshot"
Question marks work well for scheduled backups that follow a consistent
name pattern. This syntax selects the latest “nightly” backup as the snapshot to
use as the existing base.
-basenameshotname="nightly.?"
Examples
Options file:
basesnapshotname nightly.?
basesnapshotname volum_base_snap
Command line:
dsmc incr \\DRFiler\UserDataVol_Mirror_Share -snapdiff
-useexistingbase -basesnapshotname="nightly.?"
Related information
Useexistingbase
Cadlistenonport
The cadlistenonport option specifies whether to open a listening port for the
client acceptor.
When a listening port is open, it can accept any inbound connections. However,
the port is not used when the client acceptor manages only the scheduler and the
scheduler runs in polling mode. You can use this option to prevent the acceptor
from opening the unused port.
The default setting for this option is yes. Use cadlistenonport no only when
managedservices schedule and schedmode polling are used.
Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support
this option.
Options File
Place this option in the client options file (dsm.opt).
Syntax
Yes
►► CADLISTENONPort
►◄
No
Parameters
Yes
Specifies that the client acceptor opens a listening port. This parameter is the
default.
334
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
No Specifies that the client acceptor does not open a listening port. Use this setting
when you use the client acceptor only to manage the scheduler in polling
mode.
This setting effectively disables other client features that depend on the client
acceptor, such as web client backup and restore operations, IBM Spectrum
Protect for Virtual Environments: Data Protection for VMware vSphere GUI
operations, and IBM Spectrum Protect Snapshot backup and restore operations.
Example
Options file:
cadlistenonport no
Command line:
Does not apply.
Related reference:
“Managedservices” on page 454
“Schedmode” on page 516
Casesensitiveaware
The casesensitiveaware option specifies whether the Windows backup-archive
client attempts to filter out file and directory objects that have name conflicts that
are caused by different capitalization of the object names.
NTFS and ReFS volumes are case-sensitive and allow case-sensitive file names to
be stored. Although the Windows operating system is not case-sensitive,
applications such as Windows Services for UNIX (SFU) uses POSIX conventions
and allow case-sensitive file names. SFU is typically included with Windows
operating systems such as Windows Powered OS and Windows Storage Server.
These operating systems are typically deployed on hardware (for example, NAS
hardware) which is acting as a dedicated file server in a heterogeneous
environment.
If there are UNIX clients that store files on NTFS or ReFS volumes in these
Windows file server environments, use the casesensitiveaware option. If this
option is not used in these environments, unpredictable results occur during
backup and archive operations if case-sensitive file name conflicts are encountered.
For homogeneous Windows file server environments, the casesensitiveaware
option is not necessary.
For example, if there is a set of objects that are called ’MyWork.xls', 'MYWORK.xls',
and 'mywork.xls', because the Windows operating system is not case-sensitive,
applications cannot distinguish between two objects named 'mywork.xls' and
'MyWork.xls'
For this reason, the Windows backup-archive client cannot guarantee the restore
integrity of such objects. When a name casing conflict arises, the backup-archive
client can guarantee only the restore integrity of the first file in an alphabetical
sort. On an ASCII-based operating system such as Windows, this means that
capital letters come first, alphabetically, before their lowercase counterparts, so
'MySwork.xls' would alphabetically precede 'mywork.xls'.
In this example, if the casesensitiveaware option is used, only 'MyWork.xls' is
processed. An error message is issued for ’mywork.xls’ and it is skipped. If
'mywork.xls' is a directory, then the directory subtree 'mywork.xls' would be
Chapter 11. Processing options
335
skipped. In all cases, messages are written to both the local error log and to the
IBM Spectrum Protect server console to indicate the exact file names of the objects
that are skipped.
Supported Clients
This option is valid for all Windows clients. The server can also define this option.
Options File
Place this option in the client options file (dsm.opt).
Syntax
No
►► CASESENSITIVEAware
►◄
Yes
Parameters
yes
Specifies that the client will attempt to identify object names which differ in
casing only and filter out objects which have casing conflicts and cannot be
guaranteed to be restored properly.
no Specifies that the client will not attempt to identify object names which differ
in casing only. This is the default.
Changingretries
The changingretries option specifies how many additional times you want the
client to attempt to back up or archive a file that is in use. Use this option with the
archive, incremental, and selective commands.
This option is applied only when copy serialization, an attribute in a
management class copy group, is shared static or shared dynamic.
With shared static serialization, if a file is open during an operation, the
operation repeats the number of times that you specify. If the file is open during
each attempt, the operation does not complete.
With shared dynamic serialization, if a file is open during an operation, the
operation repeats the number of times that you specify. The backup or archive
occurs during the last attempt whether the file is open or not. Open file support
can be used to back up files that are locked or in use.
Supported Clients
This option is valid for all Windows clients. The server can also define this option.
The IBM Spectrum Protect API does not support this option.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
Backup tab, Number of retries if file is in use field of the Preferences editor.
336
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Syntax
►► CHAngingretries
numberretries
►◄
Parameters
numberretries
Specifies the number of times a backup or archive operation is attempted if the
file is in use. The range of values is zero through 4; the default is 4.
Examples
Options file:
changingretries 3
Command line:
-cha=3
Class
The class option specifies whether to display a list of NAS or client objects when
using the delete filespace, query backup, and query filespace commands.
For example, to display a list of the file spaces belonging to a NAS node, enter the
following command:
query filespace -class=nas
Supported Clients
This option is valid for all Windows clients. The IBM Spectrum Protect API does
not support this option.
Options File
None. You can specify this option only on the command line.
Syntax
client
►► CLASS =
►◄
nas
Parameters
client
Specifies that you want to display a list of file spaces for a client node. This is
the default.
nas
Specifies that you want to display a list of file spaces for a NAS node.
Examples
None. You can specify this option only on the command line.
Command line:
q backup -nasnodename=nodename -class=nas
Chapter 11. Processing options
337
Clientview
The clientview option is available to users who have upgraded from the IBM
Tivoli Storage Manager Express backup client to the enterprise backup-archive
client.
You must be connected to the Tivoli Storage Manager Version 5.4 or higher server
to use this option. The clientview option allows you to choose either the express
view or the standard view of the client graphical user interface (GUI).
Supported Clients
This option is valid for all Windows clients.
Options File
Place this option in the dsm.opt file. To switch to the Express view:
1. In the backup-archive client GUI, select Edit > Preference from the menu bar.
2. From the General tab of the Preferences editor, in the Client View field, click
Express.
3. Click OK to save your change.
To switch to the Standard view:
1. In the backup-archive client GUI, click Modify Settings.
2. From the General tab of the Preferences Editor, in the Client View field, click
Standard.
3. Click OK to save your change.
Syntax
standard
►► CLIENTVIEW =
►◄
express
Parameters
standard
Specifies that the standard, or enterprise, view of the backup-archive client
GUI should be used. The standard view contains the advanced features of the
backup-archive client GUI. This is the default.
express
Specifies that the express view of the backup-archive client GUI should be
used. The express view contains the same features as the Express backup client
GUI.
Clusterdisksonly
The clusterdisksonly option specifies whether the backup-archive client allows
the backup of only clustered disks in specific environments.
The backup-archive client allows for the backup of only clustered disks when the
client is running in the following environments:
v In a Microsoft Cluster Server (MSCS)
v When failover clustering is employed on a supported Windows Server client
338
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
v In a VERITAS Cluster Server (VCS) environment, when you set clusternode yes
The backup-archive client previously allowed only backups and restores of data on
clustered drives that were mounted as a drive letter.
It is common to find clustered drives that are mounted as volume mount points.
Windows Server operating systems allow users to surpass the 26-drive-letter
limitation by allowing volume mount points to be defined on a clustered server.
The client can protect data on cluster disks that are mounted as drive letters on
Windows Server OS computers. The client can also protect data on cluster disks
that are mounted as volume mount points. The backup-archive client can
automatically determine whether a volume that is using a volume mount point is a
cluster volume.
When you set clusterdisksonly yes, the backup-archive client continues to
segregate local drives from cluster drives when it evaluates the ALL-LOCAL domain
option. When clusterdisksonly no is specified, you must explicitly define the
backup domains. When clusterdisksonly no is specified, the backup-archive client
also bypasses enumeration of cluster resources to determine which resources
represent cluster drives.
Supported Clients
This option is valid for all supported Windows Server clients.
Options File
Place this option in the client options file (dsm.opt).
Syntax
Yes
►► CLUSTERDISKSOnly
►◄
No
Parameters
Yes
Specifies that the client allows only the processing of cluster drives. Yes is the
default.
No Specifies that the client allows the processing of any disk when clusternode
yes is set.
Examples
Scenario 1: Back up a node that manages the local (non-clustered) drives and the
system state information
This is the node that is dedicated to the restoration of the physical system
if a hardware failure occurs. There are no clustered drives that are
mounted as volume mount points.
Options file:
CLUSTERNODE NO (default)
CLUSTERDISKSONLY YES (default)
DOMAIN ALL-LOCAL (default)
EXCLUDE c:\...\file.txt
Chapter 11. Processing options
339
Scenario 1b: Back up a node that manages the local (non-clustered) drives and
the system state information and bypass enumeration of cluster resources
This is a scenario similar to scenario 1, which can be deployed if the
backup-archive client takes an inappropriate amount of time during startup
processing. During initialization of the backup-archive client, all of the
cluster resources are enumerated to determine which resources represent
cluster disk devices. This processing can be skipped by setting
clusterdisksonly no.
Options file:
CLUSTERNODE NO (default)
CLUSTERDISKSONLY NO
DOMAIN C: D: (local drives must be explicitly enumerated)
EXCLUDE c:\...\file.txt
Scenario 2: Back up a node that manages the clustered drives within a cluster
resource group and bypass enumeration of cluster resources
This is a scenario that can be deployed if the backup-archive client takes an
inappropriate amount of time during startup processing. During
initialization of the backup-archive client, all of the cluster resources are
enumerated to determine which resources represent cluster disk devices.
This processing can be skipped by setting clusterdisksonly no.
Options file:
CLUSTERNODE YES
CLUSTERDISKSONLY NO
DOMAIN f: g:
EXCLUDE f:\...\file.txt
Scenario 3: Back up a node that manages the clustered drives within a cluster
resource group, by using volume mount points as cluster resources
In this scenario, it is assumed that the node is responsible for backing up a
cluster resource group that has two drives, f: and f:\mnt. There are
clustered drives that are mounted as volume mount points (Windows
Server operating systems). Ensure that you define the incremental
processing domain as only the volumes within a cluster resource group. If
you have multiple cluster resource groups, assign a unique client node to
manage each cluster resource group.
Options file
CLUSTERNODE YES
CLUSTERDISKSONLY YES
DOMAIN f: f:\mnt
EXCLUDE f:\mnt\...\file.txt
Table 53 lists the clusternode and clusterdisksonly combinations.
Table 53. Clusternode and clusterdisksonly combinations
340
Clusternode
Clusterdisksonly
When to use
no
yes
This is the default behavior if
nothing is specified; since the
clusterdisksonly option is
set to clusterdisksonly yes,
the cluster disk map is built.
This combination is used for
backing up local drives.
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Table 53. Clusternode and clusterdisksonly combinations (continued)
Clusternode
Clusterdisksonly
When to use
yes
yes
This is the default way to
run in a cluster node to back
up cluster disks, including
disks that are exposed as
mount points; the cluster
disk map is built.
yes
no
For clients that run on
Windows Server operating
systems, you must specify
clusterdisksonly no only if
you want to bypass cluster
volume enumeration for
performance reasons.
Clusternode
The clusternode option specifies how the backup-archive client manages cluster
drives.
The backup-archive client manages clustered drives in the following environments:
v A Microsoft Cluster Server (MSCS)
v Failover Clustering on Windows Server systems
v VERITAS Cluster Server (VCS)
When the clusternode yes is set, only shared cluster drives are available for
backup and archive processing. When you set clusternode yes, the node name
defaults to the cluster name.
To back up local drives or Windows Server system state, you must set clusternode
no.
Note: You must set the clusternode yes for all IBM Spectrum Protect-managed
cluster operations. Inconsistent use of the clusternode option for a given IBM
Spectrum Protect cluster node name can cause the cluster node name encrypted
password to be invalidated, and prompt the user to reenter the password during
the next IBM Spectrum Protect program invocation.
Use the optfile option to properly call the correct (cluster) dsm.opt for all IBM
Spectrum Protect programs to ensure proper functionality for cluster related
operations. See the optfile option description for more information.
Supported Clients
This option is valid for Windows Server operating system clients.
Options File
Place this option in the client options file (dsm.opt).
Chapter 11. Processing options
341
Syntax
No
►► CLUSTERnode
►◄
Yes
Parameters
Yes
Specifies that you want the client to manage cluster drives in the following
environments:
v A MSCS
v Failover Clustering on Windows Server systems
v VCS
No Specifies that you want to back up local disks. This is the default.
Examples
Options file:
cluster no
Command line:
-cluster=yes
This option is valid only on the initial command line. It is not valid in interactive
mode.
Related information
“Optfile” on page 474
Collocatebyfilespec
Use the collocatebyfilespec option to specify whether the backup-archive client
uses only one server session to send objects generated from one file specification.
Setting the collocatebyfilespec option to yes attempts to eliminate interspersing
of files from different file specifications, by limiting the client to one server session
per file specification. Therefore, if you store the data to tape, files for each file
specification are stored together on one tape (unless another tape is required for
more capacity).
Considerations:
v Use the collocatebyfilespec option only if the storage pool is going directly to
tape. If you use this option going to a disk storage pool, you could affect some
load balancing, and therefore, performance.
Supported Clients
This option is valid for all Windows clients. The server can also define this option.
Options File
Place this option in the client options file (dsm.opt).
342
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Syntax
No
►► COLlocatebyfilespec
►◄
Yes
Parameters
Yes
Specifies that you want the client to use only one server session to send objects
generated from one file specification. Therefore, if you store the data to tape,
files for each file specification are stored together on one tape, unless another
tape is required for more capacity. Restore performance can increase as a result.
No Specifies that the client can (depending on the execution dynamics and on the
setting of the resourceutilization option of 3 or higher) use more than one
server session to send the files from one file specification. This is the default.
Backup performance might increase as a result. If the files are backed up to
tape, files are stored on multiple tapes. Generally, the files specified in the file
specification are still contiguous.
Examples
Options file:
collocatebyfilespec yes
Command line:
-collocatebyfilespec=yes
This option is valid only on the initial command line. It is not valid in interactive
mode.
Commmethod
The commmethod option specifies the communication method you use to provide
connectivity for client-server communication.
Supported Clients
This option is valid for all clients.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
Communication tab of the Preferences editor.
Syntax
TCPip
►► COMMMethod
►◄
SHAREdmem
V6TCPIP
NAMedpipes
Chapter 11. Processing options
343
Parameters
TCPip
The Transmission Control Protocol/Internet Protocol (TCP/IP) communication
method. This is the default.
V6Tcpip
Indicates that either TCP/IP V4 or V6 should be used, depending on the
system configuration and the results of a domain name service lookup. A valid
DNS environment must be available.
NAMedpipes
The interprocess communication method that permits message data streams to
pass between a client and a server. Use this communication method with an
IBM Spectrum Protect server that is running on the same workstation as the
client.
SHAREdmem
Use the shared memory communication method when the client and server are
running on the same system. This provides better performance than the
TCP/IP protocol.
Note: Use of this communication method requires that both client and server
run under the same Windows account.
Examples
Options file:
Use only TCP/IP V4.
commmethod tcpip
Use both TCP/IP V4 and V6, depending on how the system is configured,
and the results of a domain name service lookup.
commmethod V6Tcpip
Note: The dsmc schedule command cannot be used when both SCHEDMODe
prompt and commmethod V6Tcpip are specified.
Command line:
-commm=tcpip
-commm=V6Tcpip
This option is valid only on the initial command line. It is not valid in interactive
mode.
Commrestartduration
The commrestartduration option specifies the maximum number of minutes you
want the client to try to reconnect to the IBM Spectrum Protect server after a
communication error occurs.
Note: A scheduled event continues if the client reconnects with the server before
the commrestartduration value elapses, even if the startup window of the event
has elapsed.
You can use the commrestartduration option and the commrestartinterval in busy
or unstable network environments to decrease connection failures.
344
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Supported Clients
This option is valid for all clients.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
Communication tab, Common Options section of the Preferences editor.
Syntax
►► COMMRESTARTDuration
minutes
►◄
Parameters
minutes
The maximum number of minutes you want the client to attempt to reconnect
with a server after a communication failure occurs. The range of values is zero
through 9999; the default is 60.
Examples
Options file:
commrestartduration 90
Command line:
Does not apply.
Commrestartinterval
The commrestartinterval option specifies the number of seconds you want the
client to wait between attempts to reconnect to the IBM Spectrum Protect server
after a communication error occurs.
Note: Use this option only when commrestartduration is a value greater than zero.
You can use the commrestartduration option and the commrestartinterval in busy
or unstable network environments to decrease connection failures.
Supported Clients
This option is valid for all clients.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
Communication tab, Common Options section of the Preferences editor.
Syntax
►► COMMRESTARTInterval
seconds
►◄
Parameters
seconds
The number of seconds you want the client to wait between attempts to
Chapter 11. Processing options
345
reconnect with a server after a communication failure occurs. The range of
values is zero through 65535; the default is 15.
Examples
Options file:
commrestartinterval 30
Command line:
Does not apply.
Compressalways
The compressalways option specifies whether to continue compressing an object if
it grows during compression.
Use this option with the compression option, and with the archive, incremental,
and selective commands.
The compressalways option is ignored when client-side deduplication is enabled.
Supported Clients
This option is valid for all clients. The server can also define this option.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
Backup tab, Continue Compressing if Object Grows check box of the Preferences
editor.
Syntax
Yes
►► COMPRESSAlways
►◄
No
Parameters
Yes
File compression continues even if the file grows as a result of compression.
This is the default.
No Backup-archive client objects are resent uncompressed if they grow during
compression. API behavior depends on the application. Application backups
might fail.
Examples
Options file:
compressalways yes
Command line:
-compressa=no
This option is valid only on the initial command line. It is not valid in interactive
mode.
346
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Compression
The compression option compresses files before you send them to the server.
Compressing your files reduces data storage for backup versions and archive
copies of your files. It can, however, affect IBM Spectrum Protect throughput. A
fast processor on a slow network connection benefits from compression, but a slow
processor on a fast network connection does not.
Use the compression option with the archive, incremental, and selective
commands.
The backup image command uses the compression option value specified in the
dsm.opt file. This option is valid on the initial command line and in interactive
mode. The server can also define this option which overrides the client value.
The backup-archive client backs up a sparse file as a regular file if client
compression is off. Set compression yes to enable file compression when backing
up sparse files to minimize network transaction time and maximize server storage
space.
If you set compressalways yes, compression continues even if the file size
increases. To stop compression if the file size grows, and resend the file
uncompressed, set compressalways no.
If you set compression yes, you can control compression processing in the
following ways:
v Use the exclude.compression option in your client options file (dsm.opt) to
exclude specific files or groups of files from compression processing.
v Use the include.compression option in your client options file (dsm.opt) to
include files within a broad group of excluded files for compression processing.
This option controls compression only if your administrator specifies that your
client node can compress files before sending them to the server.
The type of compression that the client uses is determined by the combination of
compression and client-side data deduplication that is used during backup or
archive processing. The following types of compression are used:
LZ4
A faster and more efficient compression method that the client uses when
client-deduplicated data is sent to an LZ4-compatible container storage
pool on the IBM Spectrum Protect server. The server must be at version
7.1.5 or later, and must use container storage pools. Client-side LZ4
compression is used only when client-side data deduplication is enabled.
LZW
A traditional type of compression that the client uses in any of the
following situations:
v Client-deduplicated data is sent to traditional (non-container) storage
pools on the server.
v The client data does not undergo client-side data deduplication. (Does
not apply to Data Protection for VMware and Data Protection for
Microsoft Hyper-V, in which only client-deduplicated data can be
compressed.)
Chapter 11. Processing options
347
v The client data undergoes only traditional server-side data
deduplication. (Does not apply to Data Protection for VMware and Data
Protection for Microsoft Hyper-V, in which only client-deduplicated data
can be compressed.)
None
The object is not compressed by the client. The object is not compressed
because the compression option is set to no, or the option is not specified
during backup or archive processing. Although the object is not
compressed by the client, it might be compressed by the server.
You do not need to set the compression type. It is determined by the
backup-archive client at the time of backup or archive processing.
Supported Clients
This option is valid for all clients. The server can also define this option.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
Backup tab, Compress objects check box of the Preferences editor.
Syntax
No
►► COMPRESSIon
►◄
Yes
Parameters
No Files are not compressed before they are sent to the server. This is the default.
Yes
Files are compressed before they are sent to the server.
Examples
Options file:
compression yes
Command line:
-compressi=no
This option is valid only on the initial command line. It is not valid in interactive
mode.
Related reference:
“Deduplication” on page 356
“Exclude options” on page 395
“Include options” on page 426
Console
Use the console option with the query systeminfo command to output
information to the console.
v DSMOPTFILE - The contents of the dsm.opt file.
v ENV - Environment variables.
348
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
v ERRORLOG - The IBM Spectrum Protect error log file.
v FILE - Attributes for the file name that you specify.
v FILESNOTTOBACKUP - Enumeration of Windows Registry key:
HKEY_LOCAL_MACHINE\
SYSTEM\
CurrentControlSet\
BackupRestore\
FilesNotToBackup
This key specifies those files that backup products should not back up. The
query inclexcl command indicates that these files are excluded per the operating
system.
v INCLEXCL - Compiles a list of include-exclude in the order in which they are
processed during backup and archive operations.
v KEYSNOTTORESTORE - Enumeration of Windows Registry key:
HKEY_LOCAL_MACHINE\
SYSTEM\
ControlSet001\
BackupRestore\
KeysNotToRestore
This key specifies those Windows Registry keys that backup products should not
restore.
v MSINFO - Windows system information (output from MSINFO32.EXE).
v OPTIONS - Compiled options.
v OSINFO - Name and version of the client operating system
v POLICY - Policy set dump.
v REGISTRY - Windows IBM Spectrum Protect-related Windows Registry entries.
v SCHEDLOG - The contents of the IBM Spectrum Protect schedule log (usually
dsmsched.log).
v SFP - The list of files protected by Windows System File Protection, and for each
file, indicates whether that file exists. These files are backed up as part of the
SYSFILES system object.
v SFP=filename - Indicates whether the specified file (filename) is protected by
Windows System File Protection. For example:
SFP=C:\WINNT\SYSTEM32\MSVCRT.DLL
v SYSTEMSTATE - Windows system state information.
v CLUSTER - Windows cluster information.
Note: The query systeminfo command is intended primarily as an aid for IBM
support to assist in diagnosing problems, although users who are familiar with the
concepts addressed by this information might also find it useful. If you use the
console option, no special formatting of the output is performed to accommodate
screen height or width. Therefore, the console output might be difficult to read due
to length and line-wrapping. In this case, use the filename option with the query
systeminfo command to allow the output to be written to a file that can
subsequently be submitted to IBM support.
Supported Clients
This option is valid for all clients.
Chapter 11. Processing options
349
Syntax
►► CONsole
►◄
Parameters
There are no parameters for this option.
Examples
Command line:
query systeminfo dsmoptfile errorlog -console
Related information
“Filename” on page 413
Createnewbase
The createnewbase option creates a base snapshot and uses it as a source to run a
full incremental backup.
Some files might not be backed up when the snapshot difference incremental
backup command is run. If the files are skipped, you can run a snapshot difference
incremental backup with the createnewbase option to back up these files. See
“Snapdiff” on page 528 for a list of reasons why a file might not be backed up
when the snapshot difference command is run.
One reason that a file can be skipped during backup processing is because the file
name is not supported by NetApp Data ONTAP. NetApp Data ONTAP Versions
8.0 and versions lower than 7.3.3 only support file names that are within the 7 bit
ASCII character set. NetApp Data ONTAP Version 7.3.3 and versions greater than
8.0.0 support Unicode file names. If you upgraded NetApp Data ONTAP from a
version that does not support Unicode file names to a version that does support
Unicode files names, run a full incremental backup with the
createnewbase=migrate option.
Supported Clients
This option is valid for the following clients:
v All Windows clients
Enter the createnewbase option on the command line. Specify this option with the
snapdiff option.
Syntax
No
►► Createnewbase
►◄
Yes
IGNore
MIGRate
Parameters
No Specifies that a snapshot difference incremental is run. If the backup-archive
350
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
client detects that the NetApp Data ONTAP file server has been migrated from
a version that does not support Unicode file names to a file server that does, a
warning message is recorded to the error log and the IBM Spectrum Protect
server activity log. The warning message indicates that you must run a full
incremental backup and logs a return code of 8 even if the operation
completed successfully.
This parameter is the default value.
Yes
Specifies that a full incremental is run by creating a new base snapshot and is
using it to run a scan-based incremental backup. Use this option to back up
any file changes that might not have been detected by the snapshot difference
API.
If the operation finished successfully, the command ends with a return code of
0.
Do not set createnewbase=yes for any schedule that runs a daily snapshot
difference backup. Instead, create a separate, monthly schedule that has the
createnewbase=yes option.
IGNore
Specifies that a snapshot difference incremental backup is run when the
backup-archive client detects that the NetApp Data ONTAP file server was
upgraded to support Unicode file names.
The ignore option is different from the no parameter because the ignore option
suppresses the warning message. Instead, an informational message is recorded
in the error log and the IBM Spectrum Protect activity log that informs you to
run a full incremental backup.
If the command finishes successfully, it returns a code of 0.
Use the ignore option if you have upgraded the NetApp Data ONTAP file
server to support Unicode but you have not yet run a full incremental backup.
This option is used only when the backup-archive client has detected that the
file server was migrated and a full incremental has not yet been run. The
option is ignored for all other times.
MIGRate
Specifies that if the NetApp Data ONTAP file server was upgraded to a
version that supports Unicode file names, a base snapshot is taken and a
scan-based incremental backup is run. The migrate option is different from the
yes option because the migrate option creates a base snapshot only when the
client detects that the NetApp Data ONTAP file server version was updated.
The yes option creates a base snapshot every time the command is run.
After the incremental backup finishes, no additional migration-related
messages are recorded to the error log or the IBM Spectrum Protect server
activity log. When the operation finishes, the command ends with a return
code of 0.
Use the migrate option if you have upgraded the NetApp Data ONTAP file
server to support Unicode but you have not yet run a full incremental backup.
The migrate option is ignored if the NetApp Data ONTAP file server has not
been upgraded.
Examples
Command line:
dsmc incremental -snapdiff -createnewbase=yes /net/home1
Chapter 11. Processing options
351
Related tasks:
“Configuring NetApp and IBM Spectrum Protect for snapshot difference
incremental backups” on page 79
Related reference:
“Snapdiff” on page 528
Datacenter
Specifies the target location of the data center that will contain the restored
machine data.
Use this option on restore vm commands.
If folders are used within virtual center to organize datacenters, then the folder
name needs to be included in the datacenter specification, separated by a slash.
If you are restoring through a ESX server rather than a virtual center, the
-datacenter=ha-datacenter option should be used.
The default target location is the datacenter which the virtual machine was stored
at the time of backup.
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments: Data Protection for VMware.
Examples
Restore a virtual machine to USEast datacenter which is organizaed under a folder
named Production in the virtual center.
dsmc restore vm my_vm -datacenter=Production/USEast
Restore a virtual machine backup taken from a virtual center, but using a ESX
server at the time of restore.
restore vm my_vm -datacenter=ha-datacenter
Restore the virtual machine into the USWest datacenter.
restore vm my_vm -datacenter=USWEst
Datastore
Specifies the datastore target to be used during VMware restore operation.
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments: Data Protection for VMware.
Example
Restore the virtual machine to a datastore named ds8k_prod1:
restore vm my_vm -datastore=ds8k_prod1
Dateformat
The dateformat option specifies the format you want to use to display or enter
dates.
352
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Use this option if you want to change the default date format for the language of
the message repository you are using.
By default, the backup-archive and administrative clients obtain format
information from the locale definition in effect at the time you start the client.
Consult the documentation on your local system for details about setting up your
locale definition.
Note:
1. The dateformat option does not affect the web client. The web client uses the
date format for the locale that the browser is running in. If the browser is not
running in a locale that is supported, the web client uses the date format for
US English.
2. When you change the date format and use the schedlogretention option to
prune the schedule log, the client removes all entries in the schedule log with a
different date format when pruning the log. When you change the date format
and use the errorlogretention option to prune the error log, the client
removes all entries in the error log with a different date when pruning the log.
When changing the date format, copy the schedule log and error log if you
want to preserve log entries that contain a different date format.
You can use the dateformat option with the following commands.
v delete archive
v delete backup
v expire
v query archive
v query asr
v query backup
v query filespace
v query image
v query systemstate
v restore
v restore image
v restore nas
v retrieve
v restore registry
v set event
When you include the dateformat option with a command, it must precede the
fromdate, pitdate, and todate options.
Supported Clients
This option is valid for all clients.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
Regional Settings tab, Date Format drop-down list of the Preferences editor.
Syntax
►► DATEformat
format_number
►◄
Chapter 11. Processing options
353
Parameters
format_number
Displays the date using one of the following formats. Select the number that
corresponds to the date format you want to use:
1 MM/DD/YYYY
2
This is the default for the following available translations:
v US English
v Chinese (Traditional)
v Korean
DD-MM-YYYY
3
This is the default for the following available translations:
v Brazilian Portuguese
v Italian
YYYY-MM-DD
4
This is the default for the following available translations:
v Japanese
v Chinese (Simplified)
v Polish
DD.MM.YYYY
5
This is the default for the following available translations:
v German
v French
v Spanish
v Czech
v Russian
YYYY.MM.DD
6
7
This is the default for the following available translations:
v Hungarian
YYYY/MM/DD
DD/MM/YYYY
Examples
Options file:
dateformat 3
Command line:
-date=3
This option is valid on the initial command line and in interactive mode. If you
use this option in interactive mode, it affects only the command with which it is
specified. When that command completes, the value reverts to the value at the
beginning of the interactive session. This is the value from the dsm.opt file unless
overridden by the initial command line or by an option forced by the server.
Additional considerations for specifying time and date formats
The date or time format you specify with this option must be used when using
options that take date and time as input. Examples are: totime, fromtime, todate,
fromdate, and pittime.
For example, if you specify the timeformat option as TIMEFORMAT 4, the value that
you provide on the fromtime or totime option must be specified as a time such as
12:24:00pm. Specifying 13:24:00 would not be valid because TIMEFORMAT 4 requires
354
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
an hour integer that is 12 or less. If you want to specify up to 24 hour values on an
option, and if you want to use commas as separators, you must specify TIMEFORMAT
2.
Dedupcachepath
Use the dedupcachepath option to specify the location where the client-side data
deduplication cache database is created.
This option is ignored if the enablededupcache=no option is set during backup or
archive processing.
Supported Clients
This option is valid for all clients. This option is also valid for the IBM Spectrum
Protect API.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
Deduplication > Deduplication Cache Location text box of the Preferences editor.
The option can be set in the client option set on the IBM Spectrum Protect server.
Syntax
►► DEDUPCACHEPath
path
►◄
Parameters
path
Specifies the location where the client-side data deduplication cache database is
created if the enablededupcache option is set to yes. The default location is to
create the data deduplication cache file in the backup-archive client or API
installation directory.
In Uniform Naming Convention (UNC) format, the path must contain a drive
letter. In the following UNC format example, the path contains the drive letter
D$: \\computer7\D$\stgmgr\dedupecache.
Examples
Options file:
dedupcachepath c:\logs\dedup\
Command line:
Does not apply.
Related reference:
“Enablededupcache” on page 384
Dedupcachesize
Use the dedupcachesize option to determine the maximum size of the data
deduplication cache file. When the cache file reaches its maximum size, the
contents of the cache are deleted and new entries are added.
Chapter 11. Processing options
355
Supported Clients
This option is valid for all clients. This option is also valid for the IBM Spectrum
Protect API.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
Deduplication > Deduplication Cache > Maximum Size field of the Preferences
editor. The option can be set in the client option set on IBM Spectrum Protect
server.
Syntax
►► DEDUPCACHESize
dedupcachesize
►◄
Parameters
dedupcachesize
Specifies the maximum size, in megabytes, of the data deduplication cache file.
The range of values is 1 - 2048; the default is 256.
Examples
Options file:
dedupcachesize 1024
Command line:
Does not apply.
Related reference:
“Deduplication”
Deduplication
Use the deduplication option to specify whether to enable redundant client-side
data elimination when data is transferred to the IBM Spectrum Protect server
during backup and archive processing.
Data deduplication is disabled if the enablelanfree option is set. Backup-archive
client encrypted files are excluded from client-side data deduplication. Files from
encrypted file systems are also excluded.
To support client-side data deduplication, the following criteria must be met:
v Client-side data deduplication for the node is enabled on the server.
v The storage pool destination for the data must be a storage pool that is enabled
for data deduplication. The storage pool must have a device type of "file".
v A file can be excluded from client-side data deduplication processing (by default
all files are included).
v The server can limit the maximum transaction size for data deduplication by
setting the CLIENTDEDUPTXNLIMIT option on the server. For more information
about the option, refer to the IBM Spectrum Protect server documentation.
v The file size must be larger than 2 KB.
356
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Supported Clients
This option is valid for all clients; it can also be used by the IBM Spectrum Protect
API.
Options File
Place this option in the client options file (dsm.opt). You can set this option by
selecting the Deduplication > Enable Deduplication check box of the Preferences
editor. The option can be set in the client option set on IBM Spectrum Protect
server.
Syntax
No
►► DEDUPLication
►◄
Yes
Parameters
No Specifies that you do not want to enable client-side data deduplication for
backup and archive processing. No is the default.
Yes
Specifies that you want to enable client-side data deduplication for backup and
archive processing.
Examples
Options file:
deduplication yes
Command line:
-deduplication=yes
This option is valid only on the initial command line. It is not valid in interactive
mode.
Related reference:
“Include options” on page 426
“Exclude options” on page 395
Deletefiles
Use the deletefiles option with the archive command to delete files from your
workstation after you archive them.
You can also use this option with the restore image command and the incremental
option to delete files from the restored image if they were deleted after the image
was created. Deletion of files is performed correctly if the backup copy group of
the IBM Spectrum Protect server has enough versions for existing and deleted files.
Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support
this option.
Chapter 11. Processing options
357
Syntax
►► DELetefiles
►◄
Parameters
There are no parameters for this option.
Examples
Command line:
dsmc archive c:\foo\*.c –deletefiles
dsmc rest image c: -incre -deletefiles
Description
The description option assigns or specifies a description for files when performing
archive, delete archive, retrieve, query archive, or query backupset.
For example, if you want to archive a file named budget.jan and assign to it the
description “2002 Budget for Proj 1”, you would enter:
dsmc archive –des="2003 Budget for Proj 1" c:\plan\proj1\
budget.jan
Note:
1. The maximum length of a description is 254 characters.
2. Enclose the value in quotation marks (" ") if the option value that you enter
contains a blank space.
Use the description option with the following commands:
v archive
v delete archive
v query archive
v query backupset
v retrieve
Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support
this option.
Syntax
►► DEScription =
description
►◄
Parameters
description
Assigns a description to the file you are archiving. If you do not specify a
description with the archive command, the default is Archive Date:x, where x
is the current system date. Note that the date is always 10 characters long. If
your date format uses a two digit year, there are two blank spaces at the end
of the date. For example, a default description using a four-digit year might be
"Archive Date: 2002/05/03", and the same default with a two-digit year might
be "Archive Date: 02/05/03 " (note the two spaces at the end). When
358
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
retrieving files using the two-digit year description, you can enter the
-description option string in either of the following ways:
-description="ArchiveDate: 02/05/03 "
or
-description="ArchiveDate: 02/05/03*"
If you use the archive command to archive more than one file, the description
you enter applies to each file. For example, to archive a group of files and
assign the same description, Project X, to each file, you would enter:
dsmc archive –description="Project X" c:\allproj\*.x
You can then use the description to retrieve all of the files.
Examples
Command line:
dsmc archive –des="2003 Budget for Proj 1" c:\foo\ *.prj
Detail
Use the detail option to display management class, file space, backup, archive
information, and additional information, depending on the command with which it
is used.
Use the detail option with the query mgmtclass command to display detailed
information about each management class in your active policy set. If you do not
use the detail option, only the management class name and a brief description are
displayed on the screen. If you specify the detail option, information about
attributes in each copy group contained in each management class is displayed on
the screen. A management class can contain a backup copy group, an archive copy
group, both, or neither.
A Unicode-enabled file space might not display correctly if the server cannot
display the Unicode name. In this case, use the file space identifier (fsID) of the file
space to identify these file spaces on the server. Use the detail option with the
delete filespace and query filespace commands to determine the fsID of a file
space. The fsID also appears in the file information dialog in the backup-archive
client and web client GUIs.
Use the detail option with the query backup and query archive commands to
display these attributes of the file that you specify:
v Last modification date
v Last access date
v Compression
v Encryption type
v Client-side data deduplication
v Whether the HSM client migrated or premigrated the file
Use the detail option with the query adobjects command to display detailed
information about Active Directory objects, including all of their attributes.
Use the detail option with the query adobjects command to display detailed
information about Active Directory objects, including all of their attributes.
Use the detail with the query vm command to display the following statistics:
Chapter 11. Processing options
359
v The average number of IBM Spectrum Protect objects that are needed to describe
a single megablock, across all megablocks in a backup.
v The average number of IBM Spectrum Protect objects that are needed to describe
a single megablock, for all megablocks in a filespace.
v The ratio of the amount of data, reported by Change Block Tracking, versus the
amount of data that was actually backed up, in a specific backup.
v The ratio of the amount of data, reported by Change Block Tracking, versus the
amount of data that was actually backed up, for all backups in this filespace.
v The number of backups that were created since the last full backup was created
from the production disks.
The values returned on query vm can help you fine tune the heuristics (see the
Mbobjrefreshthresh and Mbpctrefreshthresh options) to fine tune the values
trigger for megablock refreshes.
Use the detail option with the following commands:
v delete filespace
v incremental
v query adobjects
v query archive
v query backup
v query filespace
v query inclexcl
v query mgmtclass
v query systemstate
v query vm
Supported Clients
This option is valid for all clients. This option is not set in the client options file;
use it by adding it to the command line when you enter any of the commands that
support it. The IBM Spectrum Protect API does not support this option.
Syntax
►► DETail
Parameters
There are no parameters for this option.
Examples
Command line:
dsmc query mgmtclass -detail
dsmc query filespace -detail
dsmc query backup file1 -detail
dsmc query systemstate -detail
dsmc query vm -detail
Diffsnapshot
The diffsnapshot option controls whether the backup-archive client creates the
differential snapshot when it runs a snapshot difference incremental backup.
360
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
►◄
If the differential snapshot is not created by the client, the latest snapshot found on
the volume is used as the differential snapshot and as the source for the backup
operation.
The default value is to create the differential snapshot. This option is ignored the
first time that the snapdiff option is used. The first time the snapdiff option is
used on a volume, a snapshot must be created and used as the source for a full
incremental backup. Snapshots that are created by the backup-archive client are
deleted by the client after the next snapshot difference incremental backup is
complete.
Snapshots can be created with the Network Appliance FilerView tool. Use the
latest parameter if you want the client to use the most recent snapshot that was
created. Whatever method is used to create named snapshots, snapshot names that
differ only by case will not work properly with the snapdiff option. Snapshots
that are created by the client will not have the casing problem. Snapshots that are
created by methods outside of IBM Spectrum Protect are never deleted by the
client.
Supported Clients
This option is valid for all Windows clients.
Syntax
create
►► DIFFSNAPSHOT
►◄
latest
Parameters
create
Specifies that you want to create a new, persistent, snapshot to use as the
source snapshot. This value is the default.
latest
Specifies that you want to use the latest snapshot that is found on the file
server as the source snapshot.
Examples
Command line:
Perform a snapdiff incremental backup from a snapshot that was taken of
a network share //homestore.example.com/vol/vol1 mounted on drive H:,
where homestore.example.com is a file server.
incremental -snapdiff H:
Perform a snapdiff incremental backup from a snapshot that was taken of
a network share //homestore.example.com/vol/vol1 mounted on drive H:,
where homestore.example.com is a file server. The -diffsnapshot option
value of LATEST means the operation uses the latest snapshot (the active
snapshot) for volume H:.
incremental -snapdiff H: -diffsnapshot=latest
Related concepts:
“Snapshot differential backup with an HTTPS connection” on page 145
Chapter 11. Processing options
361
Related tasks:
“Configuring NetApp and IBM Spectrum Protect for snapshot difference
incremental backups” on page 79
Related reference:
“Snapdiff” on page 528
“Snapdiffhttps” on page 534
“Createnewbase” on page 350
Diffsnapshotname
The diffsnapshotname option allows you to specify which differential snapshot, on
the target filer volume, to use during a snapshot differential backup. This option is
only specified if you also specify diffsnapshot=latest.
If this option is not specified, diffsnapshot=latest selects the most recent existing
snapshot on the filer volume and uses it as the differential snapshot.
Supported Clients
This option can be used with supported Windows clients.
Options File
This option can be specified in the client options file or on the command line.
Syntax
►► DIFFSNAPSHOTName
snapshot_name
Parameters
snapshot_name
Specifies the name of an existing snapshot to use as the differential snapshot.
You can also use a pattern with wildcard characters to select a snapshot.
Wildcards can be either of the following characters:
*
An asterisk (*) matches any character.
?
A question mark (?) matches a single character.
The most recent snapshot that matches the wildcard pattern is selected as the
differential snapshot.
Examples
Options file:
diffsnapshotname volume_base_snap
diffsnapshotname nightly.?
Command line:
dsmc incr \\DRFiler\UserDataVol_Mirror_Share -snapdiff
-useexistingbase -basenameshotname="nightly.?"
-diffsnapshot=latest -diffsnapshotname="nightly.?"
Related information
Basesnapshotname
362
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
►◄
Useexistingbase
Dirmc
The dirmc option specifies the management class you want to use for directories.
If you do not specify this option to associate a management class with directories,
the client program uses the management class in the active policy set of your
policy domain with the longest retention period. Select a management class for
individual directories that retains directories at least as long as it retains the files
associated with them.
If you specify a management class with this option, all directories specified in a
backup operation are bound to that management class.
The dirmc option specifies the management class of directories that you back up
and it does not affect archived directories. Use the archmc option with the archive
command to specify the available management class for your policy domain to
which you want to bind your archived directories and files. If you do not use the
archmc option, the server binds archived directories to the default management
class. If the default management class has no archive copy group, the server binds
archived directories to the management class with the shortest retention period.
Important: Only extended attributes and ACLs are stored in storage pools. The
directory information, other than extended attributes and ACLs, remains in the
database. On Windows systems, directories occupy storage pool space.
Supported Clients
This option is valid for all clients. The server can also define this option.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
Backup tab, Directory Management Class section in the Preferences editor.
Syntax
►► DIRMc
mgmtclassname
►◄
Parameters
mgmtclassname
Specifies the name of the management class that you want to associate with
directories. The client uses the management class name that you specify for all
of the directories that you back up. If you do not specify this option, the client
associates the management class with the longest retention period with
directories.
Examples
Options file:
dirm managdir
Command line
Does not apply.
Chapter 11. Processing options
363
Related information
If you want to back up specific files to a management class see “Assign a
management class to files” on page 267 for more information.
Dirsonly
The dirsonly option processes directories only. The client does not process files.
Use the dirsonly option with the following commands:
v archive
v incremental
v query archive
v query backup
v restore
v restore backupset
v retrieve
v selective
Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support
this option.
Syntax
►► DIrsonly
►◄
Parameters
There are no parameters for this option.
Examples
Command line:
dsmc query backup -dirsonly c:*
Disablenqr
The disablenqr option specifies whether the backup-archive client can use the
no-query restore method for restoring files and directories from the server.
If you set the disablenqr option to no (the default), the client can use the no-query
restore process.
If you set the disablenqr option to yes, the client can use only the standard restore
process (also known as "classic restore").
Note: There is no option or value to specify that the client can use only the
no-query restore method.
Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support
this option. The server can also define this option.
364
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Options File
Place this option in the dsm.opt file.
Syntax
No
►► DISABLENQR
►◄
Yes
Parameters
No Specifies that the client can use the no-query restore method. This is the
default.
Yes
Specifies that the client uses only the standard restore method. The no-query
restore method is not allowed.
Examples
Options file:
disablenqr yes
Command line
-disablenqr=yes
Diskbuffsize
The diskbuffsize option specifies the maximum disk I/O buffer size (in kilobytes)
that the client can use when reading files. The diskbuffsize option replaces the
largecommbuffers option.
Optimal backup, archive migration client performance can usually be achieved if
the value for this option is equal to or smaller than the amount of file read ahead
provided by the client file system. A larger buffer requires more memory and it
might not improve performance.
Important: Use the default setting, unless otherwise directed by IBM support
personnel.
Supported Clients
This option is valid for all clients.
Options File
Place this option in the client options file (dsm.opt).
Syntax
►► DISKBuffsize
size
►◄
Chapter 11. Processing options
365
Parameters
size
Specifies the maximum disk I/O buffer size (in kilobytes) that the client uses
when reading files. The range of values is 16 through 1023; the default is 32.
Examples
Options file:
diskbuffsize 64
Command line:
Does not apply.
Diskcachelocation
The diskcachelocation option specifies the location where the disk cache database
is created if the option memoryefficientbackup=diskcachemethod is set during an
incremental backup.
You can specify the diskcachelocation option in your option file, or with the
include.fs option. If the diskcachelocation option appears in the option file, its
value is used for all file systems not represented by an include.fs option
containing the diskcachelocation option.
The disk cache is a temporary file which is deleted after the incremental command
is run. Use this option to select one of the following:
1. A location that has more free disk space if, when you are using
memoryefficientbackup=diskcachemethod, you get the message that the disk
cache file cannot be created because you do not have enough disk space.
2. A location on a different physical volume to reduce contention for the disk
access mechanism, and therefore improve performance.
Important: For performance reasons, do not use a remote drive for
diskcachelocation.
The actual amount of disk space required for the disk cache file created by disk
cache incremental backups depends on the number of files and directories included
in the backup and on the average length of the files and directories to be backed
up. Estimate 2 bytes per character in the path name. For example, if there are 1 000
000 files and directories to be backed up and the average path length is 200
characters, then the database occupies approximately 400 MB. Another way to
estimate for planning purposes is to multiply the number of files and directories
by the length of the longest path to establish a maximum database size.
Supported Clients
This option is valid for all clients. The server can also define this option.
Options File
Place this option in the client options file (dsm.opt).
Syntax
►► DISKCACHELocation
366
path
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
►◄
Parameters
path
Specifies the location where the disk cache database is created if
memoryefficientbackup=diskcachemethod. The default location is to create the
disk cache file in the root of the file space being processed.
In Uniform Naming Convention (UNC) format, the path must contain a drive
letter. In the following UNC format example, the path contains the drive letter
D$: \\computer7\D$\temp\diskcache.
Examples
Options file:
diskcachelocation c:\temp
diskcachelocation c:\tivoli\data
Command line:
Does not apply.
See “Include options” on page 426 for more information about include.fs.
Domain
The domain option specifies what you want to include for incremental backup.
Domain objects are backed up only if you start the incremental command without
a file specification.
The backup-archive client uses the domain value in the following situations to
determine which drives to process during an incremental backup:
v When you run an incremental backup by using the incremental command, and
you do not specify which drives to process.
v When your IBM Spectrum Protect administrator defines a schedule to run an
incremental backup for you, but does not specify which drives to process.
v When you select the Backup Domain action from the backup-archive client GUI
You can define the domain option in the following locations:
v In an options file.
v On the command line, when entered with a client command.
v In a client option set, which is defined on the server with the define clientopt
command.
v As an option on a scheduled command, which is defined on the server with the
define schedule command.
If any of these sources contain a domain definition, the client backs up that
domain. If more than one source specifies a domain, the client backs up all
specified domains. The same domain object can be defined more than once, but the
effect is the same as defining it only once. If you do not specify a domain, the
client backs up the default domain, as described in the all-local parameter.
You can exclude objects from the domain by specifying the exclusion operator (-)
before the object. If any domain definition excludes an object, that object is
excluded from the domain, even if another definition includes the object. You
cannot use the domain exclusion operator (-) in front of any domain keyword that
begins with all-.
Chapter 11. Processing options
367
If a domain statement excludes one or more objects and no domain statement
includes any objects, the result is an empty domain (nothing is backed up). You
must specify the objects to include in the domain if any domain statements exclude
objects.
Example 1: This example uses one domain statement to back up all local file
systems except for the system state:
domain all-local -systemstate
Example 2: This example uses multiple domain statements to back up all local file
systems except for the system state:
domain all-local domain -systemstate
Example 3: This example excludes the system state from a backup operation. If no
other domain statement is used, the result is an empty domain. Nothing is backed
up.
domain -systemstate
If you start the incremental command with a file specification, the client ignores
any domain definitions and backs up only the file specification.
Supported Clients
This option is valid for all clients. The server can also define this option. The IBM
Spectrum Protect API does not support this option.
Options File
Place this option in the options file, dsm.opt. You can set this option on the Backup
tab, Domain for Backup section of the Preferences editor.
Syntax
all-local
►► DOMain
▼
►◄
object
-object
systemstate
-systemstate
Parameters
all-local
Back up all local volumes on the system, and the Windows system state. This
is the default setting. Local volumes are defined as volumes that are formatted
with a supported file system (ReFS, NTFS, FAT32, or FAT) on a direct-attached
storage device, including SAN and iSCSI attached storage. Directories that are
mapped to drive letters by using the Windows subst command are included in
a backup if the mapped directory is on a local disk.
The following types of volumes are not included when all-local is specified:
v Network attached volumes, including CIFS shares that are mapped to drive
letters.
368
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
v Removable volumes, including CD/DVD drives, USB thumb drives, and
floppy diskette drives. Some USB-attached hard disks are included in the
all-local domain if Windows does not classify them as a removable storage
device.
object
Specifies the domain objects to include in the domain.
An object name must be enclosed in quotation marks if the name includes any
spaces.
-object
Specifies the domain objects to exclude from the domain.
An object name must be enclosed in quotation marks if the name includes any
spaces.
systemstate
Back up the Windows system state. The systemstate domain is included in the
all- local domain.
-systemstate
Exclude system state from backup processing.
Examples
Options file:
An options file can contain more than one domain statement. However,
each of the domain statements is an example of a single statement in an
options file.
domain
domain
domain
domain
domain
c: d: e:
c: systemstate
ALL-LOCAL -systemstate
ALL-LOCAL -c:
ALL-LOCAL -\\florence\e$
A single domain statement can list one or more objects for the domain. You
can use more than one domain statement. The following two examples
from two options files yield the same domain result:
Example 1
...
domain fs1
domain all-local
domain -fs3
...
Example 2
...
domain all-local fs1 -fs3
...
Command line:
-domain=“c: d:”
-domain="ALL-LOCAL -c: -systemstate"
Domain definition interaction
Domain can be defined in several sources, and the result is a summation of all
domain definitions. As an example of the interaction of domain definitions,
consider how domain definitions from several sources yield different backup
results. In the table, FS followed by a number (for example, FS1) is a drive. This
Chapter 11. Processing options
369
table shows only commands that are entered on the command line. For scheduled
commands, the command-line column is not relevant, and options from the
scheduled command must be considered.
Table 54. Interaction of domain definitions from several sources
Options file
Command line
Client option set
Objects backed up using
the incremental command
domain FS1
incremental -domain=FS2
domain FS3
FS1 FS2 FS3
domain FS1
incremental
domain FS3
FS1 FS3
incremental -domain=FS2
FS2
incremental -domain=FS2
domain FS3
FS2 FS3
incremental
domain FS3
FS3
all-local
incremental
domain FS3
all-local + FS3
domain all-local
incremental
domain all-local
domain -FS1
incremental
all-local, but not FS1
domain -FS1
incremental
none
domain FS1 FS3
incremental
domain -FS3
FS1
domain all-local
incremental
domain -FS3
all-local, but not FS3
incremental FS1
-domain=all-local
incremental FS1
domain -FS1
FS1
domain all-local
incremental FS1
FS1
FS1
Related information
Domain.image
The domain.image option specifies what you want to include in your client domain
for an image backup.
Raw logical volumes must be named explicitly.
If you do not specify a file system with the backup image command, the file
systems you specify with the domain.image option are backed up.
When you specify a file system with the backup image command, the
domain.image option is ignored.
If you do not use the domain.image option to specify file systems in your client
options file, and you do not specify a file system with the backup image
command, a message is issued and no backup occurs.
Supported Clients
This option is valid for all supported Windows clients. The server can also define
this option. The IBM Spectrum Protect API does not support this option.
370
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Options File
Place this option in the client options file (dsm.opt). You can set this option in the
Backup > Domain for Backup box in the Preferences editor.
Syntax
►► DOMAIN.IMage
▼
►◄
domain
Parameters
domain
Defines the file systems or raw logical volumes to include in your default
client image domain.
Examples
Options file:
domain.image d: e: f: domain.image f:\mnt\raw\rawmnt1
f:\mnt\fs\fsmnt1
Command line:
Does not apply.
Domain.nas
The domain.nas option specifies the volumes to include in your NAS image
backups.
You can specify all-nas to include all the mounted file systems on the NAS file
server, except those you exclude with the exclude.fs.nas option.
The backup-archive client uses your domain for NAS image backups when you
run a backup nas command and you do not specify which volumes to process.
When you use this option in your client system options file (dsm.opt), the
domain.nas option defines your default domain for NAS image backups.
When you perform a NAS file system image backup using the backup nas
command, the client adds volumes that you specify on the command line to the
volumes defined in your dsm.opt file. For example, if you enter domain.nas
nas1/vol/vol0 nas1/vol/vol1 in your dsm.opt file and you enter dsmc backup nas
-nasnodename=nas1 /vol/vol2 on the command line, the client backs up the
vol/vol0, vol/vol1, and vol/vol2 volumes on node nas1.
If you set the domain.nas option to all-nas in the dsm.opt file, the client backs up
all mounted volumes on the NAS file server. When performing a backup, if you
use a file specification and set the domain.nas option to all-nas in the dsm.opt file,
all-nas takes precedence.
Supported Clients
This option is valid for all Windows clients. The server can also define this option.
Chapter 11. Processing options
371
Options File
Place this option in the client options file (dsm.opt).
Syntax
all-nas
►► DOMAIN.Nas
▼
►◄
domain
Parameters
domain
Defines the volumes you want to process. You cannot exclude volumes by
specifying the dash (-) operator.
all-nas
Processes all mounted volumes on the NAS file server, except those you
exclude with the exclude.fs.nas option. This is the default. If there is no
domain.nas statement in the dsm.opt file and no volumes specified on the
command line, the client backs up all mounted volumes on the NAS server.
Examples
Options file:
domain.nas nas1/vol/vol0 nas1/vol/vol1
domain.nas all-nas
Command line:
Does not apply.
Domain.vmfull
The domain.vmfull option specifies the virtual machines (VMs) to include in your
full virtual machine image backup operations.
This feature is available only if the client operates as a data mover for IBM
Spectrum Protect for Virtual Environments.
This option applies to both VMware and Microsoft Hyper-V virtual machine disks.
Domain.vmfull for VMware virtual machines
For VMware virtual machine backups, the domain.vmfull option works with the
vmchost option. The vmchost option identifies the vCenter server or ESX server that
contains the virtual machines that you want to protect. The domain.vmfull
parameters are used to narrow the focus of an operation to a subset of the virtual
machines that are running on the system that is identified by vmchost.
You can specify which virtual machines are to be processed by using any of the
following techniques:
v Use the VM= option and specify the name of a virtual machine.
v Provide a comma-separated list of virtual machine names.
v Use wildcard syntax to process virtual machines that match the name pattern.
372
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
v Use one of the following domain-level parameters:
all-vm
all-windows
schedule-tag
vmhost
vmfolder
vmhostcluster
vmdatastore
vmresourcepool
vmhostfolder
vmdatacenter
When you use domain-level parameters, virtual machines that are created in the
domain are automatically included when the next backup occurs. For example, if
you use the vmfolder parameter to back up all virtual machines included in a
folder, any new virtual machines that get added to that folder are included in the
next backup. The same is true of pattern-matched names that are included in a
wildcard match.
The virtual machines that are specified on the domain.vmfull option are processed
only when the backup vm command is entered without specifying a virtual
machine or a list of virtual machines on the command line.
Supported Clients
This option can be used with supported Windows clients.
The server can also define this option.
Options file
Set this option in the client options, by using the command line, or by using the
VM Backup tab of the Preferences editor.
Restriction: The following parameters cannot be set in the Preferences Editor.
Include this setting in the options file, or on the command line when you run a
backup vm command:
vmname:vmdk=vmdk_label
schedule-tag
vmresourcepool
vmhostfolder
vmdatacenter
Syntax for VMware virtual machines
Chapter 11. Processing options
373
;
vmname1,vmname2
►► DOMAIN.VMFUll
▼
►◄
VM=vmname1,vmname2
-VM=vmname1,vmname2
ALL-VM
ALL-WINdows
SCHEDULE-TAG
VMHost=srv1,srv2
VMFolder=foldername1,foldername2
VMHOSTCLUSTER=cluster1,cluster2
VMDATASTORE=datastore1,datastore2
VMRESOURCEPOOL=resourcepool1,resourcepool2
VMHOSTFOLDER=hostfolder1,hostfolder2
VMDATACENTER=datacenter1,datacenter2
Syntax rules: Multiple keywords must be separated by a semicolon. Do not
include any spaces after the semicolons. Multiple virtual machine or domain
names must be separated by commas, with no space characters. For examples, see
vm=vmname. The rule about multiple virtual machine or domain names does not
apply if you are using the "Schedule-Tag" keyword.
Parameters
vmname
Specifies the virtual machine name that you want to process. The name is the
virtual machine display name. You can specify a list of virtual machine host
names by separating the names with commas (vm1,vm2,vm5).
vm=vmname
The vm= keyword specifies that the next set of values is a list of virtual
machine names. The vm= keyword is the default and is not required.
In this example, vm= is not specified and commas are used to separate the
machine names.
domain.vmfull my_vm1,my_vm2
If you specify multiple keywords, such as vm= and vmfolder=, the values that
the keywords refer to must be separated by semicolons, with no intervening
space characters:
domain.vmfull vm=my_vm1;vm=my_vm2
domain.vmfull vm=my_vm1;vmfolder=folder1;vmfolder=folder2
Wildcard characters can be used to select virtual machine names that match a
pattern. An asterisk (*) matches any sequence of characters. A question mark
(?) matches any single character, for example:
v Exclude all files that have “test” in the host name: -vm=*test*
v Include all virtual machines with names such as: “test20”, “test25”, “test29”,
“test2A”: vm=test2?
You can exclude a virtual machine from a backup operation by specifying the
exclude operator (-) before the vm= keyword. For example, -vm is used to
exclude a particular machine, or machines, from a domain level backup, such
as, ALL-Windows, ALL-VM, and VMFolder. If “vm1” is the name of a virtual
machine in a folder that is named “accountingDept”, you can back up all of
the virtual machines in the folder, but prevent the virtual machine “vm1” from
being backed up. Set the following option:
domain.vmfull VMFolder=accountingDept;-vm=vm1
374
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
You cannot use the exclude operator (-) to exclude a domain, such as ALL-VM,
ALL-Windows, or VMFolder. The exclude operator works only at the virtual
machine name level.
vmname:vmdk=vmdk_label
The :vmdk= keyword applies only to VMware virtual machines and its use
requires a license for IBM Spectrum Protect for Virtual Environments: Data
Protection for VMware.
This option is typically used to exclude disks (see the :-vmdk syntax) from
being backed up. You can also include virtual machine disks by using the
INCLUDE.VMDISK option or exclude virtual machine disks by using the
EXCLUDE.VMDISK option.
The virtual disks within a virtual machine have disk labels that uniquely
identify each virtual disk. You use the :vmdk= keyword to specify the labels of
the virtual disks that you want to be included in a Backup VM operation. If
you do not specify :vmdk= and a disk label, all virtual disks in the virtual
machine are backed up.
Assume that there is a virtual machine named “my_vm_example”. This virtual
machine has four disks (labeled Hard Disk 1, Hard Disk 2, Hard Disk 3,
Hard Disk 4). To include only Hard Disk 2 and Hard Disk 3 in a backup, add
the :vmdk= keyword and disk label for those disks. Quotation marks are
necessary around the parameters because the disk labels contain space
characters. For example:
domain.vmfull "my_vm_example:vmdk=Hard Disk 2:vmdk=Hard Disk 3"
This next example backs up Hard Disk 1 and Hard Disk 2 on VM1, and Hard
Disk 3 and Hard Disk 4 on VM2. A comma is used to separate the virtual
machine information.
domain.vmfull "vm1:vmdk=Hard Disk 1:vmdk=Hard Disk 2",
"vm2:vmdk=Hard Disk 3:vmdk=Hard Disk 4"
Similar to the -vm= keyword, you can also use the exclusion operator (-) with
:vmdk= to exclude disks from a backup operation.
To back up a virtual machine (vm1) and exclude disks 3 and 4, use the
following syntax:
domain.vmfull "vm1:-vmdk=Hard Disk 3:-vmdk=Hard Disk 4"
To back up two virtual machines, vm1 and vm2, and exclude the first two
disks on each machine, use the following syntax:
domain.vmfull "vm1 :-vmdk=Hard Disk 1:-vmdk=Hard Disk 2",
"vm2:-vmdk=Hard Disk 1:-vmdk=Hard Disk 2"
You can include one or more disks on a domain.vmfull statement. You can
exclude one or more disks on a domain.vmfull statement. You can mix include
and exclude disks on the same statement. For example, the following statement
is valid:
domain.vmfull
"vm1:vmdk=Hard Disk 1:-vmdk=Hard Disk 2:vmdk=Hard Disk 3:vmdk:Hard Disk 4"
If an include statement is present, all other disks in the virtual machine are
excluded from a backup operation, unless the other disks are also specified in
an include statement. For example, the following statement excludes all hard
disks on vm1, except for Hard Disk 1:
domain.vmfull "vm1:vmdk=Hard Disk 1"
Both of the following exclude Hard Disk 4 from a backup of vm1:
Chapter 11. Processing options
375
domain.vmfull "vm1:vmdk=Hard Disk 1:vmdk=Hard Disk 2:vmdk=Hard Disk 3"
domain.vmfull "vm1:-vmdk=Hard Disk 4"
all-vm
For VMware virtual machines. This option processes all virtual machines that
are defined to the Virtual Center or to the ESX server that is specified on the
vmchost option.
all-windows
For VMware virtual machines. This option processes all virtual machines that
are defined to the Virtual Center or to the ESX server that is specified on the
vmchost option. The virtual machines must also have a guest operating system
type of Windows.
schedule-tag
For scheduled backups of VMware virtual machines. This option processes all
virtual machines that are defined to the Virtual Center server that is specified
on the vmchost option.
The IBM Spectrum Protect server administrator can add this option to a
schedule definition to indicate that the schedule is compatible with the
Schedule (IBM Spectrum Protect) category and tag. Virtual machines in
VMware objects that are assigned with the Schedule tag are backed up
according to the schedule.
Requirement: To be compatible for tagging, the -domain.vmfull option must
contain no additional domain-level parameters other than the Schedule-Tag
parameter in the schedule definition. Otherwise, the Schedule (IBM Spectrum
Protect) tag is ignored. The option is case insensitive and must contain no
spaces. Quotation marks that enclose the Schedule-Tag parameter are optional.
Virtual machines in VMware containers that are tagged with incompatible
schedules are not backed up.
For more information about the Schedule tag, see "Supported data protection
tags.".
vmhost=hostname
For VMware virtual machines. This option processes all virtual machines that
are defined to the Virtual Center or to the ESX server that is specified on the
vmchost option. The host name that you specify must match the fully qualified
host name or IP address, as it is specified in the vCenter server Hosts and
Clusters view.
All virtual machines that are added to this host are automatically included in
backup and restore processing. To be included, the virtual machines must also
be running on the ESX server that is specified by the host name; they cannot
be powered off.
This parameter can include multiple ESX servers that are separated by
commas. When the Virtual Center contains multiple ESX servers, this option
does not determine the ESX server from which a snapshot is taken. The ESX
server from which a snapshot is taken is determined by the VMware
VirtualCenter web service.
When you connect directly to an ESXi or ESX host, the vmchost option applies
only if the vmhost is the server that you connect to. If it is not, a warning level
message is sent to the console and is recorded in the dsmerror.log file; it is
also recorded as a server event message.
If the vmenabletemplatebackups option is set to yes, and VM templates are part
of the domain, they are included in the backup.
376
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Restriction: VMware templates for virtual machines cannot be backed up
when they are in an ESX or ESXi host because ESX and ESXi hosts do not
support templates.
vmfolder=foldername
For VMware virtual machines. This option processes all virtual machines that
are defined to the Virtual Center or to the ESX server that is specified on the
vmchost option. The virtual machines must also exist in the VMware folder
that is specified by the folder name. Folder name can include multiple
VMware folders that are separated by commas.
vmhostcluster=hostclustername
For VMware virtual machines. This option processes all virtual machines that
are defined to the Virtual Center or to the ESX server that is specified on the
vmchost option. The virtual machines must also be running on the ESX host
cluster that is specified by the host cluster name. To include more than one
host cluster name, separate the cluster names with commas:
VMHOSTCLUSTER=cluster1,cluster2.
If the vmenabletemplatebackups option is set to yes, and VM templates are part
of the domain, they are included in the backup. A VMware host cluster is not
available if you connect directly to an ESXi or ESX host. If you connect directly
to an ESXi/ESX host and a domain is processed that includes a host cluster, a
warning level message is sent to the console and is recorded in the
dsmerror.log file; it is also recorded as a server event message.
vmdatastore=datastorename
For VMware virtual machines. This option processes all virtual machines that
are defined to the Virtual Center or to the ESX server that is specified on the
vmchost option. The configured datastore location for a virtual machine must
match the datastore name that is specified by datastorename. The datastore
name can include multiple datastores that are separated by commas:
VMDATASTORE=datastore1,datastore2
Virtual machines can have their disk (vmdk files) on more than one datastore;
but there is only one default datastore location. This default datastore location
is defined in the virtual machine configuration and is always where the virtual
machine configuration file (.vmx file) is located. When a machine is selected for
backup by using a domain keyword, the virtual machine configuration file,
and all of the virtual machine's disks are included in the backup, including the
disks that are on a different datastore than the one specified as the domain.
vmresourcepool=resourcepoolname
For VMware virtual machines. This option processes all virtual machines that
are defined to the Virtual Center server that is specified on the vmchost option.
The virtual machines must also exist in the VMware resource pool that is
specified by the resource pool name. The resource pool name can include
multiple resource pools that are separated by commas, for example:
VMRESOURCEPOOL=resourcepool1,resourcepool2
vmhostfolder=hostfoldername
For VMware virtual machines. This option processes all virtual machines that
are defined to the Virtual Center server that is specified on the vmchost option.
The virtual machines must also exist in the VMware host folder that is
specified by the host folder name. The host folder name can include multiple
VMware host folders that are separated by commas, for example:
VMHOSTFOLDER=hostfolder1,hostfolder2
vmdatacenter=datacentername
For VMware virtual machines. This option processes all virtual machines that
Chapter 11. Processing options
377
are defined to the Virtual Center server that is specified on the vmchost option.
The virtual machines must also exist in the VMware datacenter that is
specified by the datacenter name. The datacenter name can include multiple
datacenters that are separated by commas, for example:
VMDATACENTER=datacenter1,datacenter2
Tip: If you specify more than one container type, for example, vmfolder=folder1
and vmhostcluster=cluster2, all virtual machines that are contained in folder1
and cluster2 are protected. The virtual machines do not have to be in both
folder1 and cluster2.
You can specify the virtual machines as shown in this example:
domain.vmfull=vmfolder=folder1;vmhostcluster=cluster2
Examples for VMware virtual machines
Options file:
Include all virtual machines in full VM backup operations.
domain.vmfull all-vm
Include all virtual machines in full VM backup operations, except for the
ones that have a name suffix of _test.
domain.vmfull all-vm;-vm=*_test
Include all virtual machines that have Windows as the operating system, in
full VM backup operations.
domain.vmfull all-windows
Include all virtual machines in cluster servers 1, 2, and 3 in full VM
backup operations.
domain.vmfull vmhostcluster=cluster1,cluster2,cluster3
Include all virtual machine data in datastore1 in full VM backup
operations.
domain.vmfull vmdatastore=datastore1
Include all virtual machines in full VM backup operations, but exclude
virtual machines testvm1 and testmvm2.
domain.vmfull all-vm;-VM=testvm1,testvm2
Include the virtual machines that are defined in the VM folders that are
named lab1 and lab2 in full VM backup operations.
domain.vmfull vmfolder=lab1,lab2
Include all virtual machines on the ESX hosts named “brovar”, “doomzoo”,
and “kepler” in full VM backup operations.
domain.vmfull vmhost=brovar.example.com,
doomzoo.example.com,kepler.example.com
Include the virtual machines in VMware resource pools resourcepool_A
and resourcepool_B in full VM backup operations.
domain.vmfull vmresourcepool=resourcepool_A,resroucepool_B
Include the virtual machines that are defined in the VMware host folders
named hostfolder1 and hostfolder2 in full VM backup operations.
domain.vmfull vmhostfolder=hostfolder1,hostfolder2
Include all virtual machines in VMware datacenter dc1 in full VM backup
operations.
378
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
domain.vmfull vmdatacenter=dc1
Domain.vmfull for Microsoft Hyper-V virtual machines
For Hyper-V VM backups, use the domain.vmfull option to specify which Hyper-V
VMs are processed when you run a backup vm command, without specifying any
Hyper-V VM names.
You can specify which VMs to process by using any of the following techniques:
v Use the VM= option and specify the name of a virtual machine.
v Provide a comma-separated list of virtual machine names.
v Use wildcard syntax to process virtual machines that match the name pattern.
|
|
v Use the vmname:vhdx= option to specify the VM hard disk (VHDX) to include or
exclude during the Hyper-V RCT backup operation of a VM.
v Use the all-vm domain-level parameter. You can also include one or more
virtual machines by using the VM= keyword, or exclude VMs by using the -VM=
syntax.
The virtual machines that are specified on the domain.vmfull option are processed
only when the backup vm command is entered without specifying a virtual
machine or a list of virtual machines on the command line.
Attention: For Microsoft Hyper-V operations, the only valid domain-level
parameter for the domain.vmfull option is all-vm. You can also include one or
more virtual machines by using the VM= keyword, or exclude virtual machines by
using the -VM= syntax.
Supported Clients
This option can be used with supported Windows clients. This option can also be
defined on the server.
Options file
Set this option in the client options, by using the command line, or by using the
VM Backup tab of the Preferences editor.
Restriction: The vmname:vhdx=vhdx_location parameter cannot be set in the
Preferences Editor. Include this setting in the options file, or on the command line
when you run a backup vm command:
Syntax for Microsoft Hyper-V virtual machines
;
vmname1,vmname2
►► DOMAIN.VMFUll
▼
►◄
VM=vmname1,vmname2
-VM=vmname1,vmname2
vmname:vhdx=disk_location
-vmname:vhdx=disk_location
ALL-VM
Chapter 11. Processing options
379
Syntax rules: Multiple keywords must be separated by a semicolon. There cannot
be any spaces after the semicolons. Multiple machine or domain names must be
separated by commas, with no space characters. For examples, see vm=vmname.
Parameters
vmname
Defines the virtual machine name that you want to process. You can supply a
list of virtual machine host names by separating the names with commas
(vm1,VM2,Vm5). The names are case-sensitive and must match the capitalization
that is shown on the Hyper-V host in the Hyper-V Manager > Virtual
Machines view.
vm=vmname
The vm= keyword specifies that the next set of values is a list of virtual
machine names. The vm= keyword is the default and is not required.
In this example, vm= is not specified and commas are used to separate the
machine names.
domain.vmfull my_vm1,my_vm2
If you specify multiple keywords, such as vm= and -vm=, the values that the
keywords refer to must be separated by semicolons, with no intervening space
characters:
domain.vmfull vm=my_vm1;vm=my_vm2
domain.vmfull -vm=my_vm3;-vm=my_vm4
Wildcard characters can be used to select virtual machine names that match a
pattern. An asterisk (*) matches any sequence of characters. A question mark
(?) matches any single character, for example:
v Exclude all files that have “test” in the host name: -vm=*test*
v Include all virtual machines with names such as: “test20”, “test25”, “test29”,
“test2A”:
vm=test2?
You can exclude a virtual machine from a backup operation by specifying the
exclude operator (-) before the vm= keyword. For example, -vm is used to
exclude a particular machine, or machines, from a domain level backup, such
as, ALL-VM. If “vm1” is the name of a virtual machine, you can back up all of
the virtual machines in the domain, but prevent the virtual machine “vm1”
from being backed up. Set the following option:
domain.vmfull all-vm;-vm=vm1
You cannot use the exclude operator (-) to exclude a domain, such as ALL-VM.
The exclude operator works only at the virtual machine name level.
|
|
|
|
vmname:vhdx=vhdx_location
This option specifies the location of the virtual machine hard disk (VHDX) to
include in Hyper-V RCT virtual machine backup operations on the Windows
Server 2016 operating system.
|
|
|
|
The vmname variable specifies the name of the virtual machine to back up.
Wildcard characters can be used to select virtual machine names that match a
pattern. An asterisk (*) matches any sequence of characters. A question mark
(?) matches any single character.
|
|
The :vhdx=disk_location keyword specifies the location of the virtual machine
disk to include in the backup operation. The disk location specified by the
380
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
|
|
|
|
|
disk_location variable must begin with "SCSI" or "IDE" followed by the
controller number and device location number. For example:
|
|
|
|
|
You can exclude a virtual machine disk from backup operations by specifying
the exclude operator (-) before the vhdx= keyword. For example, use -vhdx= to
exclude a VM disk from the backup operation of a virtual machine. For
example:
|
|
|
|
If you specify multiple virtual machine disks to include or exclude, the vhdx=
or -vhdx= keyword and associated values must be separated by colons, with no
intervening space characters. For example:
|
|
|
|
|
If you specify multiple virtual machine names and virtual machine disks, the
VM name and associated values must be separated by semicolons, with no
intervening space characters. For example:
domain.vmfull "vm1:VHDX=IDE 1 0"
domain.vmfull "vm*:VHDX=SCSI 0 1"
domain.vmfull "vm?:VHDX=SCSI 0 1"
domain.vmfull "vm1:-VHDX=IDE 1 0"
domain.vmfull "vm1:vhdx=IDE 1 0:vhdx=SCSI 0 1"
domain.vmfull "vm1:VHDX=IDE 1 0:VHDX=SCSI 0 1;vm2:VHDX=IDE 1 0:VHDX=SCSI 0 1"
domain.vmfull "vm1:-VHDX=IDE 1 0:-VHDX=SCSI 0 1;vm2:-VHDX=IDE 1 0:-VHDX=SCSI 0 1"
all-vm
This option specifies that a backup vm operation processes all Hyper-V virtual
machines that are known to the Hyper-V host.
Examples for Microsoft Hyper-V virtual machines
Options file:
Include all virtual machines in full VM backup operations.
domain.vmfull all-vm
Include all virtual machines in full VM backup operations, except for the
ones that have a name suffix of _test.
domain.vmfull all-vm;-vm=*_test
Include all virtual machines in full VM backup operations, but exclude
virtual machines testvm1 and testmvm2.
domain.vmfull all-vm;-VM=testvm1,testvm2
|
|
|
|
Include IDE disks (with controller 1 and disk location 0) and SCSI disks
(with controller 0 and disk location 1) in Hyper-V RCT backup operations
of virtual machines vm1 and vm2.
|
|
Restriction: You cannot use the all-vm option together with the
vmname:-vhdx= option in the options file or on the command line.
domain.vmfull "vm1:VHDX=IDE 1 0:VHDX=SCSI 0 1;vm2:VHDX=IDE 1 0:VHDX=SCSI 0 1"
Related reference:
“Supported data protection tags” on page 792
“Exclude.vmdisk” on page 399
“Include.vmdisk” on page 434
Enable8dot3namesupport
The enable8dot3namesupport option specifies whether the client backs up and
restores short 8.3 names for files that have long names on NTFS file systems.
Chapter 11. Processing options
381
Supported Clients
This option is valid for all Windows clients.
A file with a long file name might not have a short 8.3 name if short name
generation is disabled on the Windows system. This option is effective only for
NTFS file systems.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
General tab of the Preferences editor.
Syntax
No
►► ENABLE8DOT3NAMESupport
►◄
Yes
Parameters
No Short 8.3 names for files with long file names are not backed up or restored.
This is the default.
Yes
Short 8.3 names for files with long file names are backed up and restored.
Each short name uses up to 14 additional bytes in the server database.
Although this is a small number, if there are many files with short 8.3 names
on many Windows systems, this can increase the size of the IBM Spectrum
Protect server database.
Important: Consult with your IBM Spectrum Protect server administrator before
you use this option.
The first backup that runs with this option causes all files that have short 8.3
names to be updated on the IBM Spectrum Protect server, even if the files have not
otherwise changed. This is because the client is adding the short 8.3 names to the
active backup versions.
If this option is enabled for restore, the client attempts to set the short 8.3 name for
restored files, even if short name generation is disabled on the Windows system.
The client must run under a Windows account that possesses the
SE_RESTORE_NAME privilege in order for this option to be effective. See your
system administrator if you have questions about account privileges.
During restore, the short 8.3 name of a file is not restored if another object in the
same directory already has the same short 8.3 name. In this case, the file is restored
and an informational message is logged indicating that the short name could not
be set. If the file must be restored with its original short name, you must resolve
the conflict with the existing file, and then try the restore again.
Important: This parameter can cause unexpected results in some cases. For
example, if the short name of a file changes between the last time the file was
backed up and the time it is restored, and there is a link or registry entry that
refers to the newer short name, then restoring the file with the older short name
invalidates the references to the newer short name.
382
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Examples
Options file:
enable8dot3namesupport yes
Command line:
-enable8dot3namesupport=yes
Enablearchiveretentionprotection
The enablearchiveretentionprotection option allows the client to connect to the
IBM Spectrum Protect for Data Retention server. This ensures that archive objects
will not be deleted from the server until policy-based retention requirements for
that object have been satisfied.
This option is ignored if the client connects to a server that is not retention
protection enabled. If the option is no (the default) and an attempt is made to
connect to a data retention server, the connection is refused.
The data retention server is specially configured for this task, so normal backup or
restore processing is rejected by the server. When the client is connected to a data
retention server, the following commands will not be available. If you attempt to
use these commands, a message is displayed indicating that they are not valid
with this server.
v incremental
v backup (all subcommands)
v selective
v restore (all subcommands except restore backupset -location=file or
-location=tape)
v
v
v
v
v
Note: restore backupset -location=file or -location=tape do not connect to
any server (except the virtual one) and thus will not be blocked under any
circumstances.
restart restore
delete backup
delete group
expire
All queries except:
– query access
– query archive
– query filespace
– query inclexcl
– query managementclass
– query node
– query options
– query schedule
– query session
– query systeminfo
– query tracestatus
Supported Clients
This option is valid for all clients.
Chapter 11. Processing options
383
Options File
This option is valid only in client options file (dsm.opt) and is not valid in a client
option set from the server. It is not valid on any command line.
Syntax
No
►► ENABLEARCHIVERETENTIONProtection
►◄
Yes
Parameters
No The data retention server connection is refused. This is the default.
Yes
The client connects to a data retention server.
Enablededupcache
Use the enablededupcache option to specify whether you want to use a cache
during client-side data deduplication. Using a local cache can reduce network
traffic between the IBM Spectrum Protect server and the client.
When you perform a backup or archive operation with the data deduplication
cache enabled, the specification of data extents that are backed up or archived are
saved to the cache database. The next time you run a backup or archive, the client
queries the data deduplication cache and identifies the extents of data that have
been previously saved to the server. Data extents that are identical to data extents
on the server are not resent to the server.
If the server and the cache are not synchronized, the cache is removed and a new
one is created.
Only one process can access the distributed data deduplication cache at a time.
Concurrent backup instances on a workstation, that use the same server and
storage pool, must either use unique node names or unique cache specifications. In
this way, all the instances can use a local cache and optimize the client-side data
deduplication.
Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API also supports this
option.
Options File
Place this option in the client options file (dsm.opt). You can set this option on the
Deduplication > Enable Deduplication Cache check box of the Preferences editor.
The option can be set in the client option set on the IBM Spectrum Protect server.
Syntax
Yes*
►► ENABLEDEDUPCache
►◄
No
384
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Parameters
Yes
Specifies that you want to enable data deduplication cache. If data
deduplication is not enabled, this setting is not valid. Yes is the default for the
backup-archive client. No is the default for the IBM Spectrum Protect API.
No Specifies that you do not want to enable data deduplication cache.
Examples
Options file:
enablededupcache no
Command line:
-enablededupcache=no
This option is valid only on the initial command line. It is not valid in interactive
mode.
Related reference:
“Deduplication” on page 356
“Dedupcachepath” on page 355
“Dedupcachesize” on page 355
Enableinstrumentation
By default, instrumentation data is automatically collected by the backup-archive
client and IBM Spectrum Protect API to identify performance bottlenecks during
backup and restore processing. To disable or later enable instrumentation, use the
enableinstrumentation option.
With this option enabled, you do not have to wait for a customer service
representative to direct you to collect performance data when a problem occurs.
Instead, the data can be collected whenever you run a backup or restore operation.
This feature can be helpful because you do not have to re-create the problem just
to collect performance data. The information is already collected by the client.
This option replaces the -TESTFLAG=instrument:detail, -TESTFLAG=instrument:API,
and -TESTFLAG=instrument:detail/API options that are used in previous versions
of the client and API.
For each process, the following types of performance instrumentation data are
collected:
v The activity names for each thread (such as File I/O, Data Verb, Compression,
and Transaction), the average elapsed time per activity, and the frequency of the
activity.
v The total activity time of each thread.
v The command that was issued and the options that were used.
v The summary of the backup, restore, or query command.
By default, the performance data is stored in the instrumentation log file
(dsminstr.log) in the directory that is specified by the DSM_LOG environment
variable (or the DSMI_LOG environment variable for API-dependent products such
as IBM Spectrum Protect for Databases: Data Protection for Microsoft SQL Server
and IBM Spectrum Protect for Mail: Data Protection for Microsoft Exchange
Chapter 11. Processing options
385
Server). If you did not set the DSM_LOG environment variable, the
instrumentation log file is stored in the current directory (the directory where you
issued the dsmc command).
You can optionally change the name and location of the instrumentation log file by
using the instrlogname option. You can also control the size of the log file by
specifying the instrlogmax option.
Performance data is not collected for the backup-archive client GUI or web client
GUI.
Performance data is collected for the following products when the
enableinstrumentation option is specified in the client options file:
v Scheduled file-level backup operations with the backup-archive client
v IBM Spectrum Protect for Virtual Environments: Data Protection for VMware
backups
v IBM Spectrum Protect for Virtual Environments: Data Protection for Microsoft
Hyper-V backups
v IBM Spectrum Protect for Databases: Data Protection for Microsoft SQL Server
backups
v IBM Spectrum Protect for Mail: Data Protection for Microsoft Exchange Server
backups
Performance data is also collected during archive and retrieve processing.
Supported Clients
This option is valid for all clients and the IBM Spectrum Protect API.
Options File
Place this option in the client options file (dsm.opt). The option can be set in the
client option set on IBM Spectrum Protect server.
Tip: This option is enabled by default, so typically, you do not need to place this
option in the client options file unless you need to disable the option.
Syntax
Yes
►► ENABLEINSTRUMENTATION
►◄
No
Parameters
Yes
Specifies that you want to collect performance data during backup and restore
operations. The default value is Yes, which means that performance data is
collected even if you do not specify this option.
By default, the performance data is stored in the instrumentation log file
(dsminstr.log) in the directory that is specified by the DSM_LOG environment
variable. If you did not set the DSM_LOG environment variable, the
instrumentation log file is stored in the current directory (the directory where
386
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
you issued the dsmc command). If the file does not exist, the client creates the
file and adds performance data to the file.
No Specifies that you do not want to collect performance data during backup and
restore operations. If the instrumentation log exists, no more data is added to
the file.
Examples
Options file:
enableinstrumentation yes
Command line:
dsmc sel c:\mydir\* -subdir=yes -enableinstrumentation=yes
This option is valid only on the initial command line. It is not valid in interactive
mode.
Related tasks:
Collecting client instrumentation data
Collecting API instrumentation data
Related reference:
“Instrlogmax” on page 444
“Instrlogname” on page 445
Enablelanfree
The enablelanfree option specifies whether to enable an available LAN-free path
to a storage area network (SAN) attached storage device.
A LAN-free path allows backup, restore, archive, and retrieve processing between
the backup-archive client and the SAN-attached storage device.
To support LAN-free data movement you must install and configure the IBM
Spectrum Protect for SAN storage agent on the client workstation.
Note:
1. If you place the enablelanfree option in the client option file (dsm.opt), but
zero (0) bytes were transferred through the SAN during an operation, ensure
that you bind the data to a LAN-free enabled management class.
2. To restore backup sets in a SAN environment, see “Restore Backupset” on
page 746 for more information.
3. When a LAN-free path is enabled, the SAN Storage Agent settings override the
client tcpserveraddress, tcpport, and ssl options. This override action occurs
to ensure that both the client and the Storage Agent use the same server
communication options.
Supported Clients
This option is valid for all Windows clients.
Options File
Place this option in the client options file (dsm.opt). You can also set this option by
selecting the Enable Lanfree check box on the General tab in the Preferences
editor.
Chapter 11. Processing options
387
Syntax
No
►► ENABLELanfree
►◄
Yes
Parameters
Yes
Specifies that you want to enable an available LAN-free path to a
SAN-attached storage device.
No Specifies that you do not want to enable a LAN-free path to a SAN-attached
storage device. This is the default.
Examples
Options file:
enablelanfree yes
Command line:
-enablelanfree=yes
This option is valid only on the initial command line. It is not valid in interactive
mode.
Related information
To specify a communication protocol between the backup-archive client and
storage agent, see “Lanfreecommmethod” on page 447.
Encryptiontype
Use the encryptiontype option to specify the algorithm for data encryption.
The encryptiontype affects only backup and archive operations. The data that you
include is stored in encrypted form, and encryption does not affect the amount of
data that is sent or received. During restore and retrieve operations the encrypted
data is decrypted with the proper encryption algorithm, regardless of the setting
for this option.
Supported Clients
This option is valid for all clients.
Options File
Place this option in the client options file (dsm.opt). You can also set this option on
the Authorization tab of the Preferences editor. The server can override this.
Syntax
AES128
►► ENCRYPTIONType
►◄
AES256
388
IBM Spectrum Protect for Windows Backup-Archive Clients: Installation and User's Guide
Parameters
AES128
AES 128-bit data encryption. AES 128-bit is the default.
AES256
AES 256-bit data encryption. AES 256-bit data encryption provides the highest
level of data encryption available in backup and archive operations.
Examples
Options file:
encryptiontype aes128
Command line:
Does not apply.
|
Encryptkey
|
|
|
The backup-archive client supports the option to encrypt files that are being
backed up or archived to the IBM Spectrum Protect server. This option is enabled
with the include.encrypt option.
|
|
|
|
All files matching the pattern on the include.encrypt specification are encrypted
before the data is