IBM Spectrum Protect

UNIX and Linux Backup-Archive Clients

Version 8.1.9

Installation and User's Guide

IBM
 Note:
Before you use this information and the product it supports, read the information in “Notices” on page
725.

This edition applies to version 8, release 1, modification 9 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 International Business Machines Corporation 1993, 2019.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents

Tables................................................................................................................. xv

About this publication ........................................................................................ xxi

Who should read this publication..............................................................................................................xxi
Publications .............................................................................................................................................. xxi
Conventions used in this publication....................................................................................................... xxii
Reading syntax diagrams......................................................................................................................... xxii

Backup-archive client updates........................................................................... xxv

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...................................................................................... 2
Client environment requirements............................................................................................................... 3
AIX client environment...........................................................................................................................3
HP-UX Itanium 2 API environment........................................................................................................4
Linux on Power Systems client environment.........................................................................................4
Linux x86_64 client environment.......................................................................................................... 5
Linux on System z client environment................................................................................................... 6
Mac OS X client environment................................................................................................................. 7
Oracle Solaris client environment..........................................................................................................7
NDMP support requirements (Extended Edition only)................................................................................8
Installation requirements for backing up and archiving Tivoli Storage Manager FastBack client data.... 8
Install the UNIX and Linux backup-archive clients.....................................................................................9
Installing the AIX client..........................................................................................................................9
Uninstalling the AIX client................................................................................................................... 12
Installing the HP-UX Itanium 2 API.....................................................................................................12
Uninstalling the HP-UX Itanium 2 API.................................................................................................14
Installing the client on Linux on Power Systems (Little Endian).........................................................15
Uninstalling the client on Linux on Power (Little Endian)....................................................................18
Installing the client on Ubuntu Linux on Power Systems (Little Endian)............................................19
Uninstalling the client on Ubuntu Linux on Power Systems (Little Endian)........................................22
Installing the API on Linux on Power Systems (Big Endian)............................................................... 23
Uninstalling the API on Linux on Power Systems (Big Endian)...........................................................25
Installing the Linux x86_64 client....................................................................................................... 26
Uninstalling the Linux x86_64 client................................................................................................... 30
Installing the Ubuntu Linux x86_64 client.......................................................................................... 31
Uninstalling the Ubuntu Linux x86_64 client...................................................................................... 35
Installing the Linux on System z client................................................................................................ 36
Uninstalling the Linux on System z client............................................................................................ 39
Installing the Mac OS X client.............................................................................................................. 40
Uninstalling the Mac OS X client.......................................................................................................... 41
Installing the Oracle Solaris x86_64 client......................................................................................... 42
Uninstalling the Oracle Solaris x86_64 client..................................................................................... 44
Installing the Oracle Solaris SPARC API..............................................................................................45
Uninstalling the Oracle Solaris SPARC API..........................................................................................46
Software updates (AIX, Linux, Mac, and Solaris clients).................................................................... 47
Installing the client management service.................................................................................................47

iii
 Chapter 2. Configure the IBM Spectrum Protect client.......................................... 49
UNIX and Linux client root and authorized user tasks............................................................................. 49
Enable non-root users to manage their own data.................................................................................... 51
Enabling encryption for backup-archive client users..........................................................................51
Enable non-root users to manage shared data.........................................................................................52
Client options file overview....................................................................................................................... 53
Creating and modifying the client system-options file....................................................................... 54
Creating a default client-user options file........................................................................................... 56
Creating a customized client user-options file....................................................................................58
Environment variables (AIX, Linux, Mac, Solaris)..................................................................................... 58
Set language environment variables................................................................................................... 58
Set processing environment variables................................................................................................ 59
Set Bourne and Korn shell variables....................................................................................................61
Set C shell variables............................................................................................................................. 61
Set API environment variables............................................................................................................ 61
Web client configuration overview............................................................................................................ 62
Configuring the web client on AIX, Linux, Mac, and Solaris systems................................................. 62
Configuring the scheduler..........................................................................................................................63
Comparison between client acceptor-managed services and traditional scheduler services.......... 64
Configuring the client to use the client acceptor service to manage the scheduler.......................... 64
Start the client scheduler (AIX, Linux, Mac, Solaris)................................................................................ 66
Scheduling events using the command-line client............................................................................. 66
Configuring IBM Spectrum Protect client/server communication across a firewall................................68
Configuring IBM Spectrum Protect client/server communication with Secure Sockets Layer............... 70
Creating a symbolic link to access the latest GSKit library.................................................................72
Certificate Authorities root certificates............................................................................................... 74
Configure your system for journal-based backup.....................................................................................75
Journal daemon configuration............................................................................................................. 75
Client-side data deduplication.................................................................................................................. 80
Configuring the client for data deduplication...................................................................................... 84
Excluding files from data deduplication.............................................................................................. 86
Automated client failover configuration and use......................................................................................87
Automated client failover overview..................................................................................................... 87
Configuring the client for automated failover......................................................................................90
Determining the status of replicated client data.................................................................................92
Preventing automated client failover...................................................................................................93
Forcing the client to fail over................................................................................................................94
Configuring the client to back up and archive Tivoli Storage Manager FastBack data............................ 94
Cluster environment configuration and use..............................................................................................95
Overview of cluster environments....................................................................................................... 96
Configuring the backup-archive client in a cluster environment........................................................ 96
Enabling web client access in a Cluster Environment ......................................................................101
Migrating legacy AIXIBM PowerHA SystemMirror setups................................................................ 103
AIX configuration considerations prior to performing snapshot-based file backups and archives......104
Configuring NetApp and IBM Spectrum Protect for snapshot difference incremental backups.......... 104
Protecting clustered-data ONTAP NetApp file server volumes........................................................106
SnapMirror support for NetApp snapshot-assisted progressive incremental backup (snapdiff)....109
Register your workstation with a server................................................................................................. 111
Closed registration............................................................................................................................. 112
Open registration............................................................................................................................... 112
Creating an include-exclude list .............................................................................................................112
Include-exclude options.................................................................................................................... 113
Symbolic link and alias processing....................................................................................................120
Determine compression and encryption processing........................................................................ 120
Preview include-exclude list files...................................................................................................... 121
Include and exclude option processing............................................................................................ 122

iv
Chapter 3. Getting started................................................................................. 125
Configuring the client security settings to connect to the IBM Spectrum Protect server version
8.1.2 and later.................................................................................................................................... 125
Configuring by using the default security settings (fast path).......................................................... 125
Configuring without automatic certificate distribution..................................................................... 128
Secure password storage........................................................................................................................ 130
IBM Spectrum Protect client authentication.......................................................................................... 131
Starting a Java GUI session.....................................................................................................................132
IBM Spectrum Protect password...................................................................................................... 133
Setup wizard.......................................................................................................................................133
Starting a command-line session............................................................................................................133
Using batch mode.............................................................................................................................. 134
Issuing a series of commands by using interactive mode................................................................ 134
Specifying input strings that contain blank spaces or quotation marks................................................ 135
Starting: Additional considerations.........................................................................................................135
Using the web client in the new security environment...........................................................................136
Starting a web client session............................................................................................................. 136
Starting a web user interface session for file-restore operations..........................................................137
Downloading system logs.................................................................................................................. 138
Start the client scheduler automatically.................................................................................................140
Changing your password......................................................................................................................... 140
Sorting file lists using the backup-archive client GUI............................................................................ 142
Displaying online help............................................................................................................................. 143
Ending a session...................................................................................................................................... 143
Online forums.......................................................................................................................................... 144

Chapter 4. Backing up your data.........................................................................145

Planning your backups ........................................................................................................................... 145
Which files are backed up....................................................................................................................... 145
When to back up and when to archive files............................................................................................ 146
Pre-backup considerations (UNIX and Linux)........................................................................................ 147
LAN-free data movement...................................................................................................................147
Incremental backups on memory-constrained systems..................................................................148
Incremental backups on systems with a large number of files........................................................148
Include-exclude options to control processing................................................................................ 150
Data encryption during backup or archive operations...................................................................... 150
File system and ACL support............................................................................................................. 151
Maximum file size for operations.......................................................................................................155
Long user and group names...............................................................................................................155
Mac OS X volume names....................................................................................................................156
Mac OS X Unicode enablement......................................................................................................... 157
Mac OS X Time Machine backup disk................................................................................................ 157
Performing an incremental, selective, or incremental-by-date backup (UNIX and Linux)................... 158
Full and partial incremental backup.................................................................................................. 158
Incremental-by-date backup............................................................................................................ 162
Comparing incremental-by-date, journal-based, and NetApp snapshot difference to full
incremental and partial incremental backups............................................................................. 162
Snapshot differential backup with HTTPS (Linux)............................................................................ 163
Selective backup................................................................................................................................ 165
Solaris global zone and non-global zones backups.......................................................................... 165
Saving access permissions................................................................................................................ 166
Setting a virtual mount point............................................................................................................. 166
Backing up data using the Java GUI.................................................................................................. 166
Backing up data using the command line......................................................................................... 167
Deleting backup data......................................................................................................................... 170
Deleting file spaces............................................................................................................................ 171

v
 Backing up files from one or more file spaces for a group backup (UNIX and Linux)........................... 172
Backing up data with client-node proxy support (UNIX and Linux).......................................................172
Enabling multiple node operations from the GUI............................................................................. 173
Setting up encryption.........................................................................................................................174
Scheduling backups with client-node proxy support....................................................................... 174
Associate a local snapshot with a server file space (UNIX and Linux)...................................................178
Image backup.......................................................................................................................................... 178
Performing prerequisite tasks before creating an image backup.....................................................179
Utilizing image backups to perform file system incremental backups.............................................181
Performing an image backup using the GUI......................................................................................183
Performing an image backup using the command line.....................................................................185
Snapshot-based file backup and archive and snapshot-based image backup..................................... 185
Protecting Btrfs file systems................................................................................................................... 186
Backing up and restoring Btrfs file systems......................................................................................187
Backing up and restoring Btrfs subvolumes..................................................................................... 188
Back up NAS file systems using Network Data Management Protocol..................................................189
Backing up NAS file systems with the backup-archive client GUI using NDMP protocol................190
Back up NAS file systems using the command line.......................................................................... 191
Backup network file systems.................................................................................................................. 193
Back up NFS file systems with the global namespace feature.........................................................193
Back up AIX workload partition file systems..........................................................................................194
Backing up Solaris Zettabyte file systems.............................................................................................. 195
AIX JFS2 encrypted file system backup................................................................................................. 196
Back up AIX JFS2 extended attributes................................................................................................... 197
Backing up VMware virtual machines..................................................................................................... 197
Preparing the environment for full backups of VMware virtual machines....................................... 199
Creating full backups for VMware virtual machines..........................................................................200
Parallel backups of virtual machines.................................................................................................202
Back up and archive Tivoli Storage Manager FastBack data.................................................................. 202
Display backup processing status...........................................................................................................202
Backup (UNIX and Linux): Additional considerations............................................................................ 205
Stored files......................................................................................................................................... 205
Special file systems............................................................................................................................206
NFS or virtual mount points............................................................................................................... 206
Management classes......................................................................................................................... 206
Back up symbolic links.......................................................................................................................207
Hard links........................................................................................................................................... 209
Sparse files......................................................................................................................................... 209
NFS hard and soft mounts................................................................................................................. 209
Deleted file systems...........................................................................................................................210
Opened files....................................................................................................................................... 210
Wildcard characters........................................................................................................................... 211

Chapter 5. Restoring your data...........................................................................213

Restoring an image.................................................................................................................................. 213
Restoring an image using the GUI..................................................................................................... 214
Restoring an image using the command line.................................................................................... 215
Restore data from a backup set.............................................................................................................. 216
Restore backup sets: considerations and restrictions......................................................................218
Backup set restore............................................................................................................................. 219
Restoring backup sets using the GUI................................................................................................ 220
Backup set restores using the client command-line interface.........................................................220
Restoring or retrieving data during a failover......................................................................................... 221
Restore an image to file...........................................................................................................................222
Manage GPFS file system data with storage pools.................................................................................223
Restoring data to a point in time............................................................................................................. 224
Restoring data from a retention set........................................................................................................ 226

vi
 Restore AIX encrypted files.................................................................................................................... 227
Restore AIX workload partition file systems.......................................................................................... 227
Restore NAS file systems........................................................................................................................ 229
Restoring NAS file systems using the backup-archive client GUI.................................................... 229
Options and commands to restore NAS file systems from the command line................................ 230
Restore active or inactive backups......................................................................................................... 231
Restoring data using the GUI.................................................................................................................. 231
Command line restore examples............................................................................................................ 232
Examples: Command line restores for large amounts of data......................................................... 233
Standard query restore, no-query restore, and restartable restore.................................................234
Restoring Solaris Zettabyte (ZFS) file systems.......................................................................................235
Additional restore tasks.......................................................................................................................... 236
Authorizing another user to restore or retrieve your files.................................................................236
Restoring or retrieving files from another client node...................................................................... 237
Restore or retrieve files to another workstation............................................................................... 238
Restoring a disk in case of disk loss.................................................................................................. 238
Deleting file spaces............................................................................................................................ 239
Enable SELinux to restore files on the Red Hat Enterprise Linux 5 client........................................ 240

Chapter 6. Archive and retrieve your data (UNIX and Linux)................................ 241
Archive files..............................................................................................................................................241
Archiving data with the GUI............................................................................................................... 241
Archive data examples by using the command line..........................................................................242
Archiving data with client node proxy............................................................................................... 244
Deleting archive data......................................................................................................................... 245
Advanced archive tasks..................................................................................................................... 246
Retrieve archives..................................................................................................................................... 247
Retrieving data with the GUI..............................................................................................................248
Retrieve data examples by using the command line........................................................................ 248
Archive management classes............................................................................................................ 249

Chapter 7. IBM Spectrum Protect scheduler overview........................................ 251

Examples: Blank spaces in file names in schedule definitions.............................................................. 252
Preferential start times for certain nodes...............................................................................................252
Scheduler processing options................................................................................................................. 253
Evaluate schedule return codes in schedule scripts.........................................................................254
Return codes from preschedulecmd and postschedulecmd scripts................................................254
Client-acceptor scheduler services versus the traditional scheduler services..................................... 255
Setting the client scheduler process to run as a background task and start automatically at startup 256
Examples: Display information about scheduled work.......................................................................... 258
Display information about completed work............................................................................................259
Specify scheduling options......................................................................................................................260
Scheduler options for commands........................................................................................................... 260
Enable or disable scheduled commands................................................................................................ 260
Manage multiple schedule requirements on one system...................................................................... 261

Chapter 8. Client return codes............................................................................263

Chapter 9. Storage management policies............................................................265

Policy domains and policy sets............................................................................................................... 265
Management classes and copy groups................................................................................................... 266
Display information about management classes and copy groups....................................................... 267
Copy group name attribute................................................................................................................ 268
Copy type attribute............................................................................................................................ 268
Copy frequency attribute................................................................................................................... 268
Versions data exists attribute............................................................................................................ 268
Versions data deleted attribute......................................................................................................... 268

vii
 Retain extra versions attribute.......................................................................................................... 268
Retain only version attribute..............................................................................................................268
Copy serialization attribute................................................................................................................269
Copy mode parameter....................................................................................................................... 269
Copy destination attribute................................................................................................................. 270
Retain versions attribute....................................................................................................................270
Deduplicate data attribute.................................................................................................................270
Select a management class for files....................................................................................................... 270
Assign a management class to files........................................................................................................ 271
Override the management class for archived files................................................................................. 272
Select a management class for directories.............................................................................................272
Bind management classes to files.......................................................................................................... 273
Rebind backup versions of files.............................................................................................................. 273
Retention grace period............................................................................................................................ 273
Event-based policy retention protection................................................................................................ 274
Archive files on a data retention server.............................................................................................275

Chapter 10. Processing options.......................................................................... 277

Processing options overview...................................................................................................................277
Communication options.......................................................................................................................... 278
TCP/IP options................................................................................................................................... 278
Shared memory options.....................................................................................................................279
Server options..........................................................................................................................................279
Backup and archive processing options................................................................................................. 280
Restore and retrieve processing options................................................................................................ 289
Scheduling options.................................................................................................................................. 292
Format and language options..................................................................................................................294
Command processing options.................................................................................................................294
Authorization options.............................................................................................................................. 294
Error processing options......................................................................................................................... 295
Transaction processing options.............................................................................................................. 295
Web client options................................................................................................................................... 296
Diagnostics options................................................................................................................................. 297
Using options with commands................................................................................................................ 297
Entering options with a command..................................................................................................... 298
Initial command-line-only options.................................................................................................... 304
Client options that can be set by the IBM Spectrum Protect server................................................ 304
Client options reference.......................................................................................................................... 306
Absolute.......................................................................................................................................... 306
Afmskipuncachedfiles................................................................................................................ 307
Archmc............................................................................................................................................... 308
Archsymlinkasfile.......................................................................................................................308
Asnodename...................................................................................................................................... 309
Auditlogging..................................................................................................................................311
Auditlogname..................................................................................................................................312
Autodeploy...................................................................................................................................... 314
Autofsrename..................................................................................................................................315
Automount........................................................................................................................................ 316
Backmc............................................................................................................................................... 317
Backupsetname............................................................................................................................... 318
Basesnapshotname.........................................................................................................................319
Cadlistenonport........................................................................................................................... 320
Changingretries........................................................................................................................... 321
Class................................................................................................................................................. 321
Collocatebyfilespec.................................................................................................................. 322
Commmethod...................................................................................................................................... 323
Commrestartduration.................................................................................................................. 324

viii
Commrestartinterval.................................................................................................................. 325
Compressalways............................................................................................................................. 325
Compression....................................................................................................................................326
Console.............................................................................................................................................328
Createnewbase............................................................................................................................... 329
Csv..................................................................................................................................................... 330
Datacenter...................................................................................................................................... 333
Datastore........................................................................................................................................ 333
Dateformat...................................................................................................................................... 334
Dedupcachepath............................................................................................................................. 337
Dedupcachesize............................................................................................................................. 338
Deduplication............................................................................................................................... 338
Defaultserver............................................................................................................................... 339
Deletefiles....................................................................................................................................340
Description....................................................................................................................................341
Detail............................................................................................................................................... 342
Diffsnapshot..................................................................................................................................343
Diffsnapshotname.........................................................................................................................344
Dirmc................................................................................................................................................. 345
Dirsonly.......................................................................................................................................... 346
Disablenqr...................................................................................................................................... 347
Diskbuffsize..................................................................................................................................347
Diskcachelocation.......................................................................................................................348
Domain............................................................................................................................................... 349
Domain.image..................................................................................................................................353
Domain.nas...................................................................................................................................... 354
Domain.vmfull............................................................................................................................... 355
Dontload.......................................................................................................................................... 361
Dynamicimage..................................................................................................................................362
Efsdecrypt...................................................................................................................................... 363
Enablearchiveretentionprotection......................................................................................363
Enablededupcache.........................................................................................................................365
Enableinstrumentation..............................................................................................................366
Enablelanfree............................................................................................................................... 367
Encryptiontype............................................................................................................................. 368
Encryptkey...................................................................................................................................... 369
Errorlogmax....................................................................................................................................371
Errorlogname..................................................................................................................................372
Errorlogretention.......................................................................................................................373
Exclude options........................................................................................................................... 374
Fbbranch.......................................................................................................................................... 381
Fbclientname..................................................................................................................................382
Fbpolicyname..................................................................................................................................383
Fbreposlocation........................................................................................................................... 384
Fbserver.......................................................................................................................................... 385
Fbvolumename..................................................................................................................................386
Filelist.......................................................................................................................................... 387
Filename.......................................................................................................................................... 389
Filesonly........................................................................................................................................ 390
Followsymbolic............................................................................................................................. 391
Forcefailover............................................................................................................................... 392
Fromdate.......................................................................................................................................... 393
Fromnode.......................................................................................................................................... 394
Fromowner........................................................................................................................................ 395
Fromtime.......................................................................................................................................... 395
Groupname........................................................................................................................................ 396
Groups (deprecated).........................................................................................................................396
Host................................................................................................................................................... 397

ix
 Httpport.......................................................................................................................................... 397
Hsmreparsetag............................................................................................................................... 397
Ieobjtype........................................................................................................................................ 399
Ifnewer.............................................................................................................................................399
Imagegapsize..................................................................................................................................400
Imagetofile....................................................................................................................................401
Inactive.......................................................................................................................................... 401
Inclexcl.......................................................................................................................................... 402
Include options.................................................................................................................................. 403
Incrbydate...................................................................................................................................... 420
Incremental....................................................................................................................................421
Instrlogmax....................................................................................................................................421
Instrlogname..................................................................................................................................422
Lanfreecommmethod.......................................................................................................................423
Lanfreeshmport............................................................................................................................. 425
Lanfreetcpport............................................................................................................................. 425
Lanfreessl...................................................................................................................................... 426
Lanfreetcpserveraddress......................................................................................................... 427
Latest............................................................................................................................................... 427
Localbackupset............................................................................................................................. 428
Makesparsefile............................................................................................................................. 429
Managedservices........................................................................................................................... 430
Maxcmdretries............................................................................................................................... 431
Mbobjrefreshthresh.................................................................................................................... 432
Mbpctrefreshthresh.................................................................................................................... 433
Memoryefficientbackup..............................................................................................................434
Mode................................................................................................................................................... 435
Monitor.............................................................................................................................................438
Myreplicationserver.................................................................................................................. 438
Nasnodename....................................................................................................................................440
Nfstimeout...................................................................................................................................... 441
Nodename.......................................................................................................................................... 442
Nojournal (AIX, Linux)........................................................................................................................ 443
Noprompt.......................................................................................................................................... 443
Nrtablepath....................................................................................................................................444
Numberformat..................................................................................................................................445
Optfile.............................................................................................................................................447
Password.......................................................................................................................................... 447
Passwordaccess............................................................................................................................. 449
Passworddir....................................................................................................................................450
Pick................................................................................................................................................... 451
Pitdate.............................................................................................................................................452
Pittime.............................................................................................................................................453
Postschedulecmd/Postnschedulecmd...................................................................................... 453
Postsnapshotcmd........................................................................................................................... 455
Preschedulecmd/Prenschedulecmd...........................................................................................456
Preservelastaccessdate............................................................................................................457
Preservepath..................................................................................................................................458
Presnapshotcmd............................................................................................................................. 461
Queryschedperiod.........................................................................................................................462
Querysummary..................................................................................................................................463
Quiet................................................................................................................................................. 464
Quotesareliteral.........................................................................................................................465
Removeoperandlimit.................................................................................................................... 466
Replace.............................................................................................................................................466
Replserverguid............................................................................................................................. 467
Replservername............................................................................................................................. 469
Replsslport....................................................................................................................................470

x
Repltcpport....................................................................................................................................472
Repltcpserveraddress................................................................................................................ 474
Resourceutilization.................................................................................................................. 475
Retryperiod....................................................................................................................................477
Revokeremoteaccess.................................................................................................................... 478
Schedcmddisabled.........................................................................................................................479
Schedcmdexception.......................................................................................................................479
Schedgroup...................................................................................................................................... 480
Schedlogmax....................................................................................................................................481
Schedlogname..................................................................................................................................482
Schedlogretention.......................................................................................................................483
Schedmode........................................................................................................................................ 485
Schedrestretrdisabled..............................................................................................................486
Scrolllines....................................................................................................................................487
Scrollprompt..................................................................................................................................488
Servername...................................................................................................................................... 489
Sessioninitiation.......................................................................................................................490
Setwindowtitle............................................................................................................................. 491
Shmport.............................................................................................................................................492
Showmembers....................................................................................................................................493
Skipacl.............................................................................................................................................493
Skipaclupdatecheck.................................................................................................................... 494
Snapdiff.......................................................................................................................................... 494
Snapdiffchangelogdir................................................................................................................ 499
Snapdiffhttps............................................................................................................................... 501
Snapshotcachesize.......................................................................................................................502
Snapshotproviderfs.................................................................................................................... 503
Snapshotproviderimage..............................................................................................................504
Snapshotroot..................................................................................................................................504
Srvoptsetencryptiondisabled.................................................................................................506
Srvprepostscheddisabled......................................................................................................... 507
Srvprepostsnapdisabled............................................................................................................508
Ssl..................................................................................................................................................... 509
Sslacceptcertfromserv..............................................................................................................510
Ssldisablelegacytls.................................................................................................................. 511
Sslfipsmode........................................................................................................................................512
Sslrequired....................................................................................................................................512
Stagingdirectory.........................................................................................................................514
Subdir............................................................................................................................................... 515
Tagschedule....................................................................................................................................517
Tapeprompt...................................................................................................................................... 520
Tcpadminport..................................................................................................................................522
Tcpbuffsize....................................................................................................................................522
Tcpcadaddress............................................................................................................................... 523
Tcpclientaddress.........................................................................................................................524
Tcpclientport............................................................................................................................... 524
Tcpnodelay...................................................................................................................................... 525
Tcpport.............................................................................................................................................526
Tcpserveraddress.........................................................................................................................526
Tcpwindowsize............................................................................................................................... 527
Timeformat...................................................................................................................................... 528
Toc..................................................................................................................................................... 531
Todate............................................................................................................................................... 532
Totime............................................................................................................................................... 532
Txnbytelimit..................................................................................................................................533
Type................................................................................................................................................... 534
Updatectime....................................................................................................................................535
Useexistingbase........................................................................................................................... 535

xi
 Usereplicationfailover............................................................................................................536
Users (deprecated)...........................................................................................................................537
V2archive........................................................................................................................................ 537
Verbose.............................................................................................................................................538
Verifyimage....................................................................................................................................539
Virtualfsname............................................................................................................................... 539
Virtualmountpoint.......................................................................................................................539
Virtualnodename........................................................................................................................... 541
Vmbackdir........................................................................................................................................ 541
Vmbackuplocation.........................................................................................................................542
Vmbackupmailboxhistory............................................................................................................544
Vmbackuptype..................................................................................................................................544
Vmchost.............................................................................................................................................545
Vmcpw................................................................................................................................................. 546
Vmctlmc.............................................................................................................................................547
Vmcuser.............................................................................................................................................548
Vmdatastorethreshold................................................................................................................ 548
Vmdefaultdvportgroup.......................................................................................................................550
Vmdefaultdvswitch............................................................................................................................ 551
Vmdefaultnetwork............................................................................................................................. 551
Vmenabletemplatebackups......................................................................................................... 552
Vmlimitperdatastore.................................................................................................................. 554
Vmlimitperhost............................................................................................................................. 555
Vmmaxbackupsessions.................................................................................................................. 556
Vmmaxparallel............................................................................................................................... 558
Vmmaxrestoresessions................................................................................................................ 559
Vmmaxrestoreparalleldisks..................................................................................................... 560
Vmmaxrestoreparallelvms......................................................................................................... 561
Vmmaxvirtualdisks.............................................................................................................................563
Vmmc................................................................................................................................................... 564
Vmnocbtcontinue........................................................................................................................... 564
Vmnoprdmdisks............................................................................................................................... 565
Vmnovrdmdisks............................................................................................................................... 566
Vmpreferdagpassive.................................................................................................................... 567
Vmprocessvmwithindependent...................................................................................................568
Vmprocessvmwithprdm.................................................................................................................. 569
Vmskipctlcompression................................................................................................................ 570
Vmskipmaxvirtualdisks...................................................................................................................... 570
Vmskipmaxvmdks.............................................................................................................................. 571
Vmtagdatamover............................................................................................................................. 572
Vmtagdefaultdatamover..............................................................................................................574
Vmverifyifaction................................................................................................................................. 576
Vmverifyiflatest.................................................................................................................................. 578
Vmvstorcompr..................................................................................................................................579
Vmvstortransport.........................................................................................................................580
Vmtimeout........................................................................................................................................ 581
Webports.......................................................................................................................................... 582
Wildcardsareliteral.................................................................................................................. 583

Chapter 11. Using commands.............................................................................585

Start and end a client command session................................................................................................ 588
Process commands in batch mode....................................................................................................588
Process commands in interactive mode........................................................................................... 588
Enter client command names, options, and parameters....................................................................... 589
Command name................................................................................................................................. 589
Options............................................................................................................................................... 589
Parameters......................................................................................................................................... 590

xii
 File specification syntax.....................................................................................................................590
Wildcard characters.................................................................................................................................592
Client commands reference.................................................................................................................... 592
Archive.................................................................................................................................................. 593
Archive FastBack.............................................................................................................................. 595
Backup FastBack.................................................................................................................................597
Backup Group....................................................................................................................................... 600
Backup Image....................................................................................................................................... 602
Static, dynamic, and snapshot image backup...................................................................................605
Utilizing image backup to perform file system incremental backup................................................ 605
Backup NAS............................................................................................................................................606
Backup VM..............................................................................................................................................608
Cancel Process...................................................................................................................................615
Cancel Restore...................................................................................................................................615
Delete Access..................................................................................................................................... 616
Delete Archive...................................................................................................................................616
Delete Backup..................................................................................................................................... 618
Delete Filespace.............................................................................................................................. 622
Delete Group....................................................................................................................................... 623
Expire.................................................................................................................................................... 624
Help.........................................................................................................................................................626
Incremental......................................................................................................................................... 627
Journal-based backup (AIX, Linux)................................................................................................... 631
Incremental-by-Date......................................................................................................................... 632
Associate a local snapshot with a server file space..........................................................................632
Loop.........................................................................................................................................................633
Macro.......................................................................................................................................................634
Monitor Process.................................................................................................................................635
Preview Archive.................................................................................................................................635
Preview Backup...................................................................................................................................636
Query Access....................................................................................................................................... 637
Query Archive..................................................................................................................................... 638
Query Backup....................................................................................................................................... 640
Query NAS file system images...........................................................................................................643
Query Backupset.................................................................................................................................643
Query Backupset without the backupsetname parameter........................................................645
Query Filespace.................................................................................................................................646
Query NAS file spaces........................................................................................................................ 648
Query Group......................................................................................................................................... 648
Query Image......................................................................................................................................... 650
Query Inclexcl...................................................................................................................................652
Query Mgmtclass.................................................................................................................................653
Query Node............................................................................................................................................654
Query Options..................................................................................................................................... 655
Query Restore..................................................................................................................................... 656
Query Schedule...................................................................................................................................657
Query Session..................................................................................................................................... 657
Query Systeminfo.............................................................................................................................. 658
Query VM................................................................................................................................................ 659
Restart Restore.................................................................................................................................663
Restore.................................................................................................................................................. 664
Restore from file spaces that are not Unicode-enabled................................................................... 668
Restore Backupset............................................................................................................................ 668
Restore backup sets: considerations and restrictions......................................................................671
Restore backup sets in a SAN environment...................................................................................... 672
Restore Backupset without the backupsetname parameter................................................... 672
Restore Group..................................................................................................................................... 675
Restore Image..................................................................................................................................... 677

xiii
 Restore NAS......................................................................................................................................... 679
Restore VM............................................................................................................................................681
Preview virtual machine restore operations..................................................................................... 691
Retrieve................................................................................................................................................ 693
Retrieve archives from file spaces that are not Unicode-enabled................................................... 696
Schedule................................................................................................................................................ 696
Selective..............................................................................................................................................698
Associate a local snapshot with a server file space..........................................................................700
Set Access............................................................................................................................................701
Set Event..............................................................................................................................................703
Set Netappsvm ...................................................................................................................................705
Set Password....................................................................................................................................... 706
Set Vmtags............................................................................................................................................711
Data protection tagging overview...................................................................................................... 712

Appendix A. Accessibility...................................................................................723

Notices..............................................................................................................725
Glossary............................................................................................................ 729

Index................................................................................................................ 731

xiv
Tables

1. Upgrading the client from different server versions.....................................................................................2

2. AIX client communication methods............................................................................................................. 4

3. Supported features on AIX ...........................................................................................................................4

4. HP-UX Itanium 2 API communication methods...........................................................................................4

5. Linux on Power Systems client communication methods............................................................................5

6. Linux on Intel x86_64 client communication methods............................................................................... 6

7. Linux on System z client communication methods...................................................................................... 6

8. Mac OS X client communication methods.................................................................................................... 7

9. Oracle Solaris client communication methods.............................................................................................8

10. HP-UX Itanium 2 client: Language codes for installation packages....................................................... 13

11. Package names, contents, and default directory.....................................................................................15

12. Package names, contents, and default directory.....................................................................................20

13. Package names, contents, and default directory.....................................................................................23

14. Language pack identifiers......................................................................................................................... 26

15. Package names, contents, and default directory.....................................................................................27

16. Language pack identifiers......................................................................................................................... 31

17. Package names, contents, and default directory.....................................................................................32

18. Language pack identifiers......................................................................................................................... 35

19. Package names, contents, and default directory.....................................................................................36

20. Language pack identifiers......................................................................................................................... 40

21. Installation package names and descriptions......................................................................................... 43

22. Installation package names and descriptions......................................................................................... 45

23. Tasks for root users and authorized users............................................................................................... 49

xv
 24. Mac OS X authorization tools and associated IBM Spectrum Protect applications................................51

25. Client acceptor-managed services versus traditional scheduler services..............................................64

26. Data deduplication settings: Client and server........................................................................................ 83

27. Options for excluding file spaces and directories..................................................................................114

28. Options for controlling processing using include and exclude statements.......................................... 115

29. Wildcard and other special characters...................................................................................................118

30. Using wildcard characters with include and exclude patterns..............................................................119

31. Options for controlling symbolic link and alias processing................................................................... 120

32. Options for controlling compression and encryption............................................................................ 121

33. Working with your files using the backup-archive client GUI................................................................142

34. Supported file systems and ACL support...............................................................................................151

35. Maximum file size................................................................................................................................... 155

36. Command-line backup examples...........................................................................................................167

37. Volume device-type support for an image backup................................................................................ 180

38. Comparing incremental image backup methods................................................................................... 183

39. LVM1 and LVM2 image operation comparisons.....................................................................................184

40. NAS options and commands.................................................................................................................. 192

41. Backup and restore capabilities for VMware virtual machines on Linux platforms..............................198

42. Client command line informational messages.......................................................................................203

43. Backup set GUI restore restrictions.......................................................................................................217

44. Backup set command-line restore restrictions..................................................................................... 217

45. Sample WPAR restore commands with dsm.opt file............................................................................. 228

46. NAS options and commands.................................................................................................................. 230

47. Command-line restore examples...........................................................................................................232

48. Command line archive examples........................................................................................................... 242

xvi
49. Symbolic link management table for archive and retrieve.................................................................... 246

50. Command line examples of retrieving archives.....................................................................................248

51. Sample classic query schedule output.................................................................................................. 258

52. Sample enhanced query schedule output............................................................................................. 259

53. Client return codes and their meanings................................................................................................. 263

54. Default attribute values in the standard management class................................................................ 267

55. TCP/IP options........................................................................................................................................ 278

56. Shared memory communication options............................................................................................... 279

57. Sample client system-options file..........................................................................................................280

58. Backup and archive processing options.................................................................................................280

59. Restore and retrieve processing options............................................................................................... 289

60. Scheduling options................................................................................................................................. 292

61. Format and language options................................................................................................................. 294

62. Command processing options................................................................................................................ 294

63. Authorization options............................................................................................................................. 295

64. Error processing options.........................................................................................................................295

65. Transaction processing options............................................................................................................. 296

66. Web client options.................................................................................................................................. 296

67. Diagnostics options.................................................................................................................................297

68. Client command options.........................................................................................................................299

69. Options that are valid on the initial command line only........................................................................ 304

70. Options that can be set by the IBM Spectrum Protect server............................................................... 305

71. Column heading names.......................................................................................................................... 331

72. Sample time format settings in the locale configuration (t_fmt line)................................................... 337

73. Sample date format settings in the locale configuration (d_fmt line)...................................................337

xvii
 74. Interaction of domain definitions from several sources........................................................................353

75. Other optional parameters..................................................................................................................... 407

76. Incremental command: Related options............................................................................................... 496

77. Effects of server and client SSL settings on success or failure of login attempts................................ 513

78. Sample time format settings in the locale configuration (t_fmt line)................................................... 530

79. Sample date format settings in the locale configuration (d_fmt line)...................................................530

80. Commands.............................................................................................................................................. 585

81. Wildcard characters................................................................................................................................592

82. Archive command: Related options....................................................................................................... 594

83. Archive FastBack command: Related options....................................................................................... 596

84. Backup FastBack command: Related options....................................................................................... 598

85. Backup Group command: Related options............................................................................................ 601

86. Backup Image command: Related options............................................................................................603

87. Backup NAS command: Related options............................................................................................... 607

88. Delete Archive command: Related options............................................................................................617

89. Delete Backup command: Related options............................................................................................621

90. Delete Filespace command: Related options........................................................................................ 622

91. Delete Group command: Related options..............................................................................................624

92. Expire command: Related options......................................................................................................... 625

93. Incremental command: Related options............................................................................................... 628

94. Query Archive command: Related options............................................................................................ 639

95. Query Backup command: Related options............................................................................................ 641

96. Query Backupset command: Related options....................................................................................... 644

97. Query Backupset command: Related options....................................................................................... 646

98. Query Filespace command: Related options......................................................................................... 647

xviii
99. Query Group command: Related options...............................................................................................649

100. Query Image command: Related options............................................................................................ 651

101. Query Mgmtclass command: Related options.....................................................................................653

102. Query Node command: Related options..............................................................................................654

103. Query Options command: Related options..........................................................................................655

104. Query Systeminfo command: Related options.................................................................................... 659

105. Query VM command: Related options for VMware virtual machine queries...................................... 660

106. Restore command: Related options.................................................................................................... 666

107. Restore Backupset command: Related options.................................................................................. 670

108. Restore Group command: Related options......................................................................................... 675

109. Restore Image command: Related options......................................................................................... 678

110. Restore NAS command: Related options.............................................................................................680

111. Restore VM command: Related options used for restoring VMware virtual machines...................... 687

112. Retrieve command: Related options....................................................................................................694

113. Schedule command: Related options.................................................................................................. 697

114. Selective command: Related options.................................................................................................. 699

115. Order of precedence of vSphere inventory objects............................................................................. 721

xix
xx
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:
• A server program that acts as a backup and archive server for distributed workstations and file servers.
The server program also supplies hierarchical storage management (HSM) services, and enables
systems to perform as a migration server.
• 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.
• 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.
• 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.
Associated with IBM Spectrum Protect, but sold separately, are the IBM Spectrum Protect for Space
Management and IBM Spectrum Protect HSM for Windows client programs. These products automatically
migrate eligible files to storage to maintain specific levels of free space on local file systems and
automatically recall migrated files when they are accessed. It also enables users to migrate and recall
specific files.
The terms hierarchical storage management and space management have the same meaning throughout
this publication.
Related concepts
Planning your backups
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 backing up data.
What's new for Version 8.1.9
IBM Spectrum Protect Version 8.1.9 introduces new features and updates.
Installing the IBM Spectrum Protect backup-archive clients
The IBM Spectrum Protect backup-archive client helps you protect information on your workstations.

Who should read this publication

This publication provides instructions for a user to install, configure, and use the IBM Spectrum Protect
client.

Publications
The IBM Spectrum Protect product family includes IBM Spectrum Protect Plus, IBM Spectrum Protect for
Virtual Environments, 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, 2019 xxi

Conventions used in this publication
This publication uses the following typographical conventions:
Example Description
A series of lowercase letters with an extension indicates program file names.
autoexec.ncf
hsmgui.exe

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.
• The ►►─── symbol indicates the beginning of a syntax diagram.
• The ───► symbol at the end of a line indicates that the syntax diagram continues on the next line.
• The ►─── symbol at the beginning of a line indicates that a syntax diagram continues from the previous
line.
• The ───►◄ symbol indicates the end of a syntax diagram.
Syntax items, such as a keyword or a variable, can be:
• On the line (required element)
• Above the line (default element)
• Below the line (optional element)

Symbols
Enter these symbols exactly as they appear in the syntax diagram.
• * Asterisk
• { } Braces
• : Colon
• , Comma
• = Equal Sign
• - Hyphen
• () Parentheses
• . Period

xxii About this publication

• Space
• " quotation mark
• '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

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.
cmd_name
A

About this publication xxiii

 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

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.

cmd_name ?

xxiv IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
What's new for Version 8.1.9
IBM Spectrum Protect Version 8.1.9 introduces new features and updates.
New and changed information in this product documentation is indicated by a vertical bar (|) to the left of
the change.
The following features and updates are new for this release:
Web user interface for file restore operations is available on additional AIX® operating system
The web user interface for file restore operations is now available on the AIX operating system. With
the web user interface feature, you can perform file-restore operations on behalf of an end user,
without the need to have access to the client web server machine. This feature is available as an
optional component.
For installation instructions, see “Installing the AIX client” on page 9.
For instructions about starting the web user interface, see “Starting a web user interface session for
file-restore operations” on page 137.
Signature checking
With this release, you can now check the signature of the client package before installation. For more
information, see:
• “Installing the backup-archive client on Linux on Power Systems (Little Endian)” on page 15
• “Installing the API on Linux on Power Systems (Big Endian)” on page 23
• “Installing the Linux x86_64 client” on page 26
• “Installing the Linux on System z client” on page 36
Maintenance updates
Updates for APARs and other minor updates are provided.
For a list of new features and updates in previous V8.1 releases, see Backup-archive client updates.
Related information
About this publication
IBM Spectrum Protect is a client/server licensed product that provides storage management services in a
multiplatform computer environment.

© Copyright IBM Corp. 1993, 2019 xxv

xxvi IBM Spectrum Protect UNIX and Linux 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 along 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.9
IBM Spectrum Protect Version 8.1.9 introduces new features and updates.
Planning your backups
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 backing up data.

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.9 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.
For information about upgrading your current AIX IBM PowerHA® SystemMirror® setups, see “Migrating
legacy AIXIBM PowerHA SystemMirror setups” on page 103.

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:
• If you are upgrading the client and it is installed on the same system as the IBM Spectrum Protect
server V8.1.2 or later level, ensure that you halt the IBM Spectrum Protect server before you upgrade
the client. This action will prevent the client installation process from forcing the system to reboot. After
you upgrade the client, you can restart the IBM Spectrum Protect server.
This information applies to AIX and Linux clients.
• If you are upgrading from the IBM Tivoli® Storage Manager Version 7.1.2 or earlier backup-archive client
on the Oracle Solaris operating system, you must uninstall any previously installed language packages
before you proceed with the upgrade.
• For Mac users, updates to the Mac OS X client contained in IBM Spectrum Protect V6.3, or newer
versions, require you to consider the following items:
– When you use the Mac OS X client that is provided in this release, ensure that the dsm.sys and
dsm.opt files are encoded by using Unicode (UTF-8). UTF-8 encoding enables the use of characters

© Copyright IBM Corp. 1993, 2019 1

 from any language in the options files. If your dsm.sys or dsm.opt files were previously encoded as
MacRoman (or anything other than UTF-8), open them in an editor like TextEdit and save them with
UTF-8 encoding, and without the .txt extension. Your include-exclude lists can be encoded as
either UTF-8 or UTF-16. For more information about using Unicode, see “Considerations for Unicode-
enabled clients” on page 403.
– IBM Spectrum Protect server file spaces that were created by Mac OS 9 clients cannot be managed
by the Mac OS X client that was provided in IBM Spectrum Protect V6.3. Use q file node f=d on
the server to list files stored for a node. Any Mac-platform files that do not start with a slash (/) were
probably created by an older Mac client. You cannot restore or otherwise manage these files by using
the Mac OS X client that is provided in this release. You can manage these files, but you must use a
Mac client that is installed on a version 6.2.2 or older client node.
• 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.
The procedure for automatically deploying client upgrades depends on the version of the IBM Spectrum
Protect server that you are upgrading the client from. The following table shows the client upgrade
procedures for different versions of the server.

Table 1. Upgrading the client from different server versions

Server version Target client version Procedure
V8.1.3 or later Use the IBM Spectrum Protect
V7.1.8 or later V7 releases
Operations Center. For more
V8.1.2 or later V8 releases
information, see Scheduling
client updates.
V8.1.2 See technote 2004596.
V7.1.8 or later V7 releases
V8.1.2 or later V8 releases

See technote 1673299.

V7.1.8 or earlier V7 releases V7.1.6 or earlier V7 releases
V8.1.1 or earlier V8 servers V8.1.0

Restrictions: The following restrictions apply to automatic client deployment:

• The Windows cluster services environment is not supported.
• 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.
• Do not schedule automatic client deployments to systems that have any of the following applications
installed on them:
– IBM Spectrum Protect for Virtual Environments
– IBM Spectrum Protect for Databases
– IBM Spectrum Protect for Mail
– IBM Spectrum Protect for Enterprise Resource Planning

2 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Related reference
“Autodeploy” on page 314
Use the autodeploy option to enable or disable an automatic deployment of the client if a restart is
required.

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.
• “AIX client environment” on page 3
• “HP-UX Itanium 2 API environment” on page 4
• “Linux on Power Systems client environment” on page 4
• “Linux x86_64 client environment” on page 5
• “Linux on System z client environment” on page 6
• “Mac OS X client environment” on page 7
• “Oracle Solaris client environment” on page 7
• “NDMP support requirements (Extended Edition only)” on page 8
For current information about the client environment prerequisites for all of the supported backup-
archive client platforms, see technote 1243309.

AIX client environment

This section contains client environment information, backup-archive client components, and hardware
and software requirements for the AIX platform.

AIX client installable components

The backup-archive client is comprised of several installable components.
The installable components for the AIX client are as follows:
• Backup-archive command line client
• Administrative client
• Backup-archive client graphical user interface, which uses Oracle Java™ technology
• Backup-archive web client
• IBM Spectrum Protect 64-bit API
The API can be separately installed. The other components are all installed when you install the AIX
package (tivoli.tsm.client.api.64bit).

System requirements for the AIX client

The IBM Spectrum Protect AIX client requires a minimum amount of hardware, disk space, memory, and
software.
For software and hardware requirements for all supported versions of AIX clients, including the most
recent fix packs, see
technote 1052226.

AIX client communication methods

The TCP/IP and shared memory communication methods are available for the AIX backup-archive client.
You can use the following communication methods with the IBM Spectrum Protect Version 8.1.9 AIX
client:

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 3

 Table 2. AIX client communication methods
To use this communication Install this software: To connect to these IBM
method: Spectrum Protect servers:
TCP/IP TCP/IP (Standard with supported AIX,Linux, Windows
AIX platforms)
Shared Memory TCP/IP (Standard with supported AIX
AIX platforms)

Backup-archive client features that are available on AIX

This topic lists the features that are supported on AIX.

Table 3. Supported features on AIX

Features Supported on AIX?
Backup-archive command-line and GUI yes
Journal-based backup yes
LAN-free operations yes
Online image backup yes
Offline image backup yes

HP-UX Itanium 2 API environment

Review API environment information, installable components, and hardware and software requirements
for the HP-UX Itanium 2 platform.

HP-UX Itanium 2 API installable component

You can install only the HP-UX Itanium 2 API in IBM Spectrum Protect Version 8.1.9.

System requirements for the HP-UX Itanium 2 API

The IBM Spectrum Protect HP-UX Itanium 2 API requires a minimum amount of hardware, disk space,
memory, and software.
For software and hardware requirements for all supported versions of the HP-UX Itanium 2 API, including
the most recent fix packs, see
technote 1197146.

HP-UX Itanium 2 API communication methods

The TCP/IP and shared memory communication methods are available for the HP-UX Itanium 2 API.

Table 4. HP-UX Itanium 2 API communication methods

To use this communication Install this software: To connect to these IBM
method: Spectrum Protect servers:
TCP/IP TCP/IP (Standard with HP-UX) AIX, Linux, Windows

Linux on Power Systems client environment

This section contains client environment information, backup-archive client components, and hardware
and software requirements for the Linux on Power Systems client platforms.

Linux on Power Systems client installable components

The backup-archive client command-line, Java GUI, web backup-archive, and API comprise the Linux on
Power Systems backup-archive client installable components.
You can install the following components with IBM Spectrum Protect Version 8.1.9:

4 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • Backup-archive client
• Administrative client
• Backup-archive Java graphical user interface (GUI)
• Web backup-archive client
• IBM Spectrum Protect API (64-bit)

System requirements for clients on Linux on Power Systems

The IBM Spectrum Protect clients on Linux on Power Systems require a minimum amount of hardware,
disk space, memory, and software.
For software and hardware requirements for all supported versions of clients on Linux on Power Systems,
including the most recent fix packs, see
technote 1169963.

Linux on Power Systems client communication methods

Backup-archive clients on Linux on Power Systems can use either TCP/IP or shared memory as the
communications method for client-server communications.
Table 5 on page 5 lists the available Linux on Power Systems client communications methods, and the
IBM Spectrum Protect server operating systems that you can use them with.

Table 5. Linux on Power Systems client communication methods

To use this communication Install this software: To connect to these IBM
method: Spectrum Protect servers:
TCP/IP TCP/IP (Standard with Linux) AIX, Linux, Windows
Shared Memory TCP/IP (Standard with Linux) Linux on Power® Systems

Linux x86_64 client environment

This section contains client environment information, backup-archive client components, and hardware
and software requirements for the Linux on Intel (Linux x86_64) platform.

Linux x86_64 client installable components

The backup-archive client is comprised of several installable components.
The installable components for the Linux backup-archive client are as follows:
• Backup-archive client web files
• Backup-archive client GUI files
• Administrative client command line files
• Client API SDK files
• Client API (64-bit) runtime files
• WEBGUI (for file-restore operations using the web user interface)

System requirements for Linux x86_64 clients

The IBM Spectrum Protect Linux x86_64 clients require a minimum amount of hardware, disk space,
memory, and software.
For software and hardware requirements for all supported versions of Linux x86_64 clients, including the
most recent fix packs, see
technote 1052223.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 5

 Linux x86_64 client communication methods
The TCP/IP and shared memory communication methods are available for the Linux on Intel (Linux
x86_64) backup-archive client.
You can use the following communication methods with the IBM Spectrum Protect Version 8.1.9 Linux on
Intel (Linux x86_64) client:

Table 6. Linux on Intel x86_64 client communication methods

To use this communication Install this software: To connect to these IBM
method: Spectrum Protect servers:
TCP/IP TCP/IP (Standard with Linux) AIX, Linux, Windows
Shared Memory TCP/IP (Standard with Linux) Linux x86_64

Linux on System z client environment

This section contains client environment information, backup-archive client components, and hardware
and software requirements for the Linux on System z platform.

Linux on System z client installable components

The backup-archive client command-line, administrative client, web backup-archive client, and API
comprise the Linux on System z backup-archive client installable components.
You can install the following components with IBM Spectrum Protect Version 8.1.9:
• Backup-archive client
• Administrative client
• Web backup-archive client
• IBM Spectrum Protect API

System requirements for Linux on System z clients

IBM Spectrum Protect Linux System z clients require a minimum amount of hardware, disk space,
memory, and software.
For software and hardware requirements for all supported versions of Linux System z clients, including
the most recent fix packs, see
technote 1066436.

Linux on System z client communication methods

The TCP/IP and shared memory communication methods are available for the Linux on System z backup-
archive client.
You can use the following communication methods with the IBM Spectrum Protect Version 8.1.9 Linux on
System z client:

Table 7. Linux on System z client communication methods

To use this communication Install this software: To connect to these IBM
method: Spectrum Protect servers:
TCP/IP TCP/IP (Standard with Linux) AIX, Linux, Windows
Shared Memory TCP/IP (Standard with Linux) Linux on System z

6 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Mac OS X client environment
This section contains client environment information, backup-archive client components, and hardware
and software requirements for the Mac OS X client.

Mac OS X client installable components

The backup-archive client command-line, Java GUI, web backup-archive, and API comprise the Mac OS X
backup-archive client installable components.
The following components are installed with IBM Spectrum Protect Version 8.1.9:
• Backup-archive client
• Administrative client
• Web backup-archive client
• IBM Spectrum Protect API
• Backup-archive Java graphical user interface (GUI)
Tip: The dsmj shell script file for the Java GUI is installed in the following location:

/Library/Application Support/tivoli/tsm/client/ba/bin

System requirements for Mac OS X clients

The IBM Spectrum Protect Mac OS X clients require a minimum amount of hardware, disk space, memory,
and software.
For software and hardware requirements for all supported versions of Mac OS X clients, including the
most recent fix packs, see
technote 1053584.

Mac OS X client communication methods

The TCP/IP communication methods are available for the Mac OS X backup-archive client.
You can use the following communication methods with the IBM Spectrum Protect Version 8.1.9 Mac OS
X client:

Table 8. Mac OS X client communication methods

To use this communication Install this software: To connect to these IBM
method: Spectrum Protect servers:
TCP/IP TCP/IP (standard with Mac OS X) AIX, Linux, Windows

Oracle Solaris client environment

Review client environment information, client components, and hardware and software requirements for
the Oracle Solaris platform.
Starting in IBM Spectrum Protect Version 8.1.0, the Oracle Solaris backup-archive client is available only
on the Oracle Solaris x86_64 platform. The Oracle Solaris API is available on the Oracle Solaris x86_64
and Oracle Solaris SPARC platforms.

Oracle Solaris client installable components

The IBM Spectrum Protect command-line, Java GUI, web backup-archive, and API comprise the Solaris
backup-archive client installable components.
You can install the following client components on Oracle Solaris x86_64:
• Backup-archive client
• Administrative client
• Backup-archive Java graphical user interface (GUI)
• Web backup-archive client

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 7

 • IBM Spectrum Protect API
You can install the IBM Spectrum Protect API on Oracle Solaris SPARC.

System requirements for Oracle Solaris clients

The IBM Spectrum Protect Oracle Solaris clients require a minimum amount of hardware, disk space,
memory, and software.
For software and hardware requirements for all supported versions of IBM Spectrum Protect Oracle
Solaris clients, including the most recent fix packs, see the following IBM support pages:
• For Oracle Solaris x86_64 client requirements, see technote 1232956.
• For Oracle Solaris SPARC API requirements, see technote 1052211.

Oracle Solaris client communication methods

The TCP/IP and shared memory communication methods are available for the Oracle Solaris backup-
archive client.
You can use the following communication methods with the Oracle Solaris client:

Table 9. Oracle Solaris client communication methods

To use this communication Install this software: To connect to these IBM
method: Spectrum Protect servers:
TCP/IP TCP/IP (Standard with Solaris) AIX, Linux, Windows

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.
NDMP support requires the following hardware and software:
• IBM Spectrum Protect Extended Edition
• 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:
• Tivoli Storage Manager FastBack Version 6.1
• Tivoli Storage Manager client V6.1.3.x (where x is 1 or higher) or V6.2 or later
• Tivoli Storage Manager server V6.1.3 or higher
• 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/tivoli-storage-management/maintenance/
admincenter/v6r3/. If you do not already have an Administration Center installed, you must create

8 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 http://www.ibm.com/support/
knowledgecenter/SS9NU9/.
For information about integrating IBM Spectrum Protect and Tivoli Storage Manager FastBack, see
Integrating and .
You can install the IBM Spectrum Protect client in one of the following ways:
• 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, and the
FastBack shell.
• Install backup-archive client on a workstation where neither the FastBack server or the FastBack
Disaster Recovery Hub is installed. In this case, the FastBack shell is still required.
Related concepts
“Configuring the client to back up and archive Tivoli Storage Manager FastBack data” on page 94
Before you can back up or archive Tivoli Storage Manager FastBack client data, you must complete
configuration tasks.

Install the UNIX and Linux backup-archive clients

This section provides instructions to install and set up IBM Spectrum Protect UNIX and Linux clients.
Note: You must log on as the root user to install the backup-archive client on a UNIX or Linux workstation.
The supported UNIX and Linux clients and the location of the installation instructions for each client are
listed here.
• “Installing the AIX client” on page 9
• “Installing the HP-UX Itanium 2 API” on page 12
• “Installing the backup-archive client on Linux on Power Systems (Little Endian)” on page 15
• “Installing the backup-archive client on Ubuntu Linux on Power Systems (Little Endian)” on page 19
• “Installing the API on Linux on Power Systems (Big Endian)” on page 23
• “Installing the Linux x86_64 client” on page 26
• “Installing the Ubuntu Linux x86_64 client” on page 31
• “Installing the Linux on System z client” on page 36
• “Installing the Mac OS X client” on page 40
• “Installing the Oracle Solaris x86_64 client” on page 42
• “Installing the Oracle SPARC API” on page 45
Related concepts
“Configure the IBM Spectrum Protect client” on page 49
After installing the backup-archive client, you must configure it before performing any operations.

Installing the AIX client

You can install the AIX backup-archive client from the product installation media.

Before you begin

If you plan to install the client on the same system as the IBM Spectrum Protect server V8.1.2 or later
level, ensure that you halt the IBM Spectrum Protect server before you install the client. This action will
prevent the client installation process from forcing the system to reboot. After you install the client, you
can restart the IBM Spectrum Protect server.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 9

 About this task
In IBM Spectrum Protect Version 8.1.9, a 64-bit version of the AIX client is provided in the distribution
libraries.
You cannot upgrade a previously installed 32-bit AIX client to new the 64-bit AIX client. If you have a 32-
bit client that is installed from a previous version of IBM Spectrum Protect, use SMIT to perform the
following steps:
1. Uninstall the 32-bit client (tivoli.tsm.client.ba).
2. Uninstall any national language files that were previously installed.
3. Uninstall the API (tivoli.tsm.client.api.32bit).
Next, use SMIT to install the following packages in the IBM Spectrum Protect V8.1.9 distribution libraries,
in the following order:
1. Install the 64-bit API (tivoli.tsm.client.api.64bit).
2. Install the 64-bit client (tivoli.tsm.client.ba.64bit).
If you already have a 64-bit IBM Spectrum Protect V6.3 (or newer) client installed, you can upgrade the
client instead of uninstalling it and reinstalling it.
If you have a 64-bit client from an earlier version of IBM Spectrum Protect installed (for example, V6.1, or
V6.2) you must uninstall the client, language packs, and API. Then, install the new IBM Spectrum Protect
API and client.
All of the packages that are needed to install the client are in the AIX client package, and they overwrite
any older runtime applications on your system during installation. The LibC (C Set ++) runtime library is
required.
When you use the installp command to install this client, do not change the default field values for the
following two choices:
• AUTOMATICALLY install requisite software?
• OVERWRITE same or newer versions?
Disabling or changing the values allows a lower-level client component to install over a currently higher
installed component. Under such circumstances, function calls between components at different levels
might not be valid any longer.
Install the following packages. They are all provided on the installation media. You need an Extended
Edition license to use the NAS client.
The following files are listed in order of dependency. For example, the API is dependent on the Global
Security Kit (GSKit). When you install all of them using SMIT, you can select them (F7) in any order.
GSKit8.gskcrypt64.ppc.rte and GSKit8.gskssl64.ppc.rte
IBM GSKit 64-bit (required by the 64-bit client API).
tivoli.tsm.client.api.64bit
Installs the 64-bit API.
tivoli.tsm.client.ba.64bit
Installs the following 64-bit client files:
• Backup-archive Java client (GUI)
• Backup-archive web client
• NAS backup client
tivoli.tsm.filepath_aix
Installs the file path kernel extension that is required for journal-based backup.
tivoli.tsm.client.jbb.64bit
Installs the journal-based backup component.

10 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
tivoli.tsm.client.webgui
Installs the files required to perform file-restore operations by using the web user interface.
Each package is installed in the following default installation directory:
• The backup-archive, web client, and administrative client (dsmadmc) 64-bit files are installed in
the /usr/tivoli/tsm/client/ba/bin64 directory.
• The IBM Spectrum Protect 64-bit API files are installed in the /usr/tivoli/tsm/client/api/
bin64 directory.
• The sample system-options file, dsm.sys.smp, is placed in the installation directory.
This installation procedure can be used to install new distributions or updates from downloaded
installation media. The downloaded files that you use to install the client might be compressed.
Depending on the package file format, either copy or extract the files to disk and use these instructions to
install the components.
You can download the appropriate package file from one of the following websites:
• Download the client package from Passport Advantage or Fix Central.
• For the latest information, updates, and maintenance fixes, go to the IBM Support Portal.
If you are copying the client files into a local directory first, a .toc file is automatically created by the
installp command. You can create a .toc file manually by running /usr/sbin/inutoc in the local
directory to which you copied the IBM Spectrum Protect image. From the AIX command line, enter:

/usr/sbin/inutoc /usr/sys/inst.images

A .toc file is created in that directory.

Procedure
1. Log in as the root user.
2. Mount the volume that you are installing from.
3. From the AIX command line, type smitty install and press Enter.
4. Select Install and Update Software and press Enter.
5. Select Install and Update From ALL Available Software and press Enter.
6. At the INPUT device/directory for software prompt, press the F4 key and specify the
directory that contains the installation images, and press Enter.
7. At the SOFTWARE to install prompt, press the F4 key. Select the IBM Spectrum Protect file sets
you want to install by pressing the F7 key. Then, press the Enter key.
8. On the Install and Update From ALL Available Software panel, press the F4 key to change any entry
fields, or use the default fields. Press Enter twice to begin the installation.
9. After the installation completes, press F10 to exit.

Results
When file sets are installed, they are automatically committed on the system. The previous version of
backup-archive client software is replaced by the newly installed version.
The backup-archive client files are installed in the /usr/tivoli/tsm/client/ba/bin64 directory. If
you move the client files to another directory, you must perform the following steps:
1. Make sure that the permissions of the installed files have not changed.
2. Update the symbolic links for the installed files in the following directories:
• The /usr/bin directory
• The /usr/lib directory for IBM Spectrum Protect libraries
3. Ensure that every user of the backup-archive client sets the DSM_DIR environment variable to the
newly installed directory.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 11

 What to do next
After the installation completes, see Chapter 2, “Configure the IBM Spectrum Protect client,” on page
49 for required and optional tasks to complete before you use the backup-archive client.
Note:
• AIX workload partitions (WPAR) are supported as follows:
– Supported in global environments
– Supported with non-shared system WPARs
– Supported with shared system WPARs (backup-archive client logs and configuration files must be
defined to non-default locations)
– No support for application WPARs
– No support for image backup
– No support for backup set restore from tape
• On AIX Version 6.1, if you are using encrypted file systems (EFS) with the backup-archive client, and if
the EFS user keystore password is different from the user login password, the EFS keystore is not
automatically opened when you log on. If the EFS keystore is not open when you log on, the client might
not restore a non-EFS file into an EFS file system. You can prevent the EFS file system restore problem
one of the following ways:
– Start the backup-archive client by using the efskeymgr -o command. For example: efskeymgr -
o ./dsmj
– Synchronize the keystore password with the user login password by using the efskeymgr -n
command. For example: efskeymgr -n

Uninstalling the AIX client

You can use the following procedures to uninstall the IBM Spectrum Protect AIX backup-archive client.

Before you begin

IBM Spectrum Protect client modules and components are tightly integrated and installed file sets are
automatically committed. There is no option for rollbacks of uninstalled components.

Procedure
1. Enter the following AIX command: smitty remove.
2. Press the ENTER key.
3. In the SOFTWARE name field, press F4 to list the IBM Spectrum Protect file sets that you want to
uninstall; press the ENTER key.
4. Select the IBM Spectrum Protect file sets that you want to uninstall; press the ENTER key.
Note: The journal-based backup feature is contained in two file sets. Select both
tivoli.tsm.client.jbb.64bit and tivoli.tsm.filepath_aix. If you uninstall the file sets
one at a time, uninstall the tivoli.tsm.client.jbb.64bit file set first.
5. In the PREVIEW only? field (the remove operation does not occur), select No; press the ENTER key.

Installing the HP-UX Itanium 2 API

You can install the HP-UX Itanium 2 API from the product installation media.

About this task

The following source packages are available on the installation media:

12 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
tsmcli/hp11ia64/gskcrypt64-8.x.x.x.hpux.ia64.tar.Z and tsmcli/hp11ia64/
gskssl64-8.x.x.x.hpux.ia64.tar.Z
Contains the GSKit. If you have a previous version of the GSKit, uninstall it before you install the new
version.
tsmcli/hp11ia64/TIVsmCapi64
In this package, the software selection name that is used by swlist for the top-level product name is
TIVsm64. The component under TIVsm64 is TIVsm.CLIENT_API64.
Default installation directories
Here are the default directories where some files are stored as part of the client installation:
• The IBM Spectrum Protect API files are installed in the /opt/tivoli/tsm/client/api/bin64
directory.
• The sample system-options file, dsm.sys.smp, is placed in the installation directory.
To remove previous backup-archive client versions, log in as the root user and enter the following
command:

/usr/sbin/swremove -x mount_all_filesystems=false -v TIVsm64

If you installed additional languages in a Version 7.1.2 or earlier client, run the following command to
remove them:

/usr/sbin/swremove -x mount_all_filesystems=false -v TIVsm64.CLIENT_msg_lang

Replace lang with the appropriate language code from Table 10 on page 13.

Table 10. HP-UX Itanium 2 client: Language codes for installation packages
Language Language code
Simplified Chinese ZH_CN
Traditional Chinese ZH_TW
Czech CS_CZ
French FR_FR
German DE_DE
Hungarian HU_HU
Italian IT_IT
Japanese JA_JP
Korean KO_KR
Polish PL_PL
Brazilian Portuguese PT_BR
Russian RU_RU
Spanish ES_ES

This installation procedure can be used to install new distributions or updates from downloaded
installation media. The downloaded files that you use to install the client might be compressed.
Depending on the package file format, either copy or extract the files to disk and use these instructions to
install the components.
You can download the appropriate package file from one of the following websites:
• Download the client package from Passport Advantage or Fix Central.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 13

 • For the latest information, updates, and maintenance fixes, go to the IBM Support Portal.

Procedure
1. Log in as the root user.
2. Mount the volume that you are installing from.
3. To install GSKit: If you have a previous version of GSKit installed, remove it before you install the new
version. Extract the contents of gskcrypt64-8.x.x.x.hpux.ia64.tar.Z and
gskssl64-8.x.x.x.hpux.ia64.tar.Z to a directory on your hard disk. Enter the following
commands to install the packages:

/usr/sbin/swinstall -x mount_all_filesystems=false -v -s `pwd`

/gskcrypt64 gskcrypt64
/usr/sbin/swinstall -x mount_all_filesystems=false -v -s `pwd`
/gskssl64 gskssl64
4. If you downloaded from FTP, go to the directory where the installable image is located. Enter the
following command:
/usr/sbin/swinstall -x mount_all_filesystems=false -v -s `pwd`/TIVsmCapi64
TIVsm64
`pwd` can be used instead of the absolute name of the current directory.
Related concepts
“Configure the IBM Spectrum Protect client” on page 49
After installing the backup-archive client, you must configure it before performing any operations.

Increasing the default limit of the data segment size

The default limit of the data segment size of a process in HP-UX 11i v2 is 64 MB. When backing up large
file systems, the API might exceed this limit and run out of memory.
To increase this limit you can modify the kernel as follows:
1. As root user, start sam.
2. Select Kernel Configuration.
3. Select Configurable Parameters.
4. Locate maxdsize and increase its value through the menu entry Actions/Modify Configurable
Parameter... (e.g. set maxdsize to 268435456 for a 256 MB max size of the data segment.
5. The kernel is rebuilt by sam after this change. You must reboot for the new setting to take effect.

Uninstalling the HP-UX Itanium 2 API

You can use the following procedures to uninstall the IBM Spectrum Protect HP-UX Itanium 2 API.

Before you begin

Important: Make sure that you uninstall the packages in the order shown.

Procedure
1. To remove the CLIENT_API file set, enter the following command:
/usr/sbin/swremove -x mount_all_filesystems=false -v TIVsm64
2. To remove the Global Security Kit (GSKit), enter the following commands:

/usr/sbin/swremove -x mount_all_filesystems=false gskssl64

/usr/sbin/swremoveswremove -x mount_all_filesystems=false gskcrypt64

14 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 What to do next
After you uninstall the HP-UX API, several empty directories remain in the file system, such as the
following directories:
• The license directory (/opt/tivoli/tsm/license)
• One or more language directories (/opt/tivoli/tsm/client/ba/bin/xx_XX), where xx_XX
represents one of the following language codes: cs_CZ, de_DE, es_ES, it_IT, fr_FR, hu_HU,
ja_JP, ko_KR, pl_PL, pt_BR, ru_RU, zh_CN and zh_TW
• /opt/tivoli/tsm/client/ba/bin/cit
• /opt/tivoli/tsm/client/ba/bin/images
• /opt/tivoli/tsm/client/ba/bin/plugin
If you want to remove these empty directories, you can manually remove them.

Installing the backup-archive client on Linux on Power Systems (Little Endian)

You can install the backup-archive client from the product installation media.

Before you begin

• You must be logged in as root user to install the product.
• If you plan to install the client on the same system as the IBM Spectrum Protect server V8.1.2 or later
level, ensure that you halt the IBM Spectrum Protect server before you install the client. This action will
prevent the client installation process from forcing the system to reboot. After you install the client, you
can restart the IBM Spectrum Protect server.

About this task

The following installation options are available in uncompressed packages on the installation media.

Table 11. Package names, contents, and default directory

Package Name Contents Default directory

gskcrypt64-8.x.x.x.linux.ppcle.r 64-bit Global /usr/local/ibm/gsk8

Security Kit (GSKit)
pm
gskssl64-8.x.x.x.linux.ppcle.rpm packages

TIVsm-API64.ppc64le.rpm Application /opt/tivoli/tsm/client/api/bin64

programming
interface (API),
which contains the
shared libraries and
samples for the IBM
Spectrum Protect
API.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 15

Table 11. Package names, contents, and default directory (continued)
Package Name Contents Default directory
TIVsm-BA.ppc64le.rpm Backup-archive /opt/tivoli/tsm/client/ba/bin
client (command-
This directory is typically the default
line and GUI),
installation directory for many backup-
administrative client
archive client files. The sample system-
(dsmadmc), and the
options file (dsm.sys.smp) is written to
web client.
this directory. If you do not set the
DSM_DIR environment variable, the dsmc
executable file, the resource files, and the
dsm.sys file are stored in this directory.
If you do not set the DSM_CONFIG
environment variable, the client user-
options file must be in this directory.
If you do not set the DSM_LOG
environment variable, the backup-archive
client writes messages to the
dsmerror.log and dsmsched.log files
in the current working directory.

TIVsm-APIcit.ppc64le.rpm These files provide APIcit is installed in /opt/tivoli/tsm/

the Common client/api/bin64/cit
TIVsm-BAcit.ppc64le.rpm
Inventory
BAcit is installed in /opt/tivoli/tsm/
Technology
client/ba/bin/cit
components that
you can use to
obtain information
about the number of
client and server
devices that are
connected to the
system, and the
utilization of
processor value
units (PVUs) by
server devices.
These files are
optional. For more
information about
PVUs, see
Estimating
processor value
units in the IBM
Spectrum Protect
server
documentation.

TIVsm-filepath-source.tar.gz Files that are Filepath is installed in /opt/filepath

needed for journal-
TIVsm-JBB.ppc64le.rpm based backups. The TIVsm-JBB.ppc64le.rpm package
is installed in /opt/tivoli/tsm/
client/ba/bin.

16 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 11. Package names, contents, and default directory (continued)
Package Name Contents Default directory
TIVsm-WEBGUI.ppc64le.rpm Provides the files /opt/tivoli/tsm/tdpvmware
that are required to
perform file-restore
operations by using
the web user
interface.

This installation procedure can be used to install new distributions or updates from downloaded
installation media. The downloaded files that you use to install the client might be compressed.
Depending on the package file format, either copy or extract the files to disk and use these instructions to
install the components.
You can download the appropriate package file from one of the following websites:
• Download the client package from Passport Advantage or Fix Central.
• For the latest information, updates, and maintenance fixes, go to the IBM Support Portal.
Before installation, you must first check the signature of the client package as follows:
1. Download the generated gpk key RPM-GPG-KEY-ibmpkg from the download sites that also contain
the client packages.
2. Import the generated gpk key by entering the following command:

rpm --import RPM-GPG-KEY-ibmpkg

3. Verify the client package by entering the following command:

rpm -K <client_package>.rpm

where <client_package> is the name of an rpm package that is listed in Table 1 - Package names,
contents, and default directory.

Procedure
1. Mount the volume that you are installing the packages from.
2. Change to the directory where the installation packages are stored.
3. Install the 64-bit GSKit packages. In the following command example, the "8.x.x.x" characters
represent the GSKit version:

rpm -U gskcrypt64-8.x.x.x.linux.ppcle.rpm gskssl64-8.x.x.x.linux.ppcle.rpm

4. Install the IBM Spectrum Protect API, and optionally install the Common Inventory Technology
package that is necessary to support processor value unit (PVU) calculations.
a) Required: Install the API:

rpm -ivh TIVsm-API64.ppc64le.rpm

b) Optional: Install the Common Inventory Technology package that is used by the API. This package
depends on the API so it must be installed after the API package is installed.

rpm -ivh TIVsm-APIcit.ppc64le.rpm

Tip: If you are upgrading the API and the Common Inventory Technology package was previously
installed, you must upgrade both the API and Common Inventory Technology packages. For example,
you can run the following command:

rpm -U TIVsm-API64.ppc64le.rpm TIVsm-APIcit.ppc64le.rpm

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 17

 If you need only the API installed, you can stop here. The rest of the steps in this procedure describe
how to install the backup-archive client components and an optional client package that is needed
only if you want the client to send PVU metrics to the server. Also described in subsequent steps are
the installation of the packages that are needed if you want to perform journal-based backups.
5. Install the backup-archive client, and optionally install the Common Inventory Technology package
that is necessary to support processor value unit (PVU) calculations.
a) Install the backup-archive client components.

rpm -ivh TIVsm-BA.ppc64le.rpm

b) Optional: Install the Common Inventory Technology package the client uses to send PVU metrics to
the server. This package depends on the client package so it must be installed after the client
package is installed.

rpm -ivh TIVsm-BAcit.ppc64le.rpm

6. Optional: If you want to use journal-based backups, install the packages that are needed for the
filepath component and journal-based backups.
a) Extract TIVsm-filepath-source.tar.gz and see the README file for compile and install
instructions.
The filepath kernel module is licensed pursuant to the terms of the GNU General Public License
("GPL").
Occasionally, build problems can occur due to the dynamic nature of the Linux kernel. If the source
does not build correctly on your Linux distribution, send an email to tsmosreq@us.ibm.com to
request the latest source file. Include the version of the Linux distribution and the output of the
uname -a command along with the version of the IBM Spectrum Protect client that you are
installing.
b) Install the journal-based backup package:

rpm -ivh TIVsm-JBB.ppc64le.rpm

7. Install the files required to perform file-restore operations by using the web user interface by entering
the following command:

rpm -ivh TIVsm-WEBGUI.ppc64le.rpm

Related concepts
“Configure the IBM Spectrum Protect client” on page 49
After installing the backup-archive client, you must configure it before performing any operations.

Uninstalling the backup-archive client on Linux on Power Systems (Little Endian)

You can uninstall the IBM Spectrum Protect client on Linux on Power Systems (Little Endian).

Before you begin

You must be logged in as root user to uninstall the product. You must uninstall the packages in the order
that is shown, otherwise the uninstallation fails.

Procedure
To uninstall the backup-archive client, enter the following commands to remove the packages for journal-
based backup, the filepath component, the backup-archive client, the API, and the IBM Global Security
Kit (GSKit).
Tip: The version number of the packages is not required.
1. To uninstall the journal-based backup components only, remove both packages (journal-based
backup and filepath). The TIVsm-JBB package is dependent on the filepath package. If you use two

18 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 separate rpm -e commands to uninstall the components one at a time, uninstall the TIVsm-JBB
package first.

rpm -e TIVsm-JBB TIVsm-filepath

2. To remove the package that performs file-restore operations by using the web user interface, enter the
following command:

rpm -e TIVsm-WEBGUI

3. Uninstall the backup-archive client package:

rpm -e TIVsm-BA

4. Uninstall the backup-archive client packages:

a) If you installed the client common inventory package (TIVsmBAcit), uninstall it:

rpm -e TIVsm-BAcit

b) Uninstall the backup-archive client package:

rpm -e TIVsm-BA

5. Uninstall products that are dependent on the API, such as IBM Spectrum Protect for Databases and
IBM Spectrum Protect for Mail. Any API-dependent products must be uninstalled before you uninstall
the API package. If you uninstall an API-dependent product, you must reinstall it after you install a
newer version of the backup-archive client and API packages. Follow the instructions of the API-
dependent products to determine what you need to do to prevent data loss when you uninstall and
reinstall the products.
6. Uninstall the API package by using the following command:

rpm -e TIVsm-API64

7. Uninstall the API packages:

a) If you installed the API common inventory package (TIVsm-APIcit), uninstall it:

rpm -e TIVsm-APIcit

b) Uninstall the API package by using the following command:

rpm -e TIVsm-API64

8. Uninstall GSKit by entering the following command:

rpm -e gskcrypt64 gskssl64

Related tasks
“Installing the backup-archive client on Linux on Power Systems (Little Endian)” on page 15
You can install the backup-archive client from the product installation media.

Installing the backup-archive client on Ubuntu Linux on Power Systems (Little Endian)
You can install the backup-archive client from the product installation media.

Before you begin

You must be logged in as the root user to install the product.
If you plan to install the client on the same system as the IBM Spectrum Protect server V8.1.2 or later
level, ensure that you halt the IBM Spectrum Protect server before you install the client. This action will
prevent the client installation process from forcing the system to reboot. After you install the client, you
can restart the IBM Spectrum Protect server.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 19

 This installation procedure can be used to install new distributions or updates from downloaded
installation media. The downloaded files that you use to install the client might be compressed.
Depending on the package file format, either copy or extract the files to disk and use these instructions to
install the components.
You can download the appropriate package file from one of the following websites:
• Download the client package from Passport Advantage or Fix Central.
• For the latest information, updates, and maintenance fixes, go to the IBM Support Portal.

About this task

The following installation packages are available on the installation media.

Table 12. Package names, contents, and default directory

Package Name Contents Default directory
64-bit Global /usr/local/ibm/gsk8
gskcrypt64_8.x.x.x.ppc64el.deb
Security Kit (GSKit)
gskssl64_8.x.x.x.ppc64el.deb packages

tivsm-api64.ppc64el.deb Application /opt/tivoli/tsm/client/api/bin64

programming
interface (API),
which contains the
shared library and
samples for the IBM
Spectrum Protect
API.
tivsm-ba.ppc64el.deb Backup-archive /opt/tivoli/tsm/client/ba/bin
client (command-
This directory is typically the default
line and GUI),
installation directory for many backup-
administrative client
archive client files. The sample system-
(dsmadmc), and the
options file (dsm.sys.smp) is written to
web client.
this directory.
If you do not set the DSM_DIR
environment variable, the dsmc executable
file, the resource files, and the dsm.sys
file are stored in this directory.
If you do not set the DSM_CONFIG
environment variable, the client user-
options file must be in this directory.
If you do not set the DSM_LOG
environment variable, the backup-archive
writes messages to the dsmerror.log
and dsmsched.log files in the current
working directory.

20 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 12. Package names, contents, and default directory (continued)
Package Name Contents Default directory

tivsm-apicit.ppc64el.deb Optional. These files APIcit is installed in /opt/tivoli/tsm/

provide the Common client/api/bin64/cit
tivsm-bacit.ppc64el.deb
Inventory
BAcit is installed in /opt/tivoli/tsm/
Technology
client/ba/bin/cit
components that
you can use to
obtain information
about the number of
client and server
devices that are
connected to the
system, and the
utilization of
processor value
units (PVUs) by
server devices. For
more information
about PVUs, see
Estimating
processor value
units in the IBM
Spectrum Protect
server
documentation.

TIVsm-filepath-source.tar.gz Files that are The TIVsm-filepath-source.tar.gz

required for journal- package is installed in the /opt/
tivsm-jbb.ppc64el.deb based backups. filepath directory.
The tivsm-jbb.ppc64el.rpm package
is installed in the /opt/tivoli/tsm/
client/ba/bin directory.

Procedure
1. Mount the volume that you are installing the packages from.
2. Change to the directory where the installation packages are stored.
3. Install the 64-bit GSKit packages. In the following command example, the "8.x.x.x" characters
represent the GSKit version:

dpkg -i gskcrypt64_8.x.x.x.ppc64el.deb gskssl64_8.x.x.x.ppc64el.deb

4. Install the IBM Spectrum Protect API, and optionally install the Common Inventory Technology
package that is necessary to support processor value unit (PVU) calculations.
a) Required: Install the API:

dpkg -i tivsm-api64.ppc64el.deb

b) Optional: Install the Common Inventory Technology package that is used by the API. This package
depends on the API so it must be installed after the API package is installed.

dpkg -i tivsm-apicit.ppc64el.deb

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 21

 Tip: If you are upgrading the API and the Common Inventory Technology package was previously
installed, you must upgrade both the API and Common Inventory Technology packages. For example,
you can run the following command:

dpkg -i tivsm-api64.ppc64el.deb
tivsm-apicit.ppc64el.deb

If you need only the API installed, you can stop here. The rest of the steps in this procedure describe
how to install the backup-archive client components and an optional client package that is needed
only if you want the client to send PVU metrics to the server. Also described in subsequent steps are
the installation of the packages that are needed if you want to perform journal-based backups.
5. Install the backup-archive client:

dpkg -i tivsm-ba.ppc64el.deb

6. Optional: If you want to use journal-based backups, install the following packages:
a) Extract TIVsm-filepath-source.tar.gz and review the README file for instructions about how
to compile and install the software. The Linux Filepath kernel module is licensed pursuant to the
terms of the GNU General Public License ("GPL").
Occasionally, build problems can occur due to the dynamic nature of the Linux kernel. If the source
does not build correctly on your Linux distribution, send an email to tsmosreq@us.ibm.com to
request the latest source file. Include the version of the Linux distribution and the output of the
uname -a command along with the version of the IBM Spectrum Protect client that you are
installing.
b) Install the journal-based backup package:

dpkg -i tivsm-jbb.ppc64el.deb

Related concepts
“Configure the IBM Spectrum Protect client” on page 49
After installing the backup-archive client, you must configure it before performing any operations.

Uninstalling the client on Ubuntu Linux on Power Systems (Little Endian)

You can uninstall the IBM Spectrum Protect backup-archive client on Ubuntu Linux on Power Systems
(Little Endian).

Before you begin

You must be logged in as the root user to uninstall the product.
Requirement: You must uninstall the packages in the order that is shown, otherwise the uninstallation
fails.

Procedure
To uninstall the backup-archive client, enter the following commands to remove the packages for journal-
based backup, the backup-archive client, the API, and the IBM Global Security Kit (GSKit). Instructions for
uninstalling the filepath component are provided with the source code for filepath, when you obtain the
software from IBM.
Tip: The version number of the packages is not required.
1. To uninstall only the journal-based backup components, remove both the tivsm-jbb and filepath
packages. The tivsm-jbb package depends on the filepath package. Uninstall the tivsm-jbb
package first.
a) dpkg -r tivsm-jbb
b) dpkg -r TIVsm-filepath
2. Uninstall the backup-archive client package:

22 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 dpkg -r tivsm-ba

3. Uninstall any products that depend on the API, such as IBM Spectrum Protect for Databases and IBM
Spectrum Protect for Mail.
If you uninstall an API-dependent product, you must reinstall it after you install a newer version of the
backup-archive client and API packages. Follow the instructions of the API-dependent products to
determine what you need to do to prevent data loss when you uninstall and reinstall the products.
4. Uninstall the API package by issuing the following command:

dpkg -r tivsm-api64

5. Remove the GSKit packages:

dpkg -r gskcrypt64 gskssl64

Related tasks
“Installing the backup-archive client on Ubuntu Linux on Power Systems (Little Endian)” on page 19
You can install the backup-archive client from the product installation media.

Installing the API on Linux on Power Systems (Big Endian)

You can install the IBM Spectrum Protect API from the product installation media.

Before you begin

• You must be logged in as root user to install the product.
• If you have IBM Spectrum Protect Version 6.2 (or an earlier version) installed, remove it (rpm -e) and
any other dependent software programs before you install a newer version.
• If you have IBM Spectrum Protect V6.3 (or newer) installed, you can use the rpm upgrade option (rpm
-U) or the rpm freshen option (rpm -F) to upgrade the existing software to a newer version. The rpm -
U command can be used to install new packages or upgrade existing packages; rpm -F can update only
packages that are already installed.
• Stop any running client processes before you uninstall or upgrade the IBM Spectrum Protect API or
backup-archive client.
• If you are running a V7.1.2 or earlier client, you must uninstall any language packages before you
proceed with the upgrade.

About this task

The following installation options are available in uncompressed packages on the installation media.

Table 13. Package names, contents, and default directory

Package Name Contents Default directory

gskcrypt64-8.x.x.x.linux.ppc.rpm 64-bit Global /usr/local/ibm/gsk8

Security Kit (GSKit)
gskssl64-8.x.x.x.linux.ppc.rpm
packages
TIVsm-API64.ppc64.rpm Application /opt/tivoli/tsm/client/api/bin64
programming
interface (API),
which contains the
IBM Spectrum
Protect API shared
libraries and
samples.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 23

Table 13. Package names, contents, and default directory (continued)
Package Name Contents Default directory

TIVsm-APIcit.ppc64.rpm Optional. These files APIcit is installed in /opt/tivoli/tsm/

provide the Common client/api/bin64/cit
Inventory
Technology
components that
you can use to
obtain information
about the number of
client and server
devices that are
connected to the
system, and the
utilization of
processor value
units (PVUs) by
server devices. For
more information
about PVUs, see
Estimating
processor value
units in the IBM
Spectrum Protect
server
documentation.

This installation procedure can be used to install new distributions or updates from downloaded
installation media. The downloaded files that you use to install the client might be compressed.
Depending on the package file format, either copy or extract the files to disk and use these instructions to
install the components.
You can download the appropriate package file from one of the following websites:
• Download the client package from Passport Advantage or Fix Central.
• For the latest information, updates, and maintenance fixes, go to the IBM Support Portal.
Before installation, you must first check the signature of the client package as follows:
1. Download the generated gpk key RPM-GPG-KEY-ibmpkg from the download sites that also contain
the client packages.
2. Import the generated gpk key by entering the following command:

rpm --import RPM-GPG-KEY-ibmpkg

3. Verify the client package by entering the following command:

rpm -K <client_package>.rpm

where <client_package> is the name of an rpm package that is listed in Table 1 - Package names,
contents, and default directory.

Procedure
1. Mount the volume that you are installing from.
2. Change to the directory where the installation packages are stored.
3. Install the 64-bit GSKit packages. In this example, the "8.x.x.x" characters represent the GSKit
version:

24 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 rpm -U gskcrypt64-8.x.x.x.linux.ppc.rpm gskssl64-8.x.x.x.linux.ppc.rpm

4. Install the IBM Spectrum Protect API, and optionally install the Common Inventory Technology
package that is needed to support processor value unit (PVU) calculations.
a) Required: Install the API:

rpm -i TIVsm-API64.ppc64.rpm

b) Optional: Install the Common Inventory Technology package that is used by the API. This package
is dependent on the API so it must be installed after the API package is installed.

rpm -i TIVsm-APIcit.ppc64.rpm

Tip: If you are upgrading the API and the Common Inventory Technology package was previously
installed, you must upgrade both the API and Common Inventory Technology packages. For example,
you can run the following command:

rpm -U TIVsm-API64.ppc64.rpm TIVsm-APIcit.ppc64.rpm

Related concepts
“Configure the IBM Spectrum Protect client” on page 49
After installing the backup-archive client, you must configure it before performing any operations.

Uninstalling the API on Linux on Power Systems (Big Endian)

You can uninstall the IBM Spectrum Protect API on IBM Spectrum Protect Linux on Power Systems (Big
Endian).

Before you begin

You must be logged in as root to uninstall the product. Uninstall the packages in the order shown.

Procedure
To uninstall a previously installed IBM Spectrum Protect package, enter the following commands to
remove the packages for journal-based backup, the filepath component, the backup-archive client (if
applicable), the API, and the IBM Global Security Kit (GSKit).
Tip: The version number of the packages is not needed for uninstall.
1. Complete this step if a version 7.1 or earlier client was installed previously.
To uninstall the journal-based backup components only, remove both packages (journal-based
backup and filepath). The TIVsm-JBB package is dependent on the filepath package. If you use two
separate rpm -e commands to uninstall the components one at a time, uninstall the TIVsm-JBB
package first.

rpm -e TIVsm-JBB TIVsm-filepath

2. If a version 7.1 or earlier client was installed previously, uninstall the backup-archive client packages.
a) If you installed the optional TIVsmBAcit package, uninstall it by using the following command:

rpm -e TIVsm-BAcit

b) Uninstall the backup-archive client package:

rpm -e TIVsm-BA

Note: If language packages are installed in a Version 7.1.2 or earlier client, you must remove them
before you remove the API package. Enter the following command, and replace xx_xx with the

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 25

 language code for each additional language that you installed. For a list of language code identifiers,
see Table 14 on page 26.

rpm -e TIVsm-BA.msg.xx_xx

Table 14. Language pack identifiers

Language Language identifier
Czech CS_CZ
French FR_FR
German DE_DE
Hungarian HU_HU
Italian IT_IT
Japanese JA_JP
Korean KO_KR
Polish PL_PL
Portuguese PT_BR
Russian RU_RU
Spanish ES_ES
Traditional Chinese (EUC) ZH_CN
Traditional Chinese Big5 ZH_TW
3. Uninstall any products that are dependent on the API, such as IBM Spectrum Protect for Databases
and IBM Spectrum Protect for Mail. Any API-dependent products must be uninstalled before you
uninstall the API package. If you uninstall an API-dependent product, you must reinstall it after you
install a newer version of the API package. Consult the documentation of the dependent product to
determine what you need to do to prevent data loss when you uninstall and reinstall the products.
4. If you installed the optional API common inventory package (TIVsm-APIcit), use the following
command to uninstall the package:

rpm -e TIVsm-APIcit

5. Uninstall the API package by using the following command:

rpm -e TIVsm-API64

6. Uninstall GSKit by using the following command:

rpm -e gskcrypt64 gskssl64

Related tasks
“Installing the API on Linux on Power Systems (Big Endian)” on page 23
You can install the IBM Spectrum Protect API from the product installation media.

Installing the Linux x86_64 client

You can install the Linux x86_64 backup-archive client from the product installation media.

Before you begin

• You must be logged in as root to install the product.
• If you plan to install the client on the same system as the IBM Spectrum Protect server V8.1.2 or later
level, ensure that you halt the IBM Spectrum Protect server before you install the client. This action will

26 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 prevent the client installation process from forcing the system to reboot. After you install the client, you
can restart the IBM Spectrum Protect server.
• If you have IBM Spectrum Protect Version 6.2 (or an earlier version) installed, remove it (rpm -e) and
any other dependent software programs before you install a newer version.
• If you have IBM Spectrum Protect V6.3 (or later) installed, you can use the rpm upgrade option (rpm -
U) or the rpm freshen option (rpm -F) to upgrade the existing software to a newer version. The rpm -U
command can be used to install new packages or upgrade existing packages only if you did not
previously install any language packages. The rpm -F command can update only packages that are
already installed.
• Stop any running client processes before you uninstall or upgrade the IBM Spectrum Protect API or
backup-archive client.
• If any language packages are installed, you must uninstall them before you install or upgrade the IBM
Spectrum Protect API or backup-archive client.

About this task

The following installation options are available in uncompressed packages on the installation media.

Table 15. Package names, contents, and default directory

Package Name Contents Default directory

gskcrypt64-8.x.x.x.linux.x86_64. 64-bit Global /usr/local/ibm/gsk8

Security Kit (GSKit)
rpm
gskssl64-8.x.x.x.linux.x86_64.rp packages
m

TIVsm-API64.x86_64.rpm Application /opt/tivoli/tsm/client/api/bin64

programming
interface (API),
which contains the
IBM Spectrum
Protect API shared
libraries and
samples.
TIVsm-BA.x86_64.rpm Backup-archive /opt/tivoli/tsm/client/ba/bin
client (command-
This directory is considered to be the
line and GUI),
default installation directory for many
administrative client
backup-archive client files. The sample
(dsmadmc), and the
system-options file (dsm.sys.smp) is
web client.
written to this directory. If the DSM_DIR
environment variable is not set, the dsmc
executable file, the resource files, and the
dsm.sys file are stored in this directory.
If DSM_CONFIG is not set, the client user-
options file must be in this directory.
If you do not define DSM_LOG, writes
messages to the dsmerror.log and
dsmsched.log files in the current working
directory.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 27

Table 15. Package names, contents, and default directory (continued)
Package Name Contents Default directory

TIVsm-APIcit.x86_64.rpm Optional. These files APIcit is installed in /opt/tivoli/tsm/

provide the Common client/api/bin64/cit/
TIVsm-BAcit.x86_64.rpm
Inventory
BAcit is installed in /opt/tivoli/tsm/
Technology
client/ba/bin/cit/
components that
you can use to
obtain information
about the number of
client and server
devices that are
connected to the
system, and the
utilization of
processor value
units (PVUs) by
server devices. For
more information
about PVUs, see
Estimating
processor value
units in the IBM
Spectrum Protect
server
documentation.

TIVsm-filepath-source.tar.gz Files needed to Filepath is installed in /opt/filepath

support journal-
TIVsm-JBB.x86_64.rpm based backups. JBB is installed in /opt/tivoli/tsm/
client/ba/bin

TIVsm_BAhdw.x86_64.rpm Provides support for /opt/tivoli/tsm/client/ba/bin/

snapshot plugins
incremental backup
for NetAPP and N-
Series file servers.
TIVsm-WEBGUI.x86_64.rpm Provides the files /opt/tivoli/tsm/tdpvmware
required to perform
file-restore
operations by using
the web user
interface.

This installation procedure can be used to install new distributions or updates from downloaded
installation media. The downloaded files that you use to install the client might be compressed.
Depending on the package file format, either copy or extract the files to disk and use these instructions to
install the components.
You can download the appropriate package file from one of the following websites:
• Download the client package from Passport Advantage or Fix Central.
• For the latest information, updates, and maintenance fixes, go to the IBM Support Portal.
Before installation, you must first check the signature of the client package as follows:

28 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
1. Download the generated gpk key RPM-GPG-KEY-ibmpkg from the download sites that also contain
the client packages.
2. Import the generated gpk key by entering the following command:

rpm --import RPM-GPG-KEY-ibmpkg

3. Verify the client package by entering the following command:

rpm -K <client_package>.rpm

where <client_package> is the name of an rpm package that is listed in Table 1 - Package names,
contents, and default directory.

Procedure
To install the Linux x86_64 backup-archive client, complete the following steps:
1. Mount the volume that you are installing from.
2. Change to the directory where the installation packages are stored.
3. Install the 64-bit GSKit packages. In this example, the "8.x.x.x" characters represent the GSKit
version:

rpm -U gskcrypt64-8.x.x.x.linux.x86_64.rpm gskssl64-8.x.x.x.linux.x86_64.rpm

4. Install the IBM Spectrum Protect API, and optionally install the Common Inventory Technology
package that is necessary to support processor value unit (PVU) calculations.
a) Required: Install the API:

rpm -i TIVsm-API64.x86_64.rpm

b) Optional: Install the Common Inventory Technology package that is used by the API. This package
depends on the API so it must be installed after the API package is installed.

rpm -i TIVsm-APIcit.x86_64.rpm

Tip: If you are upgrading the API and the Common Inventory Technology package was previously
installed, you must upgrade both the API and Common Inventory Technology packages. For example,
you can run the following command:

rpm -U TIVsm-API64.x86_64.rpm TIVsm-APIcit.x86_64.rpm

If you need only the API installed, you can stop here. The rest of the steps in this procedure describe
how to install the backup-archive client components and an optional client package that is needed
only if you want the client to send PVU metrics to the server. Also described in subsequent steps are
the installation of the packages that are needed if you want to perform journal-based backups.
5. Install the backup-archive client, and optionally install the Common Inventory Technology package
that is necessary to support processor value unit (PVU) calculations.
a) Install the backup-archive client components.

rpm -i TIVsm-BA.x86_64.rpm

b) Optional: Install the Common Inventory Technology package the client uses to send PVU metrics to
the server. This package depends on the client package so it must be installed after the client
package is installed.

rpm -i TIVsm-BAcit.x86_64.rpm

6. Optional: If you want to use journal-based backups, you must compile and install the filepath
component that matches the Linux kernel on your client computer. Extract TIVsm-filepath-
source.tar.gz and see the README file for compile and install instructions. The Linux filepath
kernel module is licensed pursuant to the terms of the GNU General Public License ("GPL").

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 29

 Occasionally, build problems can occur due to the dynamic nature of the Linux kernel. If the source
does not build correctly on your Linux distribution, send an email to tsmosreq@us.ibm.com to request
the latest source file. Include the version of the Linux distribution and the output of the uname -a
command along with the version of the IBM Spectrum Protect client that you are installing.
7. Install the snapshot difference incremental backup support for NetApp and N-Series file servers by
entering the following command:

rpm -i TIVsm-BAhdw.x86_64.rpm

8. Install the files required to perform file-restore operations by using the web user interface by entering
the following command:

rpm -ivh TIVsm-WEBGUI.x86_64.rpm

Related concepts
“Configure the IBM Spectrum Protect client” on page 49
After installing the backup-archive client, you must configure it before performing any operations.

Uninstalling the Linux x86_64 client

You can use the following procedure to uninstall the IBM Spectrum Protect Linux x86_64 client.

Before you begin

You must be logged in as root to uninstall the product. Uninstall the packages in the order shown.

Procedure
To uninstall a previously installed IBM Spectrum Protect client package, enter the following commands to
remove the packages for the web user interface, journal-based backup, the filepath component, the
backup-archive client, the API, and the IBM Global Security Kit (GSKit).
Tip: The version number of the packages is not needed for uninstall.
1. To uninstall the journal-based backup components only, remove both packages (journal-based
backup and filepath). The TIVsm-JBB package depends on the filepath package. If you use two
separate rpm -e commands to uninstall the components one at a time, uninstall the TIVsm-JBB
package first.

rpm -e TIVsm-JBB TIVsm-filepath

2. To remove the package that performs file-restore operations by using the web user interface, enter the
following command:

rpm -e TIVsm-WEBGUI

3. Uninstall the backup-archive client packages:

a) If you installed the optional TIVsm-BAcit package, uninstall it before you uninstall the client:

rpm -e TIVsm-BAcit

b) Uninstall the backup-archive client.

rpm -e TIVsm-BA

Note: If language packages are installed in a Version 7.1.2 or earlier client, you must remove them
before you remove the API package. Enter the following command, and replace xx_xx with the
language code for each additional language that you installed. For a list of language code identifiers,
see Table 16 on page 31.

rpm -e TIVsm-msg.xx_xx

30 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 16. Language pack identifiers
Language Language identifier
Czech CS_CZ
French FR_FR
German DE_DE
Hungarian HU_HU
Italian IT_IT
Japanese JA_JP
Korean KO_KR
Polish PL_PL
Portuguese PT_BR
Russian RU_RU
Spanish ES_ES
Traditional Chinese (EUC) ZH_CN
Traditional Chinese Big5 ZH_TW
4. Uninstall any products that depend on the API, such as IBM Spectrum Protect for Databases and IBM
Spectrum Protect for Mail. Any API-dependent products must be uninstalled before you uninstall the
API package. If you uninstall an API-dependent product, you must reinstall it after you install a newer
version of the backup-archive client and API packages. Consult the documentation of the dependent
product to determine what you need to do to prevent data loss when you uninstall and reinstall the
products.
a) If you installed the optional API common inventory package (TIVsm-APIcit), uninstall it before
you uninstall the API package. Use the following command to uninstall the package:

rpm -e TIVsm-APIcit

b) Uninstall the API package by using the following command:

rpm -e TIVsm-API64

5. To remove the GSKit 64-bit package, enter the following command:

rpm -e gskcrypt64 gskssl64

Related tasks
“Installing the Linux x86_64 client” on page 26
You can install the Linux x86_64 backup-archive client from the product installation media.

Installing the Ubuntu Linux x86_64 client

You can install the Ubuntu Linux 64-bit backup-archive client from the product installation media.

Before you begin

If you plan to install the client on the same system as the IBM Spectrum Protect server V8.1.2 or later
level, ensure that you halt the IBM Spectrum Protect server before you install the client. This action will
prevent the client installation process from forcing the system to reboot. After you install the client, you
can restart the IBM Spectrum Protect server.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 31

 About this task
The following installation options are available in uncompressed packages on the installation media.

Table 17. Package names, contents, and default directory

Package Name Contents Default directory

gskcrypt64_8.0-50.40.linux.x86_6 64-bit Global /usr/local/ibm/gsk8

Security Kit (GSKit)
4.deb
packages
gskssl64_8.0-50.40.linux.x86_64.
deb

tivsm-api64.amd64.deb Application /opt/tivoli/tsm/client/api/bin64

programming
interface (API),
which contains the
IBM Spectrum
Protect API shared
libraries and
samples.
tivsm-ba.amd64.deb Backup-archive /opt/tivoli/tsm/client/ba/bin
client (command-
This directory is considered to be the
line and GUI),
default installation directory for many
administrative client
backup-archive client files. The sample
(dsmadmc), and the
system-options file (dsm.sys.smp) is
web client.
written to this directory. If the DSM_DIR
environment variable is not set, the dsmc
executable file, the resource files, and the
dsm.sys file are stored in this directory.
If DSM_CONFIG is not set, the client user-
options file must be in this directory.
If you do not define DSM_LOG, writes
messages to the dsmerror.log and
dsmsched.log files in the current working
directory.

32 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 17. Package names, contents, and default directory (continued)
Package Name Contents Default directory

tivsm-apicit.amd64.deb Optional. These files APIcit is installed in /opt/tivoli/tsm/

provide the Common client/api/bin64/cit
tivsm-bacit.amd64.deb
Inventory
BAcit is installed in /opt/tivoli/tsm/
Technology
client/ba/bin/cit
components that
you can use to
obtain information
about the number of
client and server
devices that are
connected to the
system, and the
utilization of
processor value
units (PVUs) by
server devices. For
more information
about PVUs, see
Estimating
processor value
units in the IBM
Spectrum Protect
server
documentation.

tivsm-filepath-source.tar.gz Files needed to The filepath and tivsm-jbb packages

support journal- are only required if you plan to use journal-
tivsm-jbb.amd64.deb based backups. based backups.
The tivsm-jbb.x86_64.deb package is
installed in /opt/tivoli/tsm/
client/ba/bin.

tivsm-bahdw.amd64.deb Provides support for /opt/tivoli/tsm/client/ba/bin/

snapshot plugins
incremental backup
for NetAPP and N-
Series file servers.

This installation procedure can be used to install new distributions or updates from downloaded
installation media. The downloaded files that you use to install the client might be compressed.
Depending on the package file format, either copy or extract the files to disk and use these instructions to
install the components.
You can download the appropriate package file from one of the following websites:
• Download the client package from Passport Advantage or Fix Central.
• For the latest information, updates, and maintenance fixes, go to the IBM Support Portal.

Procedure
To install the Ubuntu Linux x86_64 backup-archive client, complete the following steps.
1. Mount the volume that you are installing from.
2. Change to the directory where the installation packages are stored.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 33

 3. Install the 64-bit GSKit packages.

sudo dpkg -i gskcrypt64_8.0-50.40.linux.x86_64.deb

gskssl64_8.0-50.40.linux.x86_64.deb

4. Install the IBM Spectrum Protect API, and optionally install the Common Inventory Technology
package that is necessary to support processor value unit (PVU) calculations.
a) Required: Install the API:

sudo dpkg -i tivsm-api64.amd64.deb

b) Optional: Install the Common Inventory Technology package that is used by the API. This package
depends on the API so it must be installed after the API package is installed.

sudo dpkg -i tivsm-apicit.amd64.deb

Tip: If you are upgrading the API and the Common Inventory Technology package was previously
installed, you must upgrade both the API and Common Inventory Technology packages. For example,
you can run the following command:

sudo dpkg -i tivsm-api64.amd64.deb

tivsm-apicit.amd64.deb

If you need only the API installed, you can stop here. The rest of the steps in this procedure describe
how to install the backup-archive client components and an optional client package that is needed
only if you want the client to send PVU metrics to the server. Also described in subsequent steps are
the installation of the packages that are needed if you want to perform journal-based backups.
5. Install the backup-archive client, and optionally install the Common Inventory Technology package
that is necessary to support processor value unit (PVU) calculations.
a) Install the backup-archive client components.

sudo dpkg -i tivsm-ba.amd64.deb

b) Optional: Install the Common Inventory Technology package that the client uses to send PVU
metrics to the server. This package depends on the client package so it must be installed after the
client package is installed.

sudo dpkg -i tivsm-bacit.amd64.deb

6. Optional: Complete this step only if you plan to use journal-based backups.
a) Extract tivsm-filepath-source.tar.gz and see the README file for compile and install
instructions.
The filepath kernel module is licensed pursuant to the terms of the GNU General Public License
("GPL").
Occasionally, build problems can occur due to the dynamic nature of the Linux kernel. If the source
does not build correctly on your Linux distribution, send an email to tsmosreq@us.ibm.com to
request the latest source file. Include the version of the Linux distribution and the output of the
uname -a command along with the version of the IBM Spectrum Protect client that you are
installing.
b) Install the journal-based backup package: dpkg -i tivsm-jbb.amd64.deb.
7. Install the snapshot difference incremental backup support for NetApp and N-Series file servers by
entering the following command:

sudo dpkg -i tivsm-bahdw.amd64.deb

Related concepts
“Configure the IBM Spectrum Protect client” on page 49

34 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 After installing the backup-archive client, you must configure it before performing any operations.

Uninstalling the Ubuntu Linux x86_64 client

Use the following procedure to uninstall the IBM Spectrum Protect Ubuntu Linux 64-bit client.

Procedure
To uninstall a previously installed IBM Spectrum Protect client package, enter the following commands to
remove the packages for journal-based backup, the backup-archive client, the API, and the IBM Global
Security Kit (GSKit). Instructions to uninstall the filepath component are provided with the source code
for filepath, when you obtain the software from IBM.
1. To uninstall only the journal-based backup components, remove both the tivsm-jbb and the filepath
component. The tivsm-jbb package depends on the filepath package. Uninstall the tivsm-jbb
package first.
a. sudo dpkg -r tivsm-jbb
b. sudo dpkg -r tivsm-filepath
2. Uninstall the backup-archive client packages:
a) If you installed the optional tivsm-bacit package, uninstall it before you uninstall the client:

sudo dpkg -r tivsm-bacit

b) Uninstall the backup-archive client.

sudo dpkg -r tivsm-ba

Note: If language packages are installed in a Version 7.1.2 or earlier client, you must remove them
before you remove the API package. Enter the following command, and replace xx-xx with the
language code for each additional language that you installed. For a list of language code identifiers,
see Table 18 on page 35.

dpkg -r tivsm-msg.xx-xx

Table 18. Language pack identifiers

Language Language identifier
Czech cs-cz
French fr-fr
German de-de
Hungarian hu-hu
Italian it-it
Japanese ja-jp
Korean ko-kr
Polish pl-pl
Portuguese pt-br
Russian ru-ru
Spanish es-es
Traditional Chinese (EUC) zh-cn
Traditional Chinese Big5 zh-tw

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 35

 3. Uninstall any products that depend on the API, such as IBM Spectrum Protect Data Protection
products. Any API-dependent products must be uninstalled before you uninstall the API package. If
you uninstall an API-dependent product, you must reinstall it after you install a newer version of the
backup-archive client and API packages. Consult the documentation of the dependent product to
determine what you need to do to prevent data loss when you uninstall and reinstall the products.
a) If you installed the optional API common inventory package (tivsm-apicit), uninstall it before
you uninstall the API package. Use the following command to uninstall the package:

sudo dpkg -r tivsm-apicit

b) Uninstall the API package by using the following command:

sudo dpkg -r tivsm-api64

4. To remove the GSKit 64-bit packages, enter the following command:

sudo dpkg -r gskcrypt64 gskssl64

Related tasks
“Installing the Ubuntu Linux x86_64 client” on page 31
You can install the Ubuntu Linux 64-bit backup-archive client from the product installation media.

Installing the Linux on System z client

You can install the Linux on System z backup-archive client from the product installation media.

Before you begin

• You must be logged in as root to install the product.
• If you plan to install the client on the same system as the IBM Spectrum Protect server V8.1.2 or later
level, ensure that you halt the IBM Spectrum Protect server before you install the client. This action will
prevent the client installation process from forcing the system to reboot. After you install the client, you
can restart the IBM Spectrum Protect server.
• If you have IBM Spectrum Protect Version 6.2 (or an earlier version) installed, remove it (rpm -e) and
any other dependent software programs before you install a newer version.
• If you have IBM Spectrum Protect V6.3 (or newer) installed, you can use the rpm upgrade option (rpm
-U) or the rpm freshen option (rpm -F) to upgrade the existing software to a newer version. The rpm -
U command can be used to install new packages or upgrade existing packages; rpm -F can update only
packages that are already installed.
• Stop any running client processes before you uninstall or upgrade the IBM Spectrum Protect API or
backup-archive client.
• If you are running a V7.1.2 or earlier client, you must uninstall any language packages before you
proceed with the upgrade.

About this task

The following installation options are available in uncompressed packages on the installation media.

Table 19. Package names, contents, and default directory

Package Name Contents Default directory
64-bit Global Security Kit (GSKit) /usr/local/ibm/gsk8
gskcrypt64-8.x.x.x.linux.s
packages
390x.rpm
gskssl64-8.x.x.x.linux.s39
0x.rpm

36 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 19. Package names, contents, and default directory (continued)
Package Name Contents Default directory
TIVsm-API64.s390x.rpm Application programming interface /opt/tivoli/tsm/
(API), which contains the IBM client/api/bin64
Spectrum Protect API shared
libraries and samples.
TIVsm-BA.s390x.rpm Backup-archive client (command- /opt/tivoli/tsm/client/ba
line and GUI), administrative client
This directory is considered to be
(dsmadmc), and the web client.
the default installation directory for
many backup-archive client files.
The sample system-options file
(dsm.sys.smp) is written to this
directory. If the DSM_DIR
environment variable is not set, the
dsmc executable file, the resource
files, and the dsm.sys file are
stored in this directory.
If DSM_CONFIG is not set, the
client user-options file must be in
this directory.
If you do not define DSM_LOG, the
backup-archive client writes
messages to the dsmerror.log
and dsmsched.log files in the
current working directory.

TIVsm-APIcit.s390x.rpm Optional. These files provide the APIcit is installed in /opt/

Common Inventory Technology tivoli/tsm/client/api/
TIVsm-BAcit.s390x.rpm
components that you can use to bin64/cit
obtain information about the
BAcit is installed in /opt/
number of client and server devices
tivoli/tsm/
that are connected to the system,
client/ba/bin/cit
and the utilization of processor
value units (PVUs) by server
devices. For more information
about PVUs, see Estimating
processor value units in the IBM
Spectrum Protect server
documentation.

TIVsm-filepath- Files needed to support journal- Filepath is installed in /opt/

source.tar.gz based backups. filepath
TIVsm-JBB.s390x.rpm JBB is installed in /opt/
tivoli/tsm/client/ba/bin

TIVsm-WEBGUI.s390x.rpm Provides the files required to /opt/tivoli/tsm/tdpvmware

perform file-restore operations by
using the web user interface.

This installation procedure can be used to install new distributions or updates from downloaded
installation media. The downloaded files that you use to install the client might be compressed.
Depending on the package file format, either copy or extract the files to disk and use these instructions to
install the components.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 37

 You can download the appropriate package file from one of the following websites:
• Download the client package from Passport Advantage or Fix Central.
• For the latest information, updates, and maintenance fixes, go to the IBM Support Portal.
Before installation, you must first check the signature of the client package as follows:
1. Download the generated gpk key RPM-GPG-KEY-ibmpkg from the download sites that also contain
the client packages.
2. Import the generated gpk key by entering the following command:

rpm --import RPM-GPG-KEY-ibmpkg

3. Verify the client package by entering the following command:

rpm -K <client_package>.rpm

where <client_package> is the name of an rpm package that is listed in Table 1 - Package names,
contents, and default directory.

Procedure
1. Mount the volume that you are installing from.
2. Change to the directory where the packages are stored.
3. Install the 64-bit GSKit packages. In this example, the "8.x.x.x" characters represent the GSKit
version:

rpm -U gskcrypt64-8.x.x.x.linux.s390x.rpm gskssl64-8.x.x.x.linux.s390x.rpm

4. Install the IBM Spectrum Protect API, and optionally install the Common Inventory Technology
package that is needed to support processor value unit (PVU) calculations.
a) Required: Install the API:

rpm -i TIVsm-API64.s390x.rpm

b) Optional: Install the Common Inventory Technology package that is used by the API. This package
is dependent on the API so it must be installed after the API package is installed.

rpm -i TIVsm-APIcit.s390x.rpm

Tip: If you are upgrading the API and the Common Inventory Technology package was previously
installed, you must upgrade both the API and Common Inventory Technology packages. For example,
you can run the following command:

rpm -U TIVsm-API64.s390x.rpm TIVsm-APIcit.s390x.rpm

If you need only the API installed, you can stop here. The rest of the steps in this procedure describe
how to install the backup-archive client components and an optional client package that is needed
only if you want the client to send PVU metrics to the server. Also described in subsequent steps are
the installation of the packages that are needed if you want to perform journal-based backups.
5. Install the backup-archive client, and optionally install the Common Inventory Technology package
that is needed to support processor value unit (PVU) calculations.
a) Install the backup-archive client components.

rpm -i TIVsm-BA.s390x.rpm

b) Optional: Install the Common Inventory Technology package the client uses to send PVU metrics to
the server. This package is dependent on the client package so it must be installed after the client
package is installed.

rpm -i TIVsm-BAcit.s390x.rpm

38 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 6. Optional: If you want to use journal-based backups, you must compile and install the filepath
component that matches the Linux kernel on your client computer. Extract TIVsm-filepath-
source.tar.gz and see the README file for compile and install instructions. The Linux filepath
kernel module is licensed pursuant to the terms of the GNU General Public License ("GPL").
Occasionally, build problems can occur due to the dynamic nature of the Linux kernel. If the source
does not build correctly on your Linux distribution, send an email to tsmosreq@us.ibm.com to request
the latest source file. Include the version of the Linux distribution and the output of the uname -a
command along with the version of the IBM Spectrum Protect client that you are installing.
7. Install the files required to perform file-restore operations by using the web user interface by entering
the following command:

rpm -ivh TIVsm-WEBGUI.s390x.rpm

Related concepts
“Configure the IBM Spectrum Protect client” on page 49
After installing the backup-archive client, you must configure it before performing any operations.

Uninstalling the Linux on System z client

You can use the following procedures to uninstall the IBM Spectrum Protect Linux on System z client.

Before you begin

You must be logged in as root to install the product. Uninstall the packages in the order shown.

About this task

To uninstall a previously installed IBM Spectrum Protect client package, enter the following commands to
remove the packages for journal-based backup, the filepath component, the backup-archive client, the
API, and the IBM Global Security Kit (GSKit).
Tip: The version number of the packages is not needed for uninstall.

Procedure
1. To uninstall the journal-based backup components only, remove both packages (journal-based
backup and filepath). The TIVsm-JBB package is dependent on the filepath package. If you use two
separate rpm -e commands to uninstall the components one at a time, uninstall the TIVsm-JBB
package first.

rpm -e TIVsm-JBB TIVsm-filepath

2. To remove the package that performs file-restore operations by using the web user interface, enter the
following command:

rpm -e TIVsm-WEBGUI

3. Uninstall the backup-archive client packages:

a) If you installed the optional TIVsm-BAcit package, uninstall it before you uninstall the client:

rpm -e TIVsm-BAcit

b) Uninstall the backup-archive client.

rpm -e TIVsm-BA

Note: If language packages are installed in a Version 7.1.2 or earlier client, you must remove them
before you remove the API package. Enter the following command, and replace xx_xx with the

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 39

 language code for each additional language that you installed. For a list of language code identifiers,
see Table 20 on page 40.

rpm -e TIVsm-msg.xx_xx

Table 20. Language pack identifiers

Language Language identifier
Czech CS_CZ
French FR_FR
German DE_DE
Hungarian HU_HU
Italian IT_IT
Japanese JA_JP
Korean KO_KR
Polish PL_PL
Portuguese PT_BR
Russian RU_RU
Spanish ES_ES
Traditional Chinese (EUC) ZH_CN
Traditional Chinese Big5 ZH_TW
4. Uninstall any products that are dependent on the API, such as IBM Spectrum Protect for Databases
and IBM Spectrum Protect for Mail. Any API-dependent products must be uninstalled before you
uninstall the API package. If you uninstall an API-dependent product, you must reinstall it after you
install a newer version of the backup-archive client and API packages. Consult the documentation of
the dependent product to determine what you need to do to prevent data loss when you uninstall and
reinstall the products.
a) If you installed the optional API common inventory package (TIVsm-APIcit), uninstall it before
you uninstall the API package. Use the following command to uninstall the package:

rpm -e TIVsm-APIcit

b) Uninstall the API package by using the following command:

rpm -e TIVsm-API64

5. To remove the GSKit 64-bit package, enter the following command:

rpm -e gskcryp64 gskssl64

Related tasks
“Installing the Linux on System z client” on page 36
You can install the Linux on System z backup-archive client from the product installation media.

Installing the Mac OS X client

You can install the IBM Spectrum Protect Mac OS X backup-archive client from the product installation
media.

Before you begin

You must be a system administrator to install the backup-archive client.

40 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 About this task
This installation procedure can be used to install new distributions or updates from downloaded
installation media. The downloaded files that you use to install the client might be compressed.
Depending on the package file format, either copy or extract the files to disk and use these instructions to
install the components.
You can download the appropriate package file from one of the following websites:
• Download the client package from Passport Advantage or Fix Central.
• For the latest information, updates, and maintenance fixes, go to the IBM Support Portal.
For MAC OS X clients, you can use an installation wizard that prompts you for information as the product
is installed, or you can also install the client from the command line. When you install the client by using
the command-line installation procedure, the installation runs without user interaction. The command-
line procedure is useful if you want to script the installation and run it on many nodes, or if you must
install the software on a system that does not have a monitor.

Procedure
Select an installation method and install the client. Use either the installation wizard method or install the
client from the command line.
Installation Procedure
method
Installation a. Double-click the 8.1.9.0.0-TIV-TSMBAC-Mac.dmg file to mount the disk
wizard image.
b. Double-click the IBM Spectrum Protect installation package icon and follow the
prompts to complete the installation.

Command line a. Change directories to where the IBM Spectrum Protect installer is located.
b. Install the custom installation package with the following command:

/usr/sbin/installer -pkg
"/Volumes/IBM Spectrum Protect/
IBM Spectrum Protect.pkg" -target /

What to do next
A sample client system options file, called dsm.sys.smp, is created in the installation directory. You can
copy this file and modify it to create the client systems options file for your node. The default name for the
client systems option file is dsm.sys.
After you install the client, you might need to set environment variables before you use it. For more
information about setting environment variables, see “Set processing environment variables” on page
59.

Uninstalling the Mac OS X client

You can uninstall the IBM Spectrum Protect Mac OS X client if you no longer need it.

Before you begin

If the IBM Spectrum Protect scheduler is configured as a startup item, use the IBM Spectrum Protect
Tools for Administrators function or the StopCad.sh shell script to stop and uninstall the scheduler
before you begin this procedure.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 41

 About this task
You can use a shell script to uninstall the backup-archive client. The shell script name is uninstall.sh
and it is in the default installation directory, which is /Library/Application Support/
tivoli/tsm/client/ba/bin. Use the sudo command to run the script.
Alternately, you can complete the following steps instead of using the script:

Procedure
1. Move the following folders to the trash:
• /Applications/IBM Spectrum Protect
• /Library/Application Support/tivoli
2. Remove the following symbolic links:
• /usr/bin/dsmc
• /usr/bin/dsmcad
• /usr/bin/dsmadmc
• /usr/bin/dsmtrace
• /usr/bin/dsmagent
• /usr/lib/libxmlutil-6.2.0.dylib
• /usr/lib/libtsm620xerces-c1_6_0.dylib

3. Optional: Remove the log files and options files if you do not want to preserve them. The uninstall
process leaves them on disk so your settings are retained in case you reinstall the product later.
The backup-archive client might have created log files in these locations:
a. /Library/Logs/tivoli
b. ~/Library/Logs/tivoli
The client option files (dsm.opt and dsm.sys) are typically saved in the following locations:
a. /Library/Preferences/Tivoli Storage Manager
b. ~/Library/Preferences/Tivoli Storage Manager

Installing the Oracle Solaris x86_64 client

You can install the IBM Spectrum Protect Oracle Solaris x86_64 backup-archive client from the product
installation media.

Before you begin

Starting in IBM Spectrum Protect Version 8.1.0, the Oracle Solaris backup-archive client is available only
on the Oracle Solaris x86_64 platform. The backup-archive client is no longer available on the Oracle
Solaris SPARC platform; only the IBM Spectrum Protect API is available on Oracle Solaris SPARC. For
information about how to install the Solaris SPARC API, see “Installing the Oracle SPARC API” on page
45.

About this task

If a previous version of the backup-archive client is installed, remove it before you install a new version.
For information about removing previous Solaris client packages, see “Uninstalling the Oracle Solaris
x86_64 client” on page 44.
The IBM Spectrum Protect installation administration file (tsmadmin) is used in place of the default
administration file (/var/sadm/install/admin), so that you are not asked about setuid, setgid, or
superuser permission during installation. If you want to use the default administration file, remove the -

42 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
a ./tsmadmin option from the commands that are shown, and answer the questions about setuid,
setgid, or superuser permission during installation with Y.

Table 21. Installation package names and descriptions

Package Package Name Package Description
IBM Global Security Kit (GSKit) gsk8cry64.pkg and Contains the IBM GSKit that
64 bit gsk8ssl64.pkg provides Secure Sockets Layer
(SSL) 64-bit data encryption
between the IBM Spectrum
Protect client and server.
IBM Spectrum Protect TIVsmCapi.pkg Contains the IBM Spectrum
application programming Protect 64-bit API shared library
interface (API) and samples.
Backup-archive client TIVsmCba.pkg Contains the following 64-bit
components:
• Backup-archive client
(command-line and GUI)
• Administrative client
(command-line)
• Web backup-archive client
Note:
1. TCP/IP and Shared memory
are supported as
communication methods.
2. The web client is a part of the
backup-archive client package
and cannot be installed
without it.

This installation procedure can be used to install new distributions or updates from downloaded
installation media. The downloaded files that you use to install the client might be compressed.
Depending on the package file format, either copy or extract the files to disk and use these instructions to
install the components.
You can download the appropriate package file from one of the following websites:
• Download the client package from Passport Advantage or Fix Central.
• For the latest information, updates, and maintenance fixes, go to the IBM Support Portal.
Install the packages in the order shown; some packages depend on the presence of others. For example,
GSKit is a prerequisite of the API, and the API is a prerequisite of the backup-archive client package.

Procedure
1. Log in as the root user.
2. Mount the volume that you are installing from.
3. Change to the directory where the packages are stored.
4. The IBM GSKit; it is a prerequisite of the IBM Spectrum Protect API package. Install GSKit by using the
following commands:

pkgadd -n -a ./tsmadmin -d ./gsk8cry64.pkg gsk8cry64

pkgadd -n -a ./tsmadmin -d ./gsk8ssl64.pkg gsk8ssl64

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 43

 Note: On Solaris 10, these commands install the 64-bit GSKit in the global zone and in all running non-
global zones. To install the client in a sparse-root, non-global zone only, GSKit must first be installed in
the global zone. On Solaris 11, the packages are only installed in the zone where these commands are
run.
5. Use the following command to install the IBM Spectrum Protect API:

pkgadd -n -a ./tsmadmin -d ./TIVsmCapi.pkg TIVsmCapi

Note: On Solaris 10, this command installs the IBM Spectrum Protect 64-bit API in the global zone
and in all running non-global zones. If you want to install it in the global zone only, use the -G
parameter of the pkgadd command. On Solaris 11, the API is only installed in the zone where this
command is run.
6. Use the following command to install the backup-archive client:

pkgadd -n -a ./tsmadmin -d ./TIVsmCba.pkg TIVsmCba

Note: On Solaris 10, this command installs the backup-archive client components in the global zone
and in all running non-global zones. If you want to install them in the global zone only, use the -G
parameter of the pkgadd command. On Solaris 11, the client components must are only installed in
the zone where this command is run.

Results
Important: For a Solaris 10 sparse root non-global zone, the /usr file system is normally mounted as
read-only (LOFS) from the global zone, and the following conditions apply:
• If the client is not installed in the global zone, a warning message appears at the end of the installation.
The message asks the global administrator to create the required links that are provided as part of the
warning messages.
• If the client is already installed in the global zone, creation of these links is not necessary. The links are
already present and they are pointing to the correct executable files and libraries.
Related concepts
“Configure the IBM Spectrum Protect client” on page 49
After installing the backup-archive client, you must configure it before performing any operations.

Uninstalling the Oracle Solaris x86_64 client

You can uninstall all the packages that are related to IBM Spectrum Protect Oracle Solaris x86_64 client,
including the command-line, GUI, web GUI, and administrative client components.

About this task

Important: Make sure that you uninstall the packages in the specified order.
The IBM Spectrum Protect installation administration file (tsmadmin) is used in place of the default
administration file (/var/sadm/install/admin), so that you are not prompted for questions about
setuid, setgid, or superuser permission during installation. If you want to use the default
administration file, remove the -a ./tsmadmin option from the following commands and answer the
questions about setuid, setgid, or superuser permission during installation with y.

Procedure
1. Enter the following command to uninstall the backup-archive client:

pkgrm -n -a ./tsmadmin TIVsmCba

This command uninstalls all of the components of the backup-archive client (command-line, GUI, web
client, and the administrative client). You cannot uninstall individual components of this package (for
example, the command-line client).

44 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Note: If one or more language messages packages are installed in Version 7.1.2 or earlier clients,
remove them before you remove the API package. Enter the following command as the root user:

pkgrm -n -a ./tsmadmin TIVsmClCs TIVsmClDe TIVsmClEs TIVsmClFr \

TIVsmClHu TIVsmClIt TIVsmClJa TIVsmClKo \
TIVsmClPl TIVsmClPt TIVsmClRu TIVsmClSc TIVsmClTc

2. Enter the following command to uninstall the IBM Spectrum Protect API:

pkgrm -n -a ./tsmadmin TIVsmCapi

The API cannot be removed if the backup-archive client is installed. The backup-archive client must be
removed first.
3. Enter the following commands to uninstall the GSKit:

pkgrm -n -a ./tsmadmin gsk8ssl64

pkgrm -n -a ./tsmadmin gsk8cry64

Installing the Oracle SPARC API

You can install the IBM Spectrum Protect Oracle Solaris SPARC API from the product installation media.

About this task

If a previous version of the API installed, remove it before you install a new version. For information about
removing previous Solaris API packages, see “Uninstalling the Oracle Solaris SPARC API” on page 46.
The IBM Spectrum Protect installation administration file (tsmadmin) is used in place of the default
administration file (/var/sadm/install/admin), so that you are not asked about setuid, setgid, or
superuser permission during installation. If you want to use the default administration file, remove the -
a ./tsmadmin option from the commands that are shown, and answer the questions about setuid,
setgid, or superuser permission during installation with Y.

Table 22. Installation package names and descriptions

Package Package Name Package Description
IBM Global Security Kit (GSKit) gsk8cry64.pkg and Contains the IBM GSKit that
64 bit gsk8ssl64.pkg provides Secure Sockets Layer
(SSL) 64-bit data encryption
between the IBM Spectrum
Protect API and server.
IBM Spectrum Protect TIVsmCapi.pkg Contains the IBM Spectrum
application programming Protect 64-bit API shared library
interface (API) and samples.

This installation procedure can be used to install new distributions or updates from downloaded
installation media. The downloaded files that you use to install the client might be compressed.
Depending on the package file format, either copy or extract the files to disk and use these instructions to
install the components.
You can download the appropriate package file from one of the following websites:
• Download the client package from Passport Advantage or Fix Central.
• For the latest information, updates, and maintenance fixes, go to the IBM Support Portal.
Install the packages in the order shown.

Procedure
1. Log in as the root user.
2. Mount the volume that you are installing from.

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 45

 3. Change to the directory where the packages are stored.
4. The IBM GSKit; it is a prerequisite of the IBM Spectrum Protect API package. Install GSKit by using the
following commands:

pkgadd -n -a ./tsmadmin -d ./gsk8cry64.pkg gsk8cry64

pkgadd -n -a ./tsmadmin -d ./gsk8ssl64.pkg gsk8ssl64

Note: On Solaris 10, these commands install the 64-bit GSKit in the global zone and in all running non-
global zones. To install the API in a sparse-root, non-global zone only, GSKit must first be installed in
the global zone. On Solaris 11, the packages are only installed in the zone where these commands are
run.
5. Use the following command to install the IBM Spectrum Protect API:

pkgadd -n -a ./tsmadmin -d ./TIVsmCapi.pkg TIVsmCapi

Note: On Solaris 10, this command installs the IBM Spectrum Protect 64-bit API in the global zone
and in all running non-global zones. If you want to install it in the global zone only, use the -G
parameter of the pkgadd command. On Solaris 11, the API is only installed in the zone where this
command is run.

Results
Important: For a Solaris 10 sparse root non-global zone, the /usr file system is normally mounted as
read-only (LOFS) from the global zone, and the following conditions apply:
• If the API is not installed in the global zone, a warning message appears at the end of the installation.
The message asks the global administrator to create the required links that are provided as part of the
warning messages.
• If the API is already installed in the global zone, creation of these links is not necessary. The links are
already present and they are pointing to the correct executable files and libraries.
Related concepts
“Configure the IBM Spectrum Protect client” on page 49
After installing the backup-archive client, you must configure it before performing any operations.

Uninstalling the Oracle Solaris SPARC API

You can uninstall all the packages that are related to IBM Spectrum Protect Oracle Solaris SPARC API.

About this task

Important: Make sure that you uninstall the packages in the specified order.
The IBM Spectrum Protect installation administration file (tsmadmin) is used in place of the default
administration file (/var/sadm/install/admin), so that you are not prompted for questions about
setuid, setgid, or superuser permission during installation. If you want to use the default
administration file, remove the -a ./tsmadmin option from the following commands and answer the
questions about setuid, setgid, or superuser permission during installation with y.

Procedure
1. Enter the following command to uninstall the IBM Spectrum Protect API:

pkgrm -n -a ./tsmadmin TIVsmCapi

2. Enter the following commands to uninstall the GSKit:

pkgrm -n -a ./tsmadmin gsk8ssl64

pkgrm -n -a ./tsmadmin gsk8cry64

46 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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.
The client management service is available for installation on Linux backup-archive client systems.
For installation instructions and more information about the client management service, see Collecting
diagnostic information with .

Chapter 1. Installing the IBM Spectrum Protect backup-archive clients 47

48 IBM Spectrum Protect UNIX and Linux 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.
Tip: After you install the backup-archive client, the IBM License Metric Tool counts the client only if it is
connected to the IBM Spectrum Protect server and is used for data operations. Subsequently, that client
is always included in license calculations. Clients that are not connected to a server and are not used for
data operations are excluded from license calculations.
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 and dsm.sys files used by the previous client installation
are 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 these files for configuration information.
Some configuration tasks are required, while other tasks are optional. The following configuration tasks
are required:
• “Creating and modifying the client system-options file” on page 54
• “Register your workstation with a server” on page 111
The following configuration tasks are optional:
• “Creating a default client-user options file” on page 56
• “Creating a customized client user-options file” on page 58
• “Environment variables” on page 58
• “Configuring the web client on AIX, Linux, Mac, and Solaris systems” on page 62
• “Configuring the scheduler” on page 63
• “Creating an include-exclude list ” on page 112
• Configuring parallel backups of VMware virtual machines. See “Parallel backups of virtual machines” on
page 202

UNIX and Linux client root and authorized user tasks

An authorized user is any non-root user who has read and write access to the stored password (TSM.sth
file), or anyone who knows the password and enters it interactively. Authorized users use the
passworddir option to define the directory where their copy of the password file is saved.
Table 23 on page 49 shows the tasks that can and cannot be performed by the root user, authorized
users, and other users.

Table 23. Tasks for root users and authorized users

Task Root user Authorized user
Log on to the IBM Spectrum Protect Yes Yes
server, using an LDAP server to
authenticate credentials.
Register new nodes with the IBM Yes Yes
Spectrum Protect server (if
registration is set to open on the
server).
Set or re-create the IBM Spectrum Yes Yes
Protect password for client
workstations

© Copyright IBM Corp. 1993, 2019 49

Table 23. Tasks for root users and authorized users (continued)
Task Root user Authorized user
Backup Yes Yes, if you have read permission,
regardless of ownership
Note: The IBM Spectrum Protect
administrator can specify an option
on either the Register Node or
Update Node commands to
specify who is allowed to back up
data for a node. Setting
BACKUPINITiation to root
restricts backups so that only root
or authorized users can back up
files on a node. Setting
BACKUPINITiation to all
allows any user to back up data on
a node. For information about these
commands and options, see the
IBM Spectrum Protect server
documentation.

Restore Yes; when restoring to a new Yes; however, the operating system
location or the same location, file prevents writing to the same
permission and ownership are location if the file has read only
preserved permission. When restoring to the
same location, file permissions and
ownership are preserved. When
restoring to a different location, the
permissions of the restored file are
preserved but the ownership
changed to the current user.
Archive Yes Yes, if you have read permission,
regardless of ownership
Retrieve Yes. When retrieving to a new Yes. However, the operating system
location or to the same location, file prevents writing to the same
permissions and ownership are location if the file has read only
preserved. permission. Ownership of all
retrieved objects is changed to the
current user.
Client scheduler Yes Yes, if not using the client acceptor
daemon.
You must be root to manage the
client acceptor daemon. A non-root
authorized user can use the
scheduler (dsmc sched).

Grant user access to files on the Yes Yes

IBM Spectrum Protect server
Delete IBM Spectrum Protect Yes, if the node is granted backup Yes, if the node is granted backup
server file spaces or archive delete authority by the or archive delete authority by the
IBM Spectrum Protect server IBM Spectrum Protect server
administrator administrator

50 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 On Mac OS X systems, a system administrator is any user that is allowed to administer the system. You
can check your account type using the System Preferences > Accounts tool. System Administrators have
an account type of Admin.
The system administrator is responsible for configuring the backup-archive client so non-administrators
can manage their own data. Non-administrators (or non-authorized users) meet the following criteria:
• They do not have a user ID of 0. They are not the root user.
• They have a user account that has not been configured as a system administrator.
When a task requires additional authority to complete, you must use the authorization application to start
the backup-archive client. This allows the client to run with sufficient system privileges to complete the
task. The following table lists the authorization tools to use.

Table 24. Mac OS X authorization tools and associated IBM Spectrum Protect applications
Mac OS X authorization tool Associated IBM Spectrum Protect application
IBM Spectrum Protect For Administrators IBM
Spectrum Protect
StartCad.sh
StopCad.sh

sudo dsmc

Enable non-root users to manage their own data

To enable non-root users to use the backup-archive client to manage their own data, the system
administrator must complete steps in addition to the normal configuration steps to setup first-time
Authorized users for non-root users.
In addition to the normal configuration steps, the system administrator must complete the following
steps to setup Authorized users for non-root users:
1. Add a stanza in the client system-options file, dsm.sys, for the non-root user.
2. In this stanza, use the passworddir option to point to a directory that is owned by the non-root user.
The non-root user can then create a file in this passworddir directory.
3. Assign the non-root user with a unique TSM node name.
4. Ensure that an earlier TSM.PWD file that is not owned by the non-root user, does not exist in the
passworddir directory. If such a file exists, change ownership of this file to the non-root user or
remove the file.
5. Ensure that TSM.KDB, TSM.IDX or TSM.sth files that are not owned by the non-root user, do not exist
in the passworddir directory. If such files exist, remove them.
On completion of the steps by the system administrator, the non-root user must complete the following
steps:
1. Create a client system-options file, dsm.opt, and use the servername option to specify the stanza
name.
2. Ensure that the dsm.opt file can be read by default by the DSM_CONFIG environment variable. Issue
the export DSM_CONFIG=<dsm.opt> command from a shell command window to check.
3. Run the dsmc q f command to use password files that are pointed to by the passworddir option. If
no password files exist, the user is prompted.

Enabling encryption for backup-archive client users

If you configure the backup-archive client to encrypt data during backup and archive operations, and if
you specify the option to store the encryption key password (encryptkey save), by default, only root
and IBM Spectrum Protect authorized users can use the stored password to encrypt or decrypt files.

Chapter 2. Configure the IBM Spectrum Protect client 51

 Authorized users include any non-root users who have read and write access to the stored password
(TSM.sth file), or users who know the password and enter it interactively.

Enable non-root users to manage shared data

In some cases, it is necessary to have a group of non-root users who can back up data to and restore data
from a shared node. To accomplish this task, create a stanza in the dsm.sys file by specifying a unique
node name and password directory. The users who are allowed to use this node are controlled by adding
the users to a shared UNIX group, and granting permission to the saved password files for this group.

Example dsm.sys file stanza

In the following example stanza, a node name is specified that is shared among the group of non-root
users. This node name is different from other node names that can also be used on the system by
different users. For example, there might be a different stanza that the root user uses. Also, the directory
that is specified by the passworddir option must be different from the password directory that is used
by other stanzas in the dsm.sys file that are intended for different users.
Different stanzas can reference different IBM Spectrum Protect servers. If the same group of non-root
users requires access to all of these servers, each stanza can reference the same password directory.
As the root user, create a stanza like the following example:

servername spserver_dbgrp
tcps tapsrv14
tcpp 1500
nodename server1_dbgrp
passworddir /etc/spdbgrp
passworda generate

For AIX, use the following passworddir option:

passworddir /etc/security/spdbgrp

After the stanza is created, as the root user, run the query session command to create the new
password directory and initial stored passwords. For example, if the server name is tapsrv14, you would
issue the following command:

dsmc query session -server=tapsrv14_dbgrp

Assign group permissions to the newly created password directory

To allow a group of users to share the common password files, create a group. The users are assigned to
this new group as a secondary group, and the permissions of the stored passwords are modified. This
modification allows the new group to read and modify the stored password without allowing users outside
the group to have access. Review the example for your operating system:
AIX example
In this example, the group dbadm represents an existing database group that is the primary group. A
secondary group that is named spdbgrp is created for control access to the IBM Spectrum Protect
password files.

mkgroup spdbgrp
usermod -g dbadm -G spdbgrp user1
usermod -g dbadm -G spdbgrp user2

To grant group permission to the password files, you would run the following commands:

chmod 770 /etc/security/spdbgrp

chmod -R 660 /etc/security/spdbgrp/*

52 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 chmod 770 /etc/security/spdbgrp/Nodes
chgrp -R spdbgrp /etc/security/spdbgrp

Linux example
In this example, the group dbadm represents an existing database group that is the primary group. A
secondary group that is named spdbgrp is created for control access to the IBM Spectrum Protect
password files.

mkgroup spdbgrp
usermod user1 -g dbadm -G spdbgrp
usermod user2 -g dbadm -G spdbgrp

To grant group permission to the password files, you would run the following commands:

chmod 770 /etc/spdbgrp

chmod -R 660 /etc/spdbgrp/*
chmod 770 /etc/spdbgrp/Nodes
chgrp -R spdbgrp /etc/spdbgrp

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 AIX, Linux, Mac, and Solaris systems, the default client options file is named dsm.opt. For these
operating systems, two files contain backup-archive client options:
• The client-user options file. The default name for this file is dsm.opt. For brevity, this file is often called
the client options file.
• The client-system options file. The default name for this file is dsm.sys. The client-system options file is
an editable file that identifies the server and communication method, and provides the configuration for
backup, archiving, hierarchical storage management, and scheduling. For brevity, this file is often called
the system options file.
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 cannot change the name of the client-system option file. It must be named dsm.sys.
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.
Restriction: For Mac OS X, the client-user options file and client-system options file must be plain text
files, encoded as Unicode (UTF-8). By default, TextEdit does not save files as plain text. Select Format >
Make Plain Text to save the files as plain text files. Select Unicode (UTF-8) in the Plain Text Encoding
drop down list. Do not add the .txt extension when you save the file.
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:

Chapter 2. Configure the IBM Spectrum Protect client 53

 • 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.
• Do not specify options on a line that contains a comment.
• 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.
• 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 /home /mfg /planning /mrkting /mgmt

domain / /Volumes/fs2 /Volumes/fs2 /Volumes/fs3 /Volumes/fs4

• To set an option in this file, enter the option name and one or more blank spaces, followed by the option
value.
• Enter one or more blank spaces between parameters.
• The lengths of file and path names in the client options files cannot exceed the following limits:
– On AIX, Mac OS, and Solaris, the maximum length for a file name is 255 bytes. The maximum
combined length of the file name and path name is 1024 characters. The Unicode representation of a
character can occupy several bytes, so the maximum number of characters that a file name might
contain can vary.
– On Linux, the maximum length for a file name is 255 bytes. The maximum combined length of the file
name and path name is 4096 bytes. This matches the PATH_MAX that is supported by the operating
system. The Unicode representation of a character can occupy several bytes, so the maximum
number of characters that comprises a path and file name can vary. The limitation is the number of
bytes in the path and file components, which might or might not correspond to an equal number of
characters.
– For archive or retrieve operations, the maximum length that you can specify for a path and file name,
combined, is 1024 bytes.

If you update the client-user options file while a session is active, you must restart the session to pick up
the changes.
Related reference
“Optfile” on page 447
The optfile option specifies the client options file to use when you start a backup-archive client
session.
“Query Options” on page 655
Use the query options command to display all or part of your options and their current settings that
are relevant to the command-line client.

Creating and modifying the client system-options file

The client system-options file is an editable file that identifies the server and communication method, and
provides the configuration for backup, archiving, hierarchical storage management, and scheduling.

About this task

Creating and modifying the client system-options file (dsm.sys) is a required task.
The backup-archive client GUI provides a Configuration Wizard that can be used to create basic
configuration files and test the connection to the IBM Spectrum Protect server. The Configuration Wizard
starts automatically if the configuration files are not found when the GUI starts. If you want to modify the
configuration files after they are created, click on Setup Wizard from the Tools menu of the GUI.
If you do not use the Configuration Wizard, you can create and modify the client options file manually.
For Mac OS X, copy the dsm.sys.smp file to dsm.sys in one of the following locations. The default
locations are listed in the order that they are searched.

54 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
1. A location identified by the DSM_DIR environment variable
2. /Library/Application Support/tivoli/tsm/client/ba/bin/
3. /Library/Preferences/Tivoli Storage Manager/
The client uses the first options file that is found. You must use the name dsm.sys for this file. The
dsm.sys file is controlled by the system administrator.
For Oracle Solaris systems, copying dsm.sys.smp to dsm.sys is not required. The client options files
(dsm.opt and dsm.sys) are automatically created in /usr/bin, if they do not already exist, and they
are linked to the client installation directory when you install the client. Note that the files are not
removed if you uninstall the client, so you can reuse your settings if you upgrade or reinstall the client.
For the other platforms, as the root user, copy the dsm.sys.smp file to dsm.sys and then edit that file to
configure your settings. The client looks for dsm.sys in the directory specified by the DSM_DIR
environment variable (if it is set and exported), and then in the installation directory.
Important: If you are reinstalling and you want to keep your existing dsm.sys file intact, do not copy the
dsm.sys.smp file to dsm.sys.
Use the dsm.sys file to specify one or more servers to contact for services, and communications options
for each server. This file can also include authorization options, backup and archive processing options,
and scheduling options.
Edit dsm.sys to include the server or servers to which you want to connect. The following is an example
of a client system-options file stanza which contains the required options for a server you want users to
contact. You can specify options for more than one server:

Servername server_a
COMMMethod TCPip
TCPPort 1500
TCPServeraddress node.domain.company.com

Important: If you want to use the web client, you must also specify the passwordaccess=generate
option, and log in with the client to save the password.
As the default, your client node contacts the first server identified in the dsm.sys file. You can specify a
different server to contact by entering the servername option in your own client user-options file
(dsm.opt), or by entering that option with a command.
You can also specify a default server and a migration server (if you have the HSM client installed on your
workstation) in your dsm.sys file.
The dsm.sys file can also contain the following option categories:
• Communication options
• Backup and archive processing options
• Restore and retrieve processing options
• Scheduling options
• Authorization options
• Error processing options
• Transaction processing option
• Web client options
You can modify your dsm.sys file using one of the following methods:
• From the client Java GUI main window, select Edit > Client Preferences.
• Use your favorite text editor.
Important: For Mac OS X, the system-options file must be a plain text file, encoded as Unicode (UTF-8).
By default, TextEdit does not save files as plain text. Select Format > Make PlainText to save the user-
options file as a plain text file. Set the Plain Text Encoding: to Unicode (UTF-8). Do not add the .txt
extension.

Chapter 2. Configure the IBM Spectrum Protect client 55

 If you update the dsm.sys file while the client is running, you must restart the process to pick up the
changes.
Related concepts
“Client options file overview” on page 53
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.
“Processing options” on page 277
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 reference
“Defaultserver” on page 339
Use the defaultserver option to specify the name of the IBM Spectrum Protect server to contact for
backup-archive services if more than one server is defined in the dsm.sys file.
“Passwordaccess” on page 449
The passwordaccess option specifies whether you want to generate your password automatically or set
as a user prompt.

Creating a default client-user options file

A client-user options file stores the backup-archive client processing options. The backup-archive
installation program places a sample client-user options file on disk when you install the backup-archive
client. A system administrator or root can edit this file to create a default client options file, and makes
the file accessible to workstation users who use the backup-archive client. Individual users can create
and use their own client options file.

Before you begin

You must be root or a system administrator to complete this procedure.

About this task

Creating a default client-user options file is an optional task.
By default, the client-user options file is named dsm.opt, and the file contains the following types of
client options:
• Backup and archive processing options
• Restore and retrieve processing options
• Scheduling options
• Format options
• Command processing options
• Authorization options
• Error processing options
• Transaction processing option
• Web client options
For Mac clients, the client installation program places a sample client-user options file named
dsm.opt.smp in /Libraries/Preferences/Tivoli Storage Manager/. This directory is the
same directory that the installation program places a sample client-system option file (dsm.sys.smp) in.
For AIX and Linux clients, the client installation program places a sample client-user options file named
dsm.opt.smp in the default client installation directory. This directory is the same directory that the
installation program places a sample client-system option file (dsm.sys.smp) in.

56 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
For Oracle Solaris clients, the installation program places an initial client-user options file named
dsm.opt in the /usr/bin directory. This directory is the same directory that the installation program
places a sample client-system option (dsm.sys) file in.
For all client operating systems, the following procedure instructs you to edit the sample client-user
options file and save it with the default name, dsm.opt. You can save the file with a different name or
path, if you want to, but if you change the file name or if you move the file from the default installation
directory, you must use either of the following methods to specify the path and name of the client-user
options file:
• Set the DSM_CONFIG environment variable to indicate the path and file name of the client-user option
file (dsm.opt). Set the DSM_DIR environment variable to indicate the path and file name of the client-
system option file (dsm.sys). For more information about the environment variables, see “Set
processing environment variables” on page 59.
• Specify the backup-archive client optfile option to specify the path and file name of the client-user
options file.
Note: All node users must have read access to the disk location where you store the client-user options
file.

Procedure
1. Change to the directory that contains the sample client-user options file.
2. Copy the file to dsm.opt.
3. Add options for your node to the dsm.opt file.
Use either of the following methods to set the client-user options:
• Edit dsm.opt with a text editor to add the options that are needed in the node.
Note: On Mac OS X, the dsm.opt file must be saved as a plain text file and use Unicode (UTF-8) as
the encoding scheme. By default, TextEdit does not save files as plain text. To save dsm.opt, in
TextEdit, select Format > Make Plain Text. In the Plain Text Encoding drop-down list, select
Unicode (UTF-8). Do not add the .txt extension to the file name.
• Set client options by using the preferences editior. In the backup-archive client GUI, select Edit >
Client Preferences and select the options that you want to configure. The preferences editor
updates the client configuration files, dsm.opt, and dsm.sys if you add, change, or remove options.
If you update the dsm.opt file while the backup-archive client is running, you must restart the
backup-archive client so the updates are recognized.
The preferences editor uses the DSM_DIR environment variable to locate the client-system options
file (dsm.sys) and the DSM_CONFIG environment variable to locate the client user-options file
(dsm.opt). If you want dsm.opt to be in a non-default location, set DSM_CONFIG before you start
backup-archive client and then use the preferences editor to set the options. The preferences editor
queries the server for options on the server, but cannot change the server options file.
Related concepts
“Processing options” on page 277
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.
“Set processing environment variables” on page 59
Some circumstances require you to set environment variables to ensure that IBM Spectrum Protect
applications can locate the files that are needed to perform client operations, and that applications can
create log files that record events and errors that occur during client operations.
Related tasks
“Creating and modifying the client system-options file” on page 54

Chapter 2. Configure the IBM Spectrum Protect client 57

 The client system-options file is an editable file that identifies the server and communication method, and
provides the configuration for backup, archiving, hierarchical storage management, and scheduling.

Creating a customized client user-options file

If you want to use different options than those specified in the default client user-options file (dsm.opt),
you can create your own client user-options file.

About this task

You can set all of the options that can be set in the default user options file. Creating a customized client
user-options file (dsm.opt) is an optional task. To create or modify a client user-options file, use the
following method:

Procedure
1. Contact the IBM Spectrum Protect administrator on your workstation to determine the location of the
sample client user-options file dsm.opt.smp, and to get the TCP/IP address of the backup server you
are connecting to and the port it listens on.
2. Copy dsm.opt.smp to your home directory as dsm.opt, or a new file name of your choice. Store your
client user-options file in any directory to which you have write access.
3. Set the DSM_CONFIG environment variable to point to your new client user-options file.
4. Edit your dsm.opt file as appropriate for your system or use the Preferences Editor by selecting Edit >
Client Preferences from the backup-archive client GUI.

Results
Once you have created an options file, you can use the following steps to edit your options file from the
GUI.
1. Open the Edit menu and select Client Preferences.
2. Make any necessary changes, then click OK to save those changes.
Important: For Mac OS X, the system-options file must be a plain text file, encoded as Unicode (UTF-8).
By default, TextEdit does not save files as plain text. Select Format > Make PlainText to save the user-
options file as a plain text file. Set the Plain Text Encoding drop-down list selection to Unicode
(UTF-8). Do not add the .txt extension.
Related concepts
“Environment variables” on page 58
Generally, setting the environment variables is an optional task. Setting these variables makes it more
convenient for you to use the command line.
“Client options file overview” on page 53
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.

Environment variables
Generally, setting the environment variables is an optional task. Setting these variables makes it more
convenient for you to use the command line.

Set language environment variables

The backup-archive client automatically detects the language of the system locale and displays in that
language.
For example, a French operating system displays the backup-archive client in French by default. If the
backup-archive client cannot load the French message catalog, it defaults to the English (United States)

58 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 language. For example, if the client is running in an unsupported language and locale combination, such
as French/Canada or Spanish/Mexico, the client defaults to English (United States).
You can use the LANG environment variable to specify the language for the UNIX and Linux clients.
Note: The operating system locale, the terminal character set, and the file name character set encoding
must match in order for files names to be displayed or entered correctly.
To set the LANG environment variable to French, type the following statement:

export LANG=fr_FR

Note:
• This task does not apply to Mac OS X.
• To display the IBM Spectrum Protect help browser menus in the language of your current locale, ensure
that the NLSPATH environment variable in the /etc/profile file contains the following path:

NLSPATH=/usr/dt/lib/nls/msg/%L/%N.cat:$NLSPATH
export NLSPATH

If the locale of the backup-archive client is the same as the character encoding of the file names, all of
those files are backed up or restored correctly. If you are running in any single-byte character set (SBCS),
then all file names are valid and are backed up or restored by the backup-archive client.
If you are running in a DBCS or UTF-8 locale, file names that are composed of characters that are not valid
in the DBCS or UTF-8 locale cannot be entered on the backup-archive client command line. The files
might be skipped when you run a backup where a wildcard ("*") specification is used. If files are skipped,
here is an example of the error message that is issued:

ANS4042E Object name '/testData/en_US_files/file3?'

contains one or more unrecognized characters and is not valid.

If all directories and files are not created with the same locale, then run your scheduled backups by using
a single-byte character set locale. This action ensures that files are not skipped because the file names
contain characters that are not defined in the current locale. When you restore files, run in the same
locale that matches the locale encoding of the file name.
For example, file names that consist of Japanese characters might contain invalid multibyte characters if
they are displayed in a Chinese locale. These files are not backed up and are not shown by the graphical
user interface. If such files are found during backup, the dsmerror.log file lists the skipped files.
Tip: When you use the backup-archive client scheduling mode to back up a whole system, set the LANG
environment variable to en_US (or some other SBCS language) to avoid skipped files.

Set processing environment variables

Some circumstances require you to set environment variables to ensure that IBM Spectrum Protect
applications can locate the files that are needed to perform client operations, and that applications can
create log files that record events and errors that occur during client operations.
You must set the environment variables in any of the following circumstances:
• You want to invoke the backup-archive client from a directory other than the directory where the
backup-archive client is installed
• You want to specify a different options file for the backup-archive client, the administrative client, or
both.
• You do not want log files to be written to the default installation directory.
Tip: You can also specify an alternate client options file for the command-line client (not the
administrative client) using the optfile option.
There are four environment variables you can set which affect backup-archive client processing:

Chapter 2. Configure the IBM Spectrum Protect client 59

 PATH
Includes the directory where the executable file for the client executables (dsmc, dsmadmc, dsmj)
resides.
DSM_DIR
Specifies the directory where the executable file for the client executables (dsmc, dsmadmc, dsmj)
the resource files, and the dsm.sys file reside. You cannot specify the root (/) directory for DSM_DIR.
Refer to the installation section for your operating system to find the default installation directory
information.
When you request an image backup, image restore, snapshot-based file backup, NAS backup, or NAS
restore, the client uses the DSM_DIR environment variable to locate the corresponding plug-in library.
If DSM_DIR is not set, the client looks for the plug-in library in the following directories:
AIX
/usr/tivoli/tsm/client/ba/bin/plugins
Oracle Solaris and all Linux clients
/opt/tivoli/tsm/client/ba/bin/plugins
DSM_CONFIG
Specifies the fully-qualified path and file name of the client user options file for users who create their
own personalized options file. If DSM_CONFIG is not set, or the client optfile option is not used, the
client user options file is expected to satisfy these requirements:
1. The options file must be named dsm.opt.
2. For UNIX clients other than Mac OS X, if DSM_DIR is not set, then the file must reside in the default
installation directory. If DSM_DIR is set, then the file must reside in the directory specified by
DSM_DIR.
3. For Mac OS X, the file can reside in any of the following locations. These directories are searched in
order, and the first option file found is used. ~/Library Preferences/Tivoli Storage
Manager, /Library Preferences/Tivoli Storage Manager, or /Library/Application
Support/tivoli/tsm/client/ba/bin.
Refer to the installation section for your operating system to find the default installation directory
information.
DSM_LOG
Points to the directory where you want the IBM Spectrum Protect log files to reside. You cannot
specify the root (/) directory for DSM_LOG. The log files contain information about errors and events
that occur during processing. The client creates the logs to help the technical support team diagnose
severe errors.
Refer to the installation section for your operating system to find the default installation directory
information.
Important: Set the DSM_LOG environment variable to name a directory where read-write
permissions allow the required write access for the user to create and write to the log file. This
prevents log write failures and process termination. Use the chmod or setacl commands to give the
files permissions that allow all client user IDs to read and write them. If the log names are the default
names, just set the DSM_LOG environment variable to point to the directory where they reside. When
the client cannot write to the log file, an error message is written to stderror and to the syslog
daemon. The syslog daemon must be running and configured to process messages with a priority of
LOG_ERR for the error message to appear in the system log. Starting and configuring the syslog
daemon is system specific. Use man syslogd command for information about starting the syslog
daemon. Use man syslog.conf for information about configuring the syslog daemon.
Note:
1. The errorlogname and schedlogname options override DSM_LOG. If you specify the
errorlogname client option, the file is stored in the directory specified by the errorlogname option
and not in the location specified by DSM_LOG. If you specify the schedlogname client option, it is

60 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 written to the directory specified by the schedlogname option and not in the location specified by
DSM_LOG.
2. The log files cannot be symbolic links. The client detects any such links, delete the links, then exits
the operation. This action prevents the client from overwriting protected data. The affected logs
are created as files in a subsequent operation.
To use the backup-archive client Java GUI program, you must export the directory where you installed
the java binary file. For example, enter the following command:

export PATH=$PATH:java_bin_dir

where: java_bin_dir is the path to the runnable Java binary file in your file system.
Related reference
“Optfile” on page 447
The optfile option specifies the client options file to use when you start a backup-archive client
session.

Set Bourne and Korn shell variables

Enter the environment variables in the .profile file (Korn shell) or .bash_profile file (Bourne shell)
in your $HOME directory.
The following is an example, where /home/davehil/dsm.opt is the path and file name for your client
user-options file, and the /home/davehil directory is where you want to store the dsmerror.log file,
executable file, resource files, and dsm.sys file.

DSM_DIR=/home/davehil
DSM_CONFIG=/home/davehil/dsm.opt
DSM_LOG=/home/davehil
export DSM_DIR DSM_CONFIG DSM_LOG

Set C shell variables

For the C shell, add the DSM_CONFIG, DSM_LOG and DSM_DIR variables to the .cshrc file in your
$HOME directory.
The following is an example, where /home/davehil/dsm.opt is the path and file name for your client
user-options file, and the /home/davehil directory is where you want to store the dsmerror.log file,
executable file, resource files, and dsm.sys file.

setenv DSM_DIR /home/davehil

setenv DSM_CONFIG /home/davehil/dsm.opt
setenv DSM_LOG /home/davehil

Set API environment variables

If you installed the IBM Spectrum Protect API, set the following environment variables.
DSMI_DIR
Points to your installation directory. The file dsm.sys must reside in the directory pointed to by
DSMI_DIR. This environment variable must be present.
DSMI_CONFIG
Full path name of your own client user-options file (dsm.opt).
DSMI_LOG
Path for dsierror.log (this path cannot be a symbolic link).
Note: End users of applications that are developed with the API can consult the installation directions for
that application for special path names or guidelines for options.

For more information about the IBM Spectrum Protect API, see Developing solutions with the application
programming interface.

Chapter 2. Configure the IBM Spectrum Protect client 61

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 GUI to connect
to the IBM Spectrum Protect V8.1.2 or later server. For more information, see “Using the web client in the
new security environment” on page 136.
Backup-archive client options are used to configure web client settings. These options include httpport,
managedservices, webports, and revokeremoteaccess.
On AIX, Linux, Mac, and Solaris client nodes, you add the web client options to the client-systems option
file (dsm.sys).
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 296
Several backup-archive client options are used to configure the IBM Spectrum Protect web client.
Related tasks
“Configuring the web client on AIX, Linux, Mac, and Solaris systems” on page 62
To configure the web client, edit the client-system options file (dsm.sys) to specify the required options,
and then start the client acceptor daemon.

Configuring the web client on AIX, Linux, Mac, and Solaris systems
To configure the web client, edit the client-system options file (dsm.sys) to specify the required options,
and then start the client acceptor daemon.

Procedure
1. Set the following options in the dsm.sys file: managedservices webclient schedule and
passwordaccess generate.
2. Generate the IBM Spectrum Protect password. Enter dsmc query session. When you are prompted
for credentials, enter the IBM Spectrum Protect user name and password.
On Mac OS X systems, you can also generate the password by using the IBM Spectrum Protect Tools
for Administrators application. In the application, select IBM Spectrum Protect to start the client.
3. Start the client acceptor daemon. Enter dsmcad.
On Mac OS X, you can also start the client acceptor daemon with the IBM Spectrum Protect Tools for
Administrators application. In the application, select Start the Client Acceptor Daemon.
4. To access the web client from a browser, specify the host name or IP address of the client node in the
browser address bar, followed by the web client port number. The default port number is 1581.

62 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 For example, to access the web client on the node that is named myserver.example.com, specify:
http://myserver.example.com:1581
If you must change the default web client port number, use the backup-archive client httpport
option to assign a different port number.

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 292
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.
“Web client options” on page 296
Several backup-archive client options are used to configure the IBM Spectrum Protect web client.
Related tasks
“Starting a web client session” on page 136
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.
Related reference
“Httpport” on page 397
The httpport option specifies a TCP/IP port address for the web client.
“Passwordaccess” on page 449
The passwordaccess option specifies whether you want to generate your password automatically or set
as a user prompt.

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:
• Display information about available schedules.
• Display information about work that the schedule completed.
• Modify scheduling options in the dsm.sys file.
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.

Chapter 2. Configure the IBM Spectrum Protect client 63

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 25. Client acceptor-managed services versus traditional scheduler services

IBM Spectrum Protect traditional scheduler
Client acceptor-managed services services
Defined by using the managedservices Started with command dsmc sched command.
schedule option and started with client acceptor
services.
The client acceptor daemon is started with the
dsmcad command

The client acceptor service starts and stops the Remains active, even after scheduled backup is
scheduler process as needed for each scheduled complete.
action.
Requires fewer system resources when idle. Requires higher use of system resources when
idle.
Client options and IBM Spectrum Protect server Client options and IBM Spectrum Protect server
override options are refreshed each time the client override options are only processed after dsmc
acceptor services start a scheduled backup. sched is started.
Cannot be used with You must restart the scheduler process for
SESSIONINITiation=SERVEROnly backups. 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

• 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.
• 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

64 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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 client scheduler:
a) From the backup-archive client GUI, select Edit > Preferences.
b) Click the Web Client tab.
c) In the Managed Services Options field, click Schedule. If you also want the client acceptor to
manage the web client, click Both option.
d) Start the client acceptor daemon by running the following command on the command line:

dsmcad

Tip:
– You can also use the managedservices option in the client system-options file (dsm.sys) to
specify whether the client acceptor manages the scheduler.
– 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.sys file.
Related concepts
“Web client configuration overview” on page 62
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.
“Enable or disable scheduled commands” on page 260
You can use the schedcmddisabled option to disable the scheduling of commands by the server.
“Scheduling options” on page 292
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.
Related tasks
“Setting the client scheduler process to run as a background task and start automatically at startup” on
page 256
You can configure the IBM Spectrum Protect client scheduler to run as a background system task that
starts automatically when your system is started.
Related reference
“Cadlistenonport” on page 320
The cadlistenonport option specifies whether to open a listening port for the client acceptor.
“Managedservices” on page 430
The managedservices option specifies whether the IBM Spectrum Protect client acceptor service
manages the scheduler, the web client, or both.
“Sessioninitiation” on page 490

Chapter 2. Configure the IBM Spectrum Protect client 65

 Use the sessioninitiation option to control whether the server or client initiates sessions through a
firewall. The default is that the client initiates sessions. You can use this option with the schedule
command.

Start the client scheduler

This task guides you through the steps to schedule events using the GUI and the command-line client.

Scheduling events using the command-line client

This task guides you through the steps to schedule events using the command-line client.

About this task

You must be a system administrator to configure the backup-archive client to use the command-line
client interface to handle scheduled events. The command-line tools must be installed to enable this
function.
Note: If you run the client scheduler on the command line, the scheduler does not run as a background
service.
Before starting the client scheduler using the client acceptor daemon, you must complete the following
steps:

Procedure
1. Ensure that the managedservices option includes schedule in the client systems options (dsm.sys)
file.
2. Set the passwordaccess option to generate in the client systems options (dsm.sys) file.

Results
If you include files for encryption processing, ensure that you select the Save Encryption Key Password
Locally option in the Authorization Preferences window so that the client scheduler can perform
unattended scheduled services without prompting the user for the encryption key. If the encryption key
has not been previously saved, you must perform an attended backup of at least one file so that the
encryption prompt is given and the key is saved.
To start the client scheduler on your client node and connect to the server schedule:
1. Change to the backup-archvie client installation directory and enter the following command:

dsmc schedule

When you start the client scheduler, it runs continuously until you close the window, end the process,
or log off your system.
2. If the client executable directory is not in your PATH environment variable, change to the installation
directory and enter the following command:

./dsmc schedule

3. To run the schedule command in the background and to keep the client scheduler running, even if
you log off your system, enter the following:

nohup dsmc schedule 2> /dev/null &

If the IBM Spectrum Protect password is required for your workstation and you want to run the
schedule command in the background, enter the password with the command.
Root User: To start the client scheduler automatically, ensure that the passwordaccess option is set to
generate in dsm.sys, then follow the procedure for your operating system:

66 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
To start each client scheduler automatically, add an entry to the /etc/inittab file. Typically, the run level to
use is 2, 3, 4, 5, or 6, depending on the operating system and its configuration. Consult documentation for
your operating system for details on run levels.
Verify the correct syntax for the entry by consulting documentation for your operating system.
Here are some examples:
For AIX, add the following entry to the /etc/inittab file:

itsm:2:once:/usr/bin/dsmc sched > /dev/null 2>&1 # TSM scheduler

In this example, the run level is set to 2.

For Solaris, add the following entry to the /etc/inittab file:

itsm:23:once:/usr/bin/dsmc sched > /dev/null 2>&1 # TSM scheduler

In this example, the run level is set to 2 and 3.

Note: You must include the redirection to /dev/null in the command.
For Mac OS X:
The system administrator must generate a password so that the client can store the password in the
password (TSM.sth) file. This can be done either with IBM Spectrum Protect Tools for Administrators or
with the command line.
A system administrator must use either of the following methods to enable the client acceptor daemon to
launch the command-line client in schedule mode to handle scheduled events when you start the system.
Method 1 (preferred)
• Use IBM Spectrum Protect Tools for Administrators and Start the Client Acceptor Daemon
applications. This installs the client acceptor daemon as a system startup item so the client
acceptor daemon starts after system restarts. The client acceptor daemon is also started
immediately, so you do not need to restart the system to handle scheduled events.
Method 2
• Use the shell script in "/Library/Application Support/tivoli/tsm/client/ba/bin" to
install the client acceptor daemon as a startup item. The script name is StartCad.sh.
Complete the following steps to start the client acceptor daemon manually, and to check that it is
running.
1. To check whether the client acceptor daemon is running, enter the following command:

sudo ps -x | grep dsmcad

If the client acceptor daemon is running, one of the processes listed has the path /usr/bin/dsmcad.
2. To start the client acceptor daemon manually, enter the following command in a terminal window:

sudo /sbin/SystemStarter start dsmcad

The client scheduler can fail to properly initialize at system startup because TCP/IP is not fully initialized.
You might need to delay the scheduler service start up to allow time for TCP/IP to initialize.
The client does not recognize changes made to the dsm.opt or the dsm.sys file while the client scheduler
is running. If you make changes to these files while the client scheduler is running, and you want to use
the new values immediately, stop the client scheduler and restart it. For example, if you change the
inclexcl option in your dsm.sys file to point to a different include-exclude options file, you must stop
the client scheduler and restart it before the client uses the new file.
To manually stop the client scheduler, use the kill command if the client scheduler is running in the
background, or press q or Ctrl+C if it is running in the foreground. To restart the client scheduler, enter
the schedule command again.

Chapter 2. Configure the IBM Spectrum Protect client 67

 Tape prompting does not occur during a scheduled event regardless of the tapeprompt option setting in
your options file.
Related tasks
“Configuring the scheduler” on page 63
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.
Related reference
“Managedservices” on page 430
The managedservices option specifies whether the IBM Spectrum Protect client acceptor service
manages the scheduler, the web client, or both.
“Passwordaccess” on page 449
The passwordaccess option specifies whether you want to generate your password automatically or set
as a user prompt.

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
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 backup-archive client GUI 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.

68 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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.
For a client scheduler setup to operate using this method, the following parameters must be set as
SESSIONINITiation=serveronly AND SESSIONSECURITY=transitional.
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, and the backup-archive client GUI still attempt to initiate
sessions, but are blocked by the IBM Spectrum Protect server for nodes that have the
sessioninitiation option set to serveronly.
3. 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.
4. 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 the backup-archive client 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 63
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.
Related reference
“Sessioninitiation” on page 490

Chapter 2. Configure the IBM Spectrum Protect client 69

 Use the sessioninitiation option to control whether the server or client initiates sessions through a
firewall. The default is that the client initiates sessions. You can use this option with the schedule
command.
“Tcpadminport” on page 522
Use the tcpadminport option to specify a separate TCP/IP port number on which the server waits for
requests for administrative client sessions, allowing secure administrative sessions within a private
network.
“Tcpport” on page 526
The tcpport option specifies a TCP/IP port address for the IBM Spectrum Protect server. You can obtain
this address from your administrator.
“Webports” on page 582
The webports option enables the use of the web client outside a firewall.

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:
• Command-line client
• Administrative command-line client
• Client GUI
• 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:
• A certificate that is self-signed by IBM Spectrum Protect.
• 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 “Configuring by
using the default security settings (fast path)” on page 125 for details.

70 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Follow these steps to enable SSL communication with a CA-signed certificate:
1. Obtain the CA root certificate.
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.
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, /opt/tivoli/tsm/server/bin/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.
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 74.
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.
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. By default, local key database files have root ownership and permissions and cannot be read by other
users. If you plan to run the client as a non-root user, you must update the permissions. For example,
to grant read access to all users and groups, run the following command:

# chmod go+r dsmcert.*

Chapter 2. Configure the IBM Spectrum Protect client 71

 5. 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.
6. 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 checkbox on
the Communication tab of the Preferences editor. Requiring TLS 1.2 helps prevent attacks by
malicious programs.
Related reference
“Ssl” on page 509
Use the ssl option to enable Secure Sockets Layer (SSL) to provide secure client and server
communications. When the backup-archive client communicates with an IBM Spectrum Protect server
V8.1.1 and earlier V8 levels, and V7.1.7 and earlier levels, it determines whether SSL is enabled. When
the backup-archive client communicates with an IBM Spectrum Protect server V8.1.2 and later levels,
and V7.1.8 and later V7 levels, SSL is always used and this option controls whether object data is
encrypted or not. For performance reasons, it might be desirable to not encrypt the object data.
“Sslfipsmode” on page 512
The sslfipsmode option specifies whether the client uses SSL Federal Information Processing
Standards (FIPS) mode for Secure Sockets Layer (SSL) communications with the server. The default is no.

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.

Before you begin

• An IBM Spectrum Protect client, V8.1.2 and later levels, and V7.1.8 and later V7 levels requires GSKit
version 8.0.50.78.
• An IBM Spectrum Protect client, V8.1.1 and earlier V8 levels, and V7.1.7 and earlier levels requires a
version of GSKit earlier than version 8.0.50.78.

72 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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:
• ln -s /usr/local/ibm/gsk8_64/lib64/C /opt/ibm/lotus/notes/90010/zlinux
• ln -s /usr/local/ibm/gsk8_64/lib64/N /opt/ibm/lotus/notes/90010/zlinux
• 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.
When other applications deliver a GSKit version that is newer than the version delivered with IBM
Spectrum Protect API, then it is better to either perform the upgrade of the Client or to perform the
following procedure.

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\Common Files\Tivoli\TSM\api64\gsk8"

rename lib64 lib64-api

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:

Chapter 2. Configure the IBM Spectrum Protect client 73

 cd "c:\Program Files\Common Files\Tivoli\TSM\api64\gsk8"

mklink /d lib64 "C:\Program Files\ibm\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:
• Entrust.net Global Secure Server Certification Authority
• Entrust.net Global Client Certification Authority
• Entrust.net Client Certification Authority
• Entrust.net Certification Authority (2048)
• Entrust.net Secure Server Certification Authority
• VeriSign Class 3 Public Primary Certification Authority
• VeriSign Class 2 Public Primary Certification Authority
• VeriSign Class 1 Public Primary Certification Authority
• VeriSign Class 4 Public Primary Certification Authority - G2
• VeriSign Class 3 Public Primary Certification Authority - G2
• VeriSign Class 2 Public Primary Certification Authority - G2
• VeriSign Class 1 Public Primary Certification Authority - G2
• VeriSign Class 4 Public Primary Certification Authority - G3
• VeriSign Class 3 Public Primary Certification Authority - G3
• VeriSign Class 2 Public Primary Certification Authority - G3
• VeriSign Class 1 Public Primary Certification Authority - G3
• Thawte Personal Premium CA
• Thawte Personal Freemail CA
• Thawte Personal Basic CA
• Thawte Premium Server CA
• Thawte Server CA
• RSA Secure Server Certification Authority
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.

74 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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.

Journal daemon configuration

Journal-based backup is enabled by installing and configuring the IBM Spectrum Protect journal daemon.
Configure the journal daemon by editing the journal daemon configuration sample file,
tsmjbbd.ini.smp, and saving it as tsmjbbd.ini. Both files should be in the default installation
directory.
After you configured the tsmjbbd.ini file, start the journal daemon by starting the tsmjbbd executable
file.
To start the journal daemon after you restart your system on AIX, run the jbbinittab script file to add
an entry to the /etc/inittab file. The tsmjbbd executable file and the jbbinittab script file should
be in the default installation directory.
To stop the journal daemon on AIX, issue the kill nnnn command, where nnnn is the process ID of
tsmjbbd. Before the journal daemon process (tsmjbbd) shuts down, it notifies the filepath kernel
extension to stop buffering file changes.
Important: Do not use the kill -9 nnnn command, because the kill -9 command immediately
ends the process without notifying filepath to stop buffering file changes.
On Linux, the installer creates the tsmjbbd service in /etc/init.d. To control the service, run the
following command as root to stop, start, or restart the service, or to check its status:
service tsmjbbd start

stop

restart

status

If the Linux operating system runs the systemd initialization service, complete the following steps to
start the journal daemon:
1. Copy the provided systemd unit file /opt/tivoli/tsm/client/ba/bin/tsmjbbd.service to
the /etc/systemd/system/ directory.
2. Run the following command to refresh the systemd unit list:

systemctl daemon-reload

3. Run the following command to start the journal daemon at system boot time:

systemctl enable tsmjbbd.service

4. Run the following command to start the journal daemon:

systemctl start tsmjbbd.service

Note:
1. Network and removable file systems are not supported.
2. Periodic full incremental backups should be performed to complement daily journal-based backups.
Full progressive incremental backups can take longer to run than a journal-based backup. Take this
information into account when you schedule them, perhaps scheduling the incremental backups
during off-peak times. Balance these two backup techniques according to your business needs. For
example, you might decide to schedule nightly journal-based backups and also schedule a weekly full
progressive incremental backup.

Chapter 2. Configure the IBM Spectrum Protect client 75

 3. Journal-based backup uses the filepath kernel extension to monitor file system changes. To improve
the performance of journal-based backups, directories that do not contain user files are not monitored
for changes and are not included in journal-based backups. The following lists the directories that are
not included in journal-based backups on AIX and Linux systems. Changes to these directories are
processed if you perform periodic full incremental backups by using the incremental command with
the -nojournal option.

AIX Linux

/bin /bin
/dev /boot
/etc /dev
/lib /etc
/usr/bin /lib
/usr/lib /proc
/usr/share /sbin
/sys
/usr/bin
/usr/lib
/usr/share
/var

The journal daemon configuration file is periodically checked for updates to the list of journaled file
systems. You can add or remove file systems from the list of monitored file systems without stopping the
journal daemon.
Attention: If you bring a file system that is being monitored by the journal daemon offline, the
journal database for that file system is deleted. To preserve the database, set
PreserveDbOnExit=1 in the journaled file systems settings stanza. This setting preserves the
journal database when it is taken offline and ensures that the journal database is valid when the
file system comes back online. For more information, see “JournaledFileSystemSettings stanza”
on page 77.
The syntax for stanza and stanza settings is as follows:
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.
3. Numeric values can be specified in hexadecimal by preceding the value with 0x; otherwise, they are
interpreted as decimal.
4. These journaled file system settings do not correlate to any settings in the client options file. The
journal daemon is an independent process; it does not process any options in the client options file.

JournalSettings stanza
Settings under this stanza are global and apply to the entire journal daemon.
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:

76 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
ErrorLog
Specifies the log file where detailed error messages generated by the journal daemon are written. The
default value is jbberror.log in the directory of the daemon executable. For example:

ErrorLog=/logs/jbberror.log

JournalDir
Directory where journal database files are stored and written.
If the path given is an absolute (for example, it begins with a dir delimiter) pathname, this is the
directory used. If the path given is a relative directory name, then this path is appended to each file
system name and the resulting path name is used.
The default is a directory named .tSm_JoUrNaL (used within each file system being journaled).
The advantage of having the journal database on the file system being monitored is that the database
stays with the file system. The disadvantage is that the updates to the database must be processed
and discarded.
Important: Directing the database to a non-journaled file system, unless this file system is shared in a
cluster environment.
This setting applies to all journaled file systems but can be overridden with an override stanza for
each journal file system.

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 file names 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 daemon only provides a subset of the INCLUDE/EXCLUDE function provided by the
backup-archive client. The journal daemon 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 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]
*.jbb.jbbdb
*.jbbInc.jbbdb

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.
File systems that you specify in the JournalFileSystems.Extended stanza override any file systems
specified in the list of journaled file systems that you might have previously specified in the

Chapter 2. Configure the IBM Spectrum Protect client 77

 JournaledFileSystemSettings stanza. Any other options that you have specified in the
JournaledFileSystemsSettings stanza are preserved.
The syntax for the JournaledFileSystemSettings stanza is as follows:
Syntax for JournaledFileSystemSettings stanza:
[JournaledFileSystemSettings]
Syntax for stanza settings:
JournaledFileSystemSetting=value
You can specify the following JournaledFileSystemSettings values:
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 daemon to run. Journaled file systems can be added or removed online without having
to restart the daemon. For example:

JournaledFileSystems=/home /other

Important: The journal selects object names based strictly on a string match. The implication for the
user is that care must be taken when selecting file systems to journal. For example, suppose you have
a file system /jbb and another file system called /jbb/mnt1. If you ask the journal to monitor just /
jbb, then all the changes for /jbb/mnt1 also match this string and are entered in the database.
When, however, you do a back up on the client, it parses the name based on file systems, realizes the
journal is not monitoring this file system and then tells the journal to remove the /jbb/mnt1 files
from the database. The solution is to either monitor both or use the JournalExcludeList. The same is
true for the virtual mount point options. You must be consistent with this list. For example, if you
specify /home/student1 as a virtual mount point in your dsm.sys option file and you want to
journal /home, then you must specify JournaledFileSystems=/home /home/student1. In this
case, two separate databases are created.
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, DirNotifyBufferSize
Specify change notification buffer sizes for a journaled file system. A large amount of change activity
on a journaled file system might require this to be increased. The default is 0x00020000 (128 k) for
files and 0x00010000 ( 64 k) for directories.

NotifyBufferSize=0x00200000

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, and resource movement.
This setting allows a journal-based backup to continue processing when the daemon is restarted (or
the file system comes back online) without performing a full incremental backup.
Note: Any change activity which occurs while the journal daemon is not running (or the file system is
offline) is not recorded in the journal.
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.

78 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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.
Note: Set PreserveDBonExit only when you can ensure that there is a controlled shutdown of the
journal service. The scope of "controlled shutdown" includes stopping the journal service in order to
reboot the system, failing over a cluster resource, or moving a cluster resource. The journal database
can become corrupted if the shutdown is not controlled. Therefore, perform the following steps if the
journal service was not shut down in a controlled manner or if the journal database was otherwise
taken offline in an uncontrolled manner.
1. Stop the journal service (if it is running)
2. Delete the corrupted journal databases
3. Restart the journal service
4. Perform an incremental backup
An example for not deleting the journal database upon exit is:

preserveDBOnExit=1

deferFSMonStart setting
This setting defers an attempt to begin monitoring a file system in the following cases:
• When the specified journaled file system is not valid or available
• 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.
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 deferred file systems with the deferRetryInterval
setting enabled are checked for availability and brought online. The default value is 5 seconds.
logFSErrors setting
A value of 1 indicates that all errors encountered accessing a journaled file system or journal directory
should be logged. A value of zero indicates that logging of errors encountered while checking deferred
file systems and journal directories is suppressed. This is usually used in conjunction with the
deferFSMonStart setting to eliminate excessive File System Unavailable messages from being
written to the logs when bringing a journaled file system online is deferred. The default value is 1 (log
all errors).
Related concepts
“Overriding stanzas” on page 80
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.
“JournaledFileSystems.Extended stanza” on page 79
The JournaledFileSystems.Extended stanza overrides any file systems that are included in the
JournaledFileSystems stanza. It also removes the 1023 character limitation imposed by the
JournaledFileSystem stanza.

JournaledFileSystems.Extended stanza
The JournaledFileSystems.Extended stanza overrides any file systems that are included in the
JournaledFileSystems stanza. It also removes the 1023 character limitation imposed by the
JournaledFileSystem stanza.
If you include file systems in the JournaledFileSystems stanza, the total number of characters allowed in
that stanza is 1023 characters. For large configurations with many file systems, the 1023 character limit
is too small to specify all file systems. If you must use more that 1023 characters to include all file

Chapter 2. Configure the IBM Spectrum Protect client 79

 systems that you want included in journal-based backups, specify the file systems in the
JournaledFileSystems.Extended stanza. This extended stanza does not impose the 1023 character
limitation. Values in JournaledFileSystems.Extended override any value specified in the other stanza. If a
file system is specified in both the JournaledFileSystems stanza and the JournaledFileSystems.Extended
stanza, the file system specified in the JournaledFileSystems stanza is ignored.
The syntax for JournaledFileSystems.Extended has a simple list form. The file systems that you want to
be included in journal-based backups by editing the journal daemon configuration file (the default name is
tmsjbbd.ini).
Syntax for JournaledFileSystems.Extended stanza:
[JournaledFileSystems.Extended]
Syntax for stanza settings:

/filesystem_1
/filesystem_2
.
.
/filesystem_n

List each file system that you want included in journal-based backups.

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.
HookFileName
In order for the journal to begin monitoring a file system, it must know the name of an existing file in
that file system. This setting specifies an existing file. Access to this file is then used as a test of
whether or not this file system is online. (The system definition of mounted cannot be used because
we allow the use of virtual mount points in the backup-archive client. This means that the backup-
archive client system can treat a directory as a (virtual) file system).
Therefore, if this file system can be mounted and unmounted, a HookFileName needs to be
provided.
If a HookFileName is not entered, the journal daemon attempts to create a temporary file in the
highest directory, use it to begin monitoring, and then delete it.
The following is the syntax for the JournaledFileSystemSettings stanza:
Syntax for JournaledFileSystemSettings stanza:
[JournaledFileSystemSettings.fs]
Syntax for stanza settings:
JournaledFileSystemSetting=override value
For example, the override stanza name for /home would be:

JournaledFileSystemSettings./home
HookFileName=/home/doNotDeleteThisFile

Client-side data deduplication

Data deduplication is a method of reducing storage needs by eliminating redundant data.

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

80 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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:
• Exclude specific files on a client from data deduplication.
• 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.
• 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:

• The client creates extents. Extents are parts of files that are compared with other file extents to identify
duplicates.
• The client and server work together to identify duplicate extents. The client sends non-duplicate
extents to the server.
• 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.

Benefits
Client-side data deduplication provides several advantages:
• It can reduce the amount of data that is sent over the local area network (LAN).
• 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.
• 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.

Chapter 2. Configure the IBM Spectrum Protect client 81

 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:
• The client and server must be at version 6.2.0 or later. The latest maintenance version should always be
used.
• 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 or container storage pool
that is enabled for data deduplication.
• 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.
• 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.
• 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.
• Files on the client must not be encrypted. Encrypted files and files from encrypted file systems cannot
be deduplicated.
• 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:
• LAN-free data movement
• Simultaneous-write operations
• Data encryption

82 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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 26 on page 83.

Table 26. Data deduplication settings: Client and server

Value of the client Data deduplication
DEDUPLICATION option Setting on the server 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.
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:
• Enable storage-device encryption together with client-side data deduplication.
• Use client-side data deduplication only for nodes that are secure.
• If you are uncertain about network security, enable Secure Sockets Layer (SSL).
• 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.
• 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” on page 84
Configure the client so that you can use data deduplication to back up or archive your files.
Related reference
“Deduplication” on page 338
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.
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.
“Dedupcachepath” on page 337
Use the dedupcachepath option to specify the location where the client-side data deduplication cache
database is created.
“Dedupcachesize” on page 338

Chapter 2. Configure the IBM Spectrum Protect client 83

 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.
“Enablededupcache” on page 365
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.
“Ieobjtype” on page 399
Use the ieobjtype option to specify an object type for a client-side data deduplication operation within
include-exclude statements.

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 80 are met:
• 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.
• The storage pool destination for the data must be a data deduplication-enabled storage pool.
• Ensure that your files are bound to the correct management class.
• 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.

Procedure
Use one of the following methods to enable data deduplication on the client:
Option Description
Edit the client options • Add the deduplication yes option to the dsm.sys file.
file
Preferences editor a. From the IBM Spectrum Protect window, click Edit > Client Preferences.
b. Click Deduplication.
c. Select the Enable Deduplication check box.
d. 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.
• Add the deduplication yes option to the dsm.sys 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:

84 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • Add the ENABLEDEDUPCACHE NO option to the dsm.sys 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.............: SERVER1

Server Type.............: Windows
Archive Retain Protect..: "No"
Server Version..........: Ver. 6, Rel. 2, Lev. 0.0
Last Access Date........: 08/25/2009 13:38:18
Delete Backup Files.....: "No"
Delete Archive Files....: "Yes"
Deduplication...........: "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:

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........: STANDARD

Copy Type..............: Archive
Copy Frequency.........: Cmd
Retain Version.........: 365 day(s)
Copy Serialization.....: Shared Static
Copy Mode..............: Absolute
Retain Initiation......: Create
Retain Minimum.........: 65534 day(s)
Copy Destination.......: FILEPOOL
Lan Free Destination...: NO
Deduplicate Data.......: YES

ANS1900I Return code is 0.

Related concepts
“Client-side data deduplication” on page 80

Chapter 2. Configure the IBM Spectrum Protect client 85

 Data deduplication is a method of reducing storage needs by eliminating redundant data.
Related reference
CLIENTDEDUPTXNLIMIT option
REGISTER NODE command
UPDATE NODE (Update node attributes)
“Deduplication” on page 338
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.
“Enablededupcache” on page 365
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.
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.

Excluding files from data deduplication

You can exclude a file from data deduplication during backup or archive processing.

About this task

You can exclude only files for archive data deduplication. You can exclude files and images (where
applicable) 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.
• To exclude a file from data deduplication during archive processing, select Archive in the Category
list.
• 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.
• For archive processing, only the File object type is available.
• For backup processing, select one of the following object types:
– File
– Image
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.
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.

86 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 What to do next
You can also exclude files from data deduplication processing by editing the dsm.sys file:
1. Add the deduplication yes option.
2. Exclude the files in a directory from data deduplication. For example, to exclude the files in the /Users/
Administrator/Documents/Taxes/ directory, add the following statement: EXCLUDE.dedup /Users/
Administrator/Documents/Taxes/.../*
3. Exclude client-side data deduplication for image backup of a file system. For example, to exclude the /
home file system, add the following statement: EXCLUDE.DEDUP /home/*/* IEOBJTYPE=Image.
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
“Client-side data deduplication” on page 80
Data deduplication is a method of reducing storage needs by eliminating redundant data.
Related reference
“Deduplication” on page 338
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.
“Enablededupcache” on page 365
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.
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.

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
When the client fails over to the secondary server, you can restore or retrieve replicated data from the
secondary server.

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 this 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 this server.

Chapter 2. Configure the IBM Spectrum Protect client 87

 Each time the client logs on to the 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 that secondary server is sent to the
client and saved to the client system options file (dsm.sys):

*** 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

MYREPLICATIONServer TARGET
*** 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:
• The primary server, secondary server, and backup-archive client must be running IBM Spectrum Protect
Verson 7.1, or a later version.
• The primary and secondary servers must be set up for node replication.
• 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.
• 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.
• 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.
• 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.
• 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 444.
• 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.
• 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

88 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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.

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:
• 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.
• Schedules are not replicated to the secondary server. Therefore, schedules are not run while the
primary server server is unavailable.
• 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.
• 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.
• 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.
• 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 web
client.
• 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.

Chapter 2. Configure the IBM Spectrum Protect client 89

 – 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
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.

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:
• Ensure that the client node participates in node replication on the primary server.
Note: If the replication server is V8.1.1 or earlier, and SSL is enabled, you must manually install the SSL
certificate on the client with the following command: gsk8capicmd_64 -cert -add -db
dsmcert.kdb -stashed -label "TSM server STSM01 self-signed key" -file
<certificate_file> -format ascii Where <certificate_file> is the path to the corresponding
certificate.
• Ensure that the client meets the requirements for automated client failover.
• 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:
• 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.
• 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.

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.

90 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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.sys file:

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

SErvername server_a
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname1.example.com
PASSWORDAccess prompt
MYREPLICATIONServer TARGET

3. Non-root users must specify a location for the node replication table by adding the nrtablepath
option to the dsm.sys file. The backup-archive client uses this table to store information about each
backup or archive operation to the IBM Spectrum Protect server.
You must specify a location that your user ID has write access to. For example:

nrtablepath /Volumes/nrtbl

Restriction: Do not specify the root directory (/) for the location of the node replication table.
4. Save and close the client options file.
5. 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
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.
Related tasks
Restoring or retrieving data during a failover

Chapter 2. Configure the IBM Spectrum Protect client 91

 When the client fails over to the secondary server, you can restore or retrieve replicated data from the
secondary server.
Related reference
Forcefailover
The forcefailover option enables the client to immediately fail over to the secondary server.
Myreplicationserver
The myreplicationserver option specifies which secondary server stanza that the client uses during a
failover.
Nrtablepath
The nrtablepath option specifies the location of the node replication table on the client. The backup-
archive client uses this table to store information about each backup or archive operation to the IBM
Spectrum Protect server.
Replserverguid
The replserverguid option specifies the globally unique identifier (GUID) that is used when the client
connects to the secondary server during failover. The GUID is used to validate the secondary server to
ensure that it is the expected server.
Replservername
The replservername option specifies the name of the secondary server that the client connects to
during a failover.
Replsslport
The replsslport option specifies the TCP/IP port on the secondary server that is SSL-enabled. The
replsslport option is used when the client connects to the secondary server during a failover. This
option is deprecated if you are connecting to an IBM Spectrum Protect server V8.1.2 and later levels, and
V7.1.8 and later V7 levels.
Repltcpport
The repltcpport option specifies the TCP/IP port on the secondary server to be used when the client
connects to the secondary server during a failover.
Repltcpserveraddress
The repltcpserveraddress option specifies the TCP/IP address of the secondary server to be used
when the client connects to the secondary server during a failover.
Usereplicationfailover
The usereplicationfailover option specifies whether automated client failover occurs on a client
node.

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
dsmc query filespace -detail

92 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 The following sample output shows that the time stamps on the server and the client match, therefore the
replication status is current:

# Last Incr Date Type fsID Unicode Replication File Space Name
--- -------------- ------- ---- ------- ----------- ---------------
1 00/00/0000 00:00:00 HFS 9 Yes Current /

Last Store Date Server Local

--------------- ------ -----
Backup Data : 04/22/2013 19:39:17 04/22/2013 19:39:17
Archive Data : No Date Available 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:

# Last Incr Date Type fsID Unicode Replication File Space Name
--- -------------- ------- ---- ------- ----------- ---------------
1 00/00/0000 00:00:00 HFS 9 Yes Not Current /

Last Store Date Server Local

--------------- ------ -----
Backup Data : 04/22/2013 19:39:17 04/24/2013 19:35:41
Archive Data : No Date Available 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
When the client fails over to the secondary server, you can restore or retrieve replicated data from the
secondary server.
Related reference
Nrtablepath
The nrtablepath option specifies the location of the node replication table on the client. The backup-
archive client uses this table to store information about each backup or archive operation to the IBM
Spectrum Protect server.

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.

Chapter 2. Configure the IBM Spectrum Protect client 93

 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
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.
Related reference
Usereplicationfailover
The usereplicationfailover option specifies whether automated client failover occurs on a client
node.

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.

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-system options file (dsm.sys).
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:
• Check the Secondary Server Information field in the Connection Information window in the backup-
archive client GUI.
• 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 392
The forcefailover option enables the client to immediately fail over to the secondary server.

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 http://www.ibm.com/support/knowledgecenter/
SS9NU9/.
After you install the FastBack client, complete the following tasks:
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.

94 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 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:
• Backup-archive client on the FastBack server
• Backup-archive client on the FastBack Disaster Recovery Hub
• Backup-archive client on a dedicated proxy workstation
For information about integrating IBM Spectrum Protect and Tivoli Storage Manager FastBack, see
Integrating and .
Related concepts
“Installation requirements for backing up and archiving Tivoli Storage Manager FastBack client data” on
page 8
Before you can back up or archive your FastBack client data, you must install the required software.
Related reference
“Set Password” on page 706
The set password command changes the IBM Spectrum Protect password for your workstation, or sets
the credentials that are used to access another server.

Cluster environment configuration and use

The term cluster has different meanings in different environments. It can mean highly available, high
performance, load balancing, grid computing, or some combination of all of these terms.
There are currently several clustering products available for UNIX and Linux, and this section defines
those aspects of a clustering environment that need to exist in order for this backup methodology to work
correctly. A basic understanding of how your cluster software functions is needed. Cluster software
related activities such as the development of application start and stop scripts are not described in this
section.
A cluster environment refers to a UNIX or a Linux environment which exhibits the following
characteristics:

Chapter 2. Configure the IBM Spectrum Protect client 95

 • Disks are shared between physical workstations, either in an exclusive fashion (only one host has
access to the logical disk at any one time) or in a concurrent fashion.
• Disks appear as local disks to the host and not as network resources.
Important: Mount the file systems locally to the system, not through a LAN-based file share protocol
such as network file system (NFS).
• Mount points of local disks are identical on each physical host in the environment (if file system /
group1_disk1 fails from NodeA to NodeB, it is mounted on NodeB as /group1_disk1).

Overview of cluster environments

Cluster environments can be set up in many different configurations. This section describes the most
popular cluster configurations.

Active/Active: Pool cluster resources

In an active/active configuration, each node is actively managing at least one resource and is configured
as a backup for one or more resources in the cluster. Active/active is the most common form of a cluster
environment.

Active/Passive: Fault tolerant

In an active/passive configuration, one node actively manages the resource.
The other node is only used if the primary node experiences a fault and the resource needs to failover. An
active/passive cluster is a subtype of an active/active cluster.

Concurrent access
In a concurrent configuration, more than one node manages a resource. When a fault occurs, the resource
continues to be managed by the other nodes.

Configuring the backup-archive client in a cluster environment

The backup-archive client is designed to manage the backup of cluster drives by placing the backup-
archive client within the context of the cluster's resource groups.

About this task

This gives the advantage of backing up data from local resources (as opposed to accessing the data
across the network) to maximize the performance of the backup operation and to manage the backup
data relative to the resource group. Therefore, the backup-archive client can always back up data on
cluster resources as if the data were local data and maximize backup performance. This ensures that
critical data is getting backed up across system failures.
For example, an active/active cluster environment has three physical hosts in the cluster named NodeA,
NodeB, and NodeC.
The nodes have the following qualities:
• NodeA owns the cluster resource with file systems /A1 and /A2
• NodeB owns the cluster resources with file systems /B1 and /B2
• NodeC owns the cluster resources with file systems /C1 and /C2
Note: NodeA might also have two non-clustered volumes, /fs1 and /fs2, that must be backed up.
For best backup performance, you might want all nodes in the cluster to perform the backups of the
shared file systems that they own. When a node failover occurs, the backup tasks of the failed node shift
to the node to which the failover occurred. For example, when NodeA fails over to NodeB, the backup
of /A1 and /A2 moves to NodeB.
The following are prerequisites before configuring the backup-archive client to back up cluster and non-
cluster volumes:
• A separate backup-archive client scheduler process must be run for each resource group being
protected. In normal conditions, each node would have two scheduler processes: one for the cluster

96 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 resources, and one for the local file systems. After a failure, additional scheduler processes are started
on a node in order to protect the resources that have moved over from another node.
• The backup-archive client password files must be stored on cluster disks so that after a failure, the
generated backup-archive client password is available to the takeover node.
• The file systems to be protected as part of a resource group are defined using the backup-archive client
domain option. The domain option is specified in the dsm.sys file, which should also be stored on a
cluster disk so that it can be accessed by the takeover node.
Follow the steps below to configure the backup-archive client in a cluster environment.

Procedure
1. Register backup-archive client node definitions on the IBM Spectrum Protect server. All nodes in the
cluster must be defined on the IBM Spectrum Protect server. If you are defining multiple cluster
resources in a cluster environment to failover independently, then unique node names must be
defined per resource group. For the above sample three-way active/active cluster configuration,
define three nodes (one per resource), as follows: (1) Protect: IBM>register node nodeA
nodeApw domain=standard, (2) Protect: IBM>register node nodeB nodeBpw
domain=standard, (3) Protect: IBM>register node nodeC nodeCpw domain=standard.
2. Configure the backup-archive client system-options file. Each node in the cluster must have separate
server stanzas for each cluster resource group in order to be backed up in each respective dsm.sys
file. You must ensure that the server stanzas are identical in the system option files on each node.
Alternatively, you can place the dsm.sys file on a shared cluster location. The server stanzas defined
to back up clustered volumes must have the following special characteristics:
• The nodename option must refer to the client node name registered on the IBM Spectrum Protect
server. If the client node name is not defined, the node name defaults to the host name of the
node, which might conflict with other node names used for the same client system.
Important: Use the nodename option to explicitly define the client node.
• The tcpclientaddress option must refer to the service IP address of the cluster node.
• The passworddir option must refer to a directory on the shared volumes that are part of the
cluster resource group.
• The errorlogname and schedlogname options must refer to files on the shared volumes that are
part of the cluster resource group to maintain a single continuous log file.
• All include exclude statements must refer to files on the shared volumes that are part of the cluster
resource group.
• If you use the inclexcl option, it must refer to a file path on the shared volumes that are part of
the cluster group.
• The stanza names identified with the servername option must be identical on all systems.
3. Other backup-archive client options can be set as needed. In the following example, all three nodes,
NodeA, NodeB, and NodeC, must have the following three server stanzas in their dsm.sys file:

Servername server1_nodeA
nodename NodeA
commmethod tcpip
tcpport 1500
tcpserveraddress server1.example.com
tcpclientaddres nodeA.example.com
passwordaccess generate
passworddir /A1/tsm/pwd
managedservices schedule
schedlogname /A1/tsm/dsmsched.log
errorlogname /A1/tsm/errorlog.log

Servername server1_nodeB
nodename NodeB
commmethod tcpip
tcpport 1500
tcpserveraddress server1.example.com
tcpclientaddres nodeB.example.com
passwordaccess generate

Chapter 2. Configure the IBM Spectrum Protect client 97

 passworddir /B1/tsm/pwd
managedservices schedule
schedlogname /B1/tsm/dsmsched.log
errorlogname /B1/tsm/errorlog.log

Servername server1_nodeC
nodename NodeC
commmethod tcpip
tcpport 1500
tcpserveraddress server1.example.com
tcpclientaddres nodeC.example.com
passwordaccess generate
passworddir /C1/tsm/pwd
managedservices schedule
schedlogname /C1/tsm/dsmsched.log
errorlogname /C1/tsm/errorlog.log

4. Configure the backup-archive client user-options file. The options file (dsm.opt) must reside on the
shared volumes in the cluster resource group. Define the DSM_CONFIG environment variable to refer
to this file. Ensure that the dsm.opt file contains the following settings:
• The value of the servername option must be the server stanza in the dsm.sys file which defines
parameters for backing up clustered volumes.
• Define the clustered file systems to be backed up with the domain option.
Note: Ensure that you define the domain option in the dsm.opt file or specify the option in the
schedule or on the backup-archive client command line. This is to restrict clustered operations to
cluster resources and non-clustered operations to non-clustered resources.
In the example, nodes NodeA, NodeB, and NodeC set up their corresponding dsm.opt file and
DSM_CONFIG environment variable as follows:

NodeA:

1) Set up the /A1/tsm/dsm.opt file:

servername server1_nodeA
domain /A1 /A2

2) Issue the following command or include it in your user profile:

export DSM_CONFIG=/A1/tsm/dsm.opt

NodeB:

1) Set up the /B1/tsm/dsm.opt file:

servername server1_nodeB
domain /B1 /B2

2) Issue the following command or include it in your user profile:

export DSM_CONFIG=/B1/tsm/dsm.opt

NodeC:

1) Set up the /C1/tsm/dsm.opt file:

servername server1_nodeC
domain /C1 /C2

2) Issue the following command or include it in your user profile:

export DSM_CONFIG=/C1/tsm/dsm.opt

5. Set up the schedule definitions for each cluster resource group. After the basic setup is completed,
define the automated schedules to back up cluster resources to meet the backup requirements. The
procedure illustrates the schedule setup by using the built-in IBM Spectrum Protect scheduler. If you
are using a vendor-acquired scheduler, refer to the documentation provided by the scheduler vendor.
• Define a schedule in the policy domain where cluster nodes are defined. Ensure that the schedule's
startup window is large enough to restart the schedule on the failover node in case of a failure and
fallback event. This means that the schedule's duration must be set to longer than the time it takes
to complete the backup of the cluster data for that node, under normal conditions.

98 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 If the reconnection occurs within the start window for that event, the scheduled command is
restarted. This scheduled incremental backup reexamines files sent to the server before the
failover. The backup then "catches up" to where it stopped before the failover situation.
In the following example, the clus_backup schedule is defined in the standard domain to start
the backup at 12:30 A.M. every day with the duration set to two hours (which is the normal backup
time for each node's data).

Protect: IBM>define schedule standard clus_backup action=incr

starttime=00:30 startdate=TODAY Duration=2

• Associate the schedule with the all of the backup-archive client nodes defined to backup cluster
resources, as follows: (1) Protect: IBM>define association standard clus_backup
nodeA, (2) Protect: IBM>define association standard clus_backup nodeB, (3)
Protect: IBM>define association standard clus_backup nodeC.
6. Set up the scheduler service for backup. On each client node, a scheduler service must be configured
for each resource that the node is responsible for backing up, under normal conditions. The
DSM_CONFIG environment variable for each resource scheduler service must be set to refer to the
corresponding dsm.opt file for that resource. For the sample configuration, the following shell
scripts must be created to allow dsmcad processes to be started, as needed, from any node in the
cluster.

NodeA: /A1/tsm/startsched
#!/bin/ksh
export DSM_CONFIG=/A1/tsm/dsm.opt
dsmcad
NodeB: /B1/tsm/startsched
#!/bin/ksh
export DSM_CONFIG=/B1/tsm/dsm.opt
dsmcad
NodeC: /C1/tsm/startsched
#!/bin/ksh
export DSM_CONFIG=/C1/tsm/dsm.opt
dsmcad

7. Define the backup-archive client to the cluster application. To continue the backup of the failed
resource after a failover condition, the IBM Spectrum Protect scheduler service (for each cluster
client node) must be defined as a resource to the cluster application in order to participate in the
failover processing. This is required in order to continue the backup of the failed resources from the
node that takes over the resource. Failure to do so would result in the incomplete backup of the failed
resource. The sample scripts in step 5 can be associated with the cluster resources to ensure that
they are started on nodes in the cluster while the disk resources being protected move from one
node to another. The actual steps required to set up the scheduler service as a cluster resource are
specific to the cluster software. Refer to your cluster application documentation for additional
information.
8. Ensure that the password for each node is generated and cached correctly in the location specified
using the passworddir option. This can be validated by performing the following steps:
a) Validate that each node can connect to the IBM Spectrum Protect server without the password
prompt. You can do this by running the backup-archive client command line interface and issuing
the following command on each node:

#dsmc query session

If you are prompted to submit your password, enter the password to run the command
successfully and rerun the command. The second time, the command should run without the
prompt for the password. If you get prompted for the password, check your configuration.
b) Validate that the other nodes in the cluster can start sessions to the IBM Spectrum Protect server
for the failed-over node. This can be done by running the same commands, as described in the
step above, on the backup nodes. For example, to validate if NodeB and NodeC can start a session
as NodeA in the failover event without prompting for the password, perform the following
commands on NodeB and NodeC

Chapter 2. Configure the IBM Spectrum Protect client 99

 #export DSM_CONFIG=/A1/tsm/dsm.opt
#dsmc query session

The prompt for the password might appear at this time, but this is unlikely. If you are prompted,
the password was not stored in the shared location correctly. Check the passworddir option
setting used for NodeA and follow the configuration steps again.
c) Ensure that the schedules are run correctly by each node. You can trigger a schedule by setting
the schedule's start time to now. Remember to reset the start time after testing is complete.

Protect: IBM>update sched standard clus_backup starttime=now

d) Failover and fallback between nodeA and nodeB, while nodeA is in the middle of the backup and
the schedule's start window, is still valid. Verify that the incremental backup continues to run and
finish successfully after failover and fallback.
e) Issue the command below to cause a node's (nodeA) password to expire. Ensure that backup
continues normally under normal cluster operations, as well as failover and fallback:

Protect: IBM>update node nodeA forcep=yes

9. Configure the backup-archive client to back up local resources.

a) Define client nodes on the IBM Spectrum Protect server. Local resources should never be backed
up or archived using node names defined to back up cluster data. If local volumes that are not
defined as cluster resources are backed up, separate node names (and separate client instances)
must be used for both non-clustered and clustered volumes.
In the following example, assume that only NodeA has local file systems /fs1 and /fs2 to be
backed up. In order to manage the local resources, register a node NodeA_local on the IBM
Spectrum Protect server: Protect: IBM>register node nodeA_local nodeA_localpw
domain=standard.
b) Add a separate stanza in each node's system options file dsm.sys that must back up local
resources with the following special characteristics:
• The value of the tcpclientaddress option must be the local host name or IP address. This is
the IP address used for primary traffic to and from the node.
• If the client backs up and restores non-clustered volumes without being connected to the
cluster, the value of the tcpclientaddress option must be the boot IP address. This is the IP
address used to start the system (node) before it rejoins the cluster:

Example stanza for NodeA_local:

Servername server1_nodeA_local
nodename nodeA_local
commmethod tcpip
tcpport 1500
tcpserveraddress server1.example.com
tcpclientaddres nodeA_host.example.com
passwordaccess generate
managedservices schedule

c) Define the user options file dsm.opt in a path that is on a non-clustered resource.
• The value of the servername option must be the server stanza in the dsm.sys file which defines
parameters for backing up non-clustered volumes.
• Use the domain option to define the non-clustered file systems to be backed up.
Note: Ensure that you define the domain option in the dsm.opt file or specify the option in the
schedule or on the backup-archive client command line, in order to restrict the backup-archive
operations to non-clustered volumes.
In the following example, nodeA uses the following /home/admin/dsm.opt file and sets up the
DSM_CONFIG environment to refer to /home/admin/A1.dsm.opt.

100 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Contents of /home/admin/A1.dsm.opt

servername ibm_nodeA_local
domain /fs1 /fs2

export DSM_CONFIG=/home/admin/A1.dsm.opt

d) Define and set up a schedule to perform the incremental backup for non-clustered file systems.

Protect: IBM>define schedule standard local_backup action=incr

starttime=00:30 startdate=TODAY Duration=2

Associate the schedule with all of the backup-archive client nodes that are defined to backup non-
clustered resources.

Protect: IBM>define association standard nodeA_local

10. Restore cluster file system data. All volumes in a cluster resource are backed up under the target
node defined for that cluster resource. If you need to restore the data that resides on a cluster
volume, it can be restored from the client node that owns the cluster resource at the time of the
restore. The backup-archive client must use the same user options file (dsm.opt) that was used
during the backup to restore the data. There are no additional setup requirements necessary to
restore data on cluster volumes.
11. Restore local file system data. The non-clustered volumes are backed up under the separate node
name setup for non-clustered operations. In order to restore this data, the backup-archive client
must use the same user options file dsm.opt that was used during the backup. In the example, set
environment variable DSM_CONFIG to refer to /home/admin/A1.dsm.opt prior to performing a
client restore for the local node nodeA_local.
Related concepts
“Restoring your data” on page 213
Use IBM Spectrum Protect to restore backup versions of specific files, a group of files with similar names,
or entire directories.

Enabling web client access in a Cluster Environment

If IBM Spectrum Protect web client access is needed during a failover condition, you must configure the
web client acceptor daemon that is associated with the cluster to failover along with the cluster resource.

Before you begin

Beginning with IBM Spectrum Protect Version 8.1.2, you can no longer use the web client GUI to connect
to the IBM Spectrum Protect V8.1.2 or later server. For more information, see “Using the web client in the
new security environment” on page 136.

About this task

After you have completed the configuration steps described in the Configuring the backup-archive client in
a cluster environment section, perform the additional steps described below to complete the web client
access setup:

Procedure
1. Set up the client acceptor daemon to manage the web client and scheduler. The client acceptor
daemon should be set up to manage schedulers as well as web client access. This reduces the number
of daemons that need to be configured as cluster applications and thus simplifies the configuration
and administration. When a failover occurs, the client acceptor starts on the node that is managing the
takeover.
2. Update the managedservices option in the system-options file dsm.sys on each node for each
server stanza, as shown below for NodeA

Chapter 2. Configure the IBM Spectrum Protect client 101

 Servername server1_NodeA
nodename NodeA
commmethod tcpip
tcpp 1500
tcps server1.example.com
tcpclientaddres nodeA.example.com
passwordaccess generate
passworddir /A1/tsm/pwd
schedlogn /A1/tsm/dsmsched.log
errorlogname /A1/tsm/errorlog.log
managedservices webclient schedule

3. Set up the client acceptor daemon to use a known HTTP port. By default, the client acceptor daemon
uses HTTP port 1581, when available, for the web client access. If this port is not available, the client
acceptor finds the first available port, starting with 1581. In a failover condition of an active-active
cluster configuration, a failover cluster host system is probably running multiple instances of the client
acceptor. If default settings are used for the HTTP port, the failover node uses any available port for
the client acceptor being failed over, since the default port is probably in use by the current client
acceptor processes of the failover host. This causes problems for the web client associated with the
client acceptor that failed over, as the new HTTP port is not known to the web client users. You might
use the httpport option to specify the specific ports for the web client access for each resource. This
allows you to always use the same port when connecting from a web browser, independent of the
node serving the cluster resource. Add the httpport option in the system-options file (dsm.sys) on
each node for each server stanza as follows, making sure that each stanza uses a unique value:

Servername server1_NodeA
nodename NodeA
commmethod tcpip
tcpp 1500
tcps server1.example.com
tcpclientaddres nodeA.example.com
passwordaccess generate
passworddir /A1/tsm/pwd
managedservices webclient schedule
schedlogn /A1/tsm/dsmsched.log
errorlogname /A1/tsm/errorlog.log
httpport 1510

Servername server1_NodeB
nodename NodeB
commmethod tcpip
tcpp 1500
tcps server1.example.com
tcpclientaddres nodeB.example.com
passwordaccess generate
passworddir /B1/tsm/pwd
managedservices webclient schedule
schedlogn /B1/tsm/dsmsched.log
errorlogname /B1/tsm/errorlog.log
httpport 1511

Servername server1_NodeC
nodename NodeC
commmethod tcpip
tcpp 1500
tcps server1.example.com
tcpclientaddres nodeC.example.com
passwordaccess generate
passworddir /C1/tsm/pwd
managedservices webclient schedule
schedlogn /C1/tsm/dsmsched.log
errorlogname /C1/tsm/errorlog.log
httpport 1512

102 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Migrating legacy AIXIBM PowerHA SystemMirror setups
If you are currently using the backup-archive client in an IBM PowerHA SystemMirror environment using
the clusternode option, you must update your current configurations. The clusternode option is no
longer supported.

About this task

Perform the following steps to update your current configurations:

Procedure
1. Update the backup-archive client system-options file. As with the clusternode option, each node in
the cluster must continue to have separate server stanzas for each cluster resource group to be
backed up in each respective dsm.sys file. The existing dsm.sys file for NodeA might appear as
follows:

Servername server1_nodeA
commmethod tcpip
tcpp 1500
tcps server1.example.com
tcpclientaddres nodeA.example.com
passwordaccess generate
passworddir /A1
clusternode yes
managedservices schedule
schedlogn /A1/dsmsched.log
errorlogname /A1/errorlog.log

2. Notice that no nodename option is used in this sample. Make the following changes to the existing
dsm.sys file for NodeA.
• Remove the clusternode option.
• Specify a nodename option if you do not have one already specified.
3. The new dsm.sys file for NodeA should appear as follows:

Servername server1_nodeA
commmethod tcpip
nodename myclus (myclus is the existing cluster name )
tcpp 1500
tcps server1.example.com
tcpclientaddres nodeA.example.com
passwordaccess generate
passworddir /A1
managedservices schedule
schedlogn /A1/dsmsched.log
errorlogname /A1/errorlog.log

4. Register backup-archive client nodes on the IBM Spectrum Protect server. If new backup-archive
client nodes are added in the first step to replace the current default value of the cluster node name,
register those nodes on the IBM Spectrum Protect server.
5. Update schedule definitions. If new backup-archive client nodes are added in the previous step,
ensure that the backup schedule definitions used earlier to back up this node's data are now
associated with the new client node names.
6. Validate the setup. For more information, see “Configuring the backup-archive client in a cluster
environment” on page 96

Chapter 2. Configure the IBM Spectrum Protect client 103

AIX configuration considerations prior to performing snapshot-based file
backups and archives
If you are configuring your IBM Spectrum Protect AIX client to perform snapshot-based file backups and
archives, there are some items that you need to consider.
• Ensure that the volume group containing the file system to be snapshot has sufficient disk space to
allow JFS2 external snapshots to be created for the file system.
• The client uses a default size of 100 percent of the file system size for the snapshot size. This value was
found to be most appropriate for file systems with even moderate file system activity. If you need to
lower this value based on your experience with your own file system activity, you can use the
snapshotcachesize option to fine-tune this value.
• Do not enable internal snapshots when creating new JFS2 file systems on AIX 6.1 or later for all file
systems managed by IBM Spectrum Protect. The client uses external snapshots and JFS2 does not
allow the creation of external and internal snapshots concurrently for the same file system.
Related reference
“Snapshotcachesize” on page 502
Use the snapshotcachesize option to specify an appropriate size to create the snapshot.

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, including snapshot differential

104 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 Linux
hosts.
• Map the NetApp volumes by using an NFS mount.
• Ensure the NetApp volumes have the UNIX 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 104 using the following steps:
a) Log in as the root user ID.
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 104.
newPassword
This value is the password for the user ID that you created in step “1” on page 104.
Related tasks
“Protecting clustered-data ONTAP NetApp file server volumes” on page 106
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).
Related reference
“Snapdiff” on page 494
Using the snapdiff (snapshot difference) option with the incremental command streamlines the
incremental backup process. The command runs an incremental backup of the files that were reported as
changed by NetApp instead of scanning all of the volume for changed files.
“Snapdiffhttps” on page 501
Specify the snapdiffhttps option to use a secure HTTPS connection for communicating with a NetApp
filer during a snapshot differential backup.
“Createnewbase” on page 329

Chapter 2. Configure the IBM Spectrum Protect client 105

 The createnewbase option creates a base snapshot and uses it as a source to run a full incremental
backup.

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

• Complete the procedure in “Configuring NetApp and IBM Spectrum Protect for snapshot difference
incremental backups” on page 104.
• 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:
• 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).
• 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:

dsmc set password –type=filer management_filer_hostname

management_filer_username management_filer_password

Where:

106 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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

Where:
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.
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. Mount the remote storage virtual machine to a local file system.
For example, enter the following command for each storage virtual machine:

mount storage_virtual_machine_hostname /tmp/fs1

Where:
storage_virtual_machine_hostname
The host name or IP address of the storage virtual machine.
/tmp/fs1
An example of a file system to mount the storage virtual machine volume to.
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 backup-archive client snapdiffhttps option to enable
access to the cluster management server with the HTTPS protocol.
For example, on Linux clients, enter the following command:

dsmc incr /tmp/fs1 -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.

Chapter 2. Configure the IBM Spectrum Protect client 107

 For example, on Linux clients, enter the following command:

dsmc incr /tmp/fs1 -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

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

108 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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 NFS-exported 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 NFS 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 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 NFS-exported 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:
• When this backup is the initial backup.
• When createnewbase=yes is specified.

Chapter 2. Configure the IBM Spectrum Protect client 109

 • 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 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.

110 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 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.
You must be a root user or authorized user to perform this required task.
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

Chapter 2. Configure the IBM Spectrum Protect client 111

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:
• 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.
• The initial password you want to use, if required.
• Contact information, such as your name, user ID, and phone number.
Your IBM Spectrum Protect administrator defines the following for you:
• 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.
• Whether you can compress files before sending them to the server.
• 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:
• Your client node is assigned to a policy domain named standard.
• 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 the include-exclude list in your dsm.sys file. If you define more than one server in your dsm.sys
file, each server must have its own include-exclude list. This list can also contain include-exclude
statements obtained from the include-exclude files you specify with the inclexcl option.

112 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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.sys, in the same
order, and processed accordingly.

Procedure
You can use the following methods to create an include-exclude list or specify an include-exclude file:
• You can add include-exclude statements in the backup-archive client GUI or web client directory tree.
The online help provides detailed instructions.
a) 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.
b) Create the include-exclude list manually, following the steps listed.
• You can create an include-exclude list manually by performing the following steps:
a) Determine your include and exclude requirements.
b) Locate the server stanza in your dsm.sys file. Each server stanza must have its own include-exclude
list.
c) Enter your include and exclude statements. The client evaluates all exclude.fs and
exclude.dir statements first (regardless of their position within the include-exclude list), and
removes the excluded file spaces, 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.cpp file is not backed up:

include /Users/user01/Documents/includefile.cpp
exclude /Users/user01/Documents/.../*

However, in the following include-exclude list the includefile.cpp file is backed up:

exclude /Users/user01/Documents/.../*
include /Users/user01/Documents/includefile.cpp

d) Save the file and close it.

For Mac OS X, ensure that you save the file as plain text encoded as Unicode (UTF-8 or UTF-16). Do
not add the .txt extension.
e) Restart the client to enable your include-exclude list.
Related concepts
“Considerations for Unicode-enabled clients” on page 403
An include-exclude file can be in Unicode or non-Unicode format.
“System files to exclude” on page 116
There are some system files that should be placed in the client options file so that they are excluded.
“Storage management policies” on page 265
Storage management policies are rules your administrator defines in order to manage your backups and
archives on the server.
Related reference
“Inclexcl” on page 402
The inclexcl option specifies the path and file name of an include-exclude options file.

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

Chapter 2. Configure the IBM Spectrum Protect client 113

 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 and files from the list of objects available
for processing. The exclude.dir statements override all include statements that match the pattern.
Table 27 on page 114 lists the options you can use to exclude file spaces and directories from processing.

Table 27. Options for excluding file spaces and directories

Option Description
exclude.fs Excludes file spaces matching the pattern. The client does not consider the
“Exclude options” specified file space for processing and the usual deleted-file expiration process
on page 374 cannot occur. If you exclude a file space that was previously included, existing
backup versions remain on the server subject to retention rules specified in the
associated management class definition.
exclude.dir Excludes a directory, its files, and all its subdirectories and their files from backup
“Exclude options” processing. For example, the statement exclude.dir /test/dan/data1
on page 374 excludes the /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.
• Use the following statements to exclude volumes /Volumes/disk2 altogether
from backup processing. Note that the volume (/Volumes/disk2) is backed
up, but all other directories on /Volumes/disk2 is excluded.

exclude /Volumes/disk2/*
exclude.dir /Volumes/disk2/*

• An alternative method for excluding an entire volume from domain incremental

backup is to use a domain statement to exclude the volume. For example:

domain "-/Volumes/disk2"

This alternative still permits selective backup processing of files on /Volumes/

disk2.

Exclude files and directories from a journal-based backup

There are two methods of excluding files and directories from a journal-based backup.
• On AIX and Linux, 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.
• On AIX and Linux 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.
If you are running AIX Version 6.1 or later, add an exclude .snapshot statement to the
tsmjbbd.ini file to prevent JFS2 internal snapshot directories from being monitored by the journal-
based backup daemon.
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.

114 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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 28 on page 115 lists the options that you can use to control processing with include and exclude
statements.

Table 28. Options for controlling processing using include and exclude statements
Option Description Page
Back up processing
These options are equivalent. Use these options to exclude a file “Exclude
exclude
or group of files from backup services and space management options”
exclude.backup
services (if the HSM client is installed). The exclude.backup on page
exclude.file
option only excludes files from normal backup, but not from 374
exclude.file.backup
HSM.
Use these options to include files or assign management “Include
include
classes for backup processing. options”
include.backup
on page
include.file
403
include.fs Controls how the client processes your file space for “Include
incremental backups. options”
on page
403
Archive processing
Excludes a file or group of files from archive services. “Exclude
exclude.archive options”
on page
374
These options are equivalent. Use these options to include files “Include
include
or assign management classes for archive processing. options”
include.archive
on page
403
Image processing
exclude.fs.nas Excludes file systems on the NAS file server from an image “Exclude
backup when used with the backup nas command. If you do options”
not specify a NAS node name, the file system identified applies on page
to all NAS file servers. The backup nas command ignores all 374
other exclude statements including exclude.fs and
exclude.dir statements. This option is for AIX and Solaris
clients only.
exclude.image Excludes mounted file systems and raw logical volumes that “Exclude
match the specified pattern from full image backup operations. options”
Incremental image backup operations are unaffected by on page
exclude.image. This option is valid for AIX, Solaris, and all 374
Linux clients.

Chapter 2. Configure the IBM Spectrum Protect client 115

 Table 28. Options for controlling processing using include and exclude statements (continued)
Option Description Page
include.fs.nas Use the include.fs.nas option to bind a management class “Include
to Network Attached Storage (NAS) file systems. To specify options”
whether the client saves Table of Contents (TOC) information on page
during a NAS file system image backup, use the toc option with 403
the include.fs.nas option in your dsm.sys file. For more
information, see “Toc” on page 531. This option is valid only for
AIX and Solaris clients.
include.image Includes a file space or logical volume, assigns a management “Include
class, or allows you to assign one of several image backup options”
processing options to a specific logical volume when used with on page
the backup image command. The backup image command 403
ignores all other include options. This option is valid for AIX,
Solaris, Linux x86_64, and Linux on POWER® only.

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.
Note: This section applies to Mac OS X only.
The implicitly generated statements can be seen in the lines of output of the query inclexcl
command with the source "operating system".
The backup-archive client adds the following exclude statements to the include-exclude list from your
dsm.sys file. Do not include any of these statements in the dsm.sys file, or duplicate entries occurs.

EXCLUDE.ARCHIVE "/.../Desktop DB"

EXCLUDE.BACKUP "/.../Desktop DB"
EXCLUDE.ARCHIVE "/.../Desktop DF"
EXCLUDE.BACKUP "/.../Desktop DF"
EXCLUDE.ARCHIVE /.vol
EXCLUDE.BACKUP /.vol
EXCLUDE.ARCHIVE /automount
EXCLUDE.BACKUP /automount
EXCLUDE.ARCHIVE /Network
EXCLUDE.BACKUP /Network
EXCLUDE.ARCHIVE /dev
EXCLUDE.BACKUP /dev
EXCLUDE.BACKUP /.vol/.../*
EXCLUDE.ARCHIVE /.vol/.../*
EXCLUDE.BACKUP /automount/.../*
EXCLUDE.ARCHIVE /automount/.../*
EXCLUDE.BACKUP /Network/.../*
EXCLUDE.ARCHIVE /Network/.../*
EXCLUDE.BACKUP /dev/.../*
EXCLUDE.ARCHIVE /dev/.../*
EXCLUDE.DIR /.vol
EXCLUDE.DIR /automount
EXCLUDE.DIR /Network
EXCLUDE.DIR /dev

Note:
1. Do not specify volumes with periods in the name (...). The backup-archive client uses the sequence of
periods as part of include-exclude processing. The client reports an invalid include-exclude statement
if a volume has a sequence of periods in the name. The volume must be renamed.
2. Objects that have a type of rhap and a creator of lcmt are excluded from processing. Generally, these
are special file-system objects that can also be created with the mknod command or are UNIX mount
points. The objects or mount points must be manually recreated as part of a full system restore.

116 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
You should have the following minimum include-exclude list in your include-exclude options file:

EXCLUDE /.../dsmsched.log
EXCLUDE /.../dsmprune.log
EXCLUDE /.../dsmj.log
EXCLUDE /.../dsmerror.log
EXCLUDE /.../.hotfiles.bTree

EXCLUDE.DIR /private/tmp
EXCLUDE.DIR /private/var/vm
EXCLUDE.DIR /private/var/tmp
EXCLUDE.DIR /private/var/db/netinfo/local.nidb

EXCLUDE.DIR /.../.Trashes
EXCLUDE.DIR /.../.Spotlight-*
EXCLUDE.DIR /.../Library/Caches
EXCLUDE.DIR /.../.fseventsd

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 AIX, the names of directories or files can contain:

* ? : [ ]

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.
To exclude the single directory /usr1/[dir2] from backup processing, enter the following in the dsm.sys
file or the include-exclude file:

exclude.dir "/usr1/[\[]dir2[\]]"

To exclude the single file /usr1/fi*le1 from backup processing, enter the following statement in the
dsm.sys file or the include-exclude file:

exclude "/usr1/fi[\*]le1"

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.sys file or the include-exclude file.
Related concepts
“Wildcard characters” on page 592
Use wildcard characters when you want to specify multiple files with similar names in one command.
Without wildcard characters, you must repeat the command for each file.

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.

Chapter 2. Configure the IBM Spectrum Protect client 117

 Table 29. 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:
• The pattern ab?, matches abc, but does not match ab, abab, or abzzz.
• The pattern ab?rs, matches abfrs, but does not match abrs, or abllrs.
• The pattern ab?ef?rs, matches abdefjrs, but does not match abefrs, abdefrs, or
abefjrs.
• The pattern ab??rs, matches abcdrs, abzzrs, but does not match abrs, abjrs, or
abkkkrs.

* The match-all character. For example:

• The pattern ab*, matches ab, abb, abxxx, but does not match a, b, aa, bb.
• The pattern ab*rs, matches abrs, abtrs, abrsrs, but does not match ars, or aabrs,
abrss.
• The pattern ab*ef*rs, matches abefrs, abefghrs, but does not match abefr, abers.
• 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 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.

\ 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.

Related concepts
“Wildcard characters” on page 592
Use wildcard characters when you want to specify multiple files with similar names in one command.
Without wildcard characters, you must repeat the command for each file.

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.
Note: In the dsm.sys file, the include and exclude options do not work with symbolic links to
directories. For example, do not use /u in your include or exclude statements because /u is a symbolic
link to the /home directory. Instead of entering:

include /u/tmp/save.fil

enter:

118 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 include /home/tmp/save.fil

However, the exclude option does work with symbolic links to directories when you enter a backup
command with the absolute path that contains the symbolic link.
Table 30 on page 119 shows how to use wildcard characters to include or exclude files.

Table 30. Using wildcard characters with include and exclude patterns
Task Pattern
Exclude all files that end with .doc, except those found
EXCLUDE /.../*.doc
in the home directory of aleko, Documents directory. INCLUDE "/home/aleko/Documents/
*.doc"

Exclude all files during backup with an extension of bak,

exclude /.../*.bak
except those found on the /usr file system in the dev include /usr/dev/*.bak
directory.
Exclude all files and directories under any Documents
EXCLUDE /.../Documents/.../*
directory that might exist, except for the Current file of INCLUDE "/home/aleko/Documents/
user aleko. Current"

Exclude all files in any directory named "tmp" and its

exclude /.../tmp/.../*
subdirectories, except for the file /home/tmp/ include /home/tmp/save.fil
save.fil.
Exclude any .cpp file in any directory on the Vol1,
EXCLUDE /Volumes/Vol[1-4]/.../*.cpp
Vol2, Vol3, and Vol4 volumes.
Exclude any .cpp file in any directory on the Vol1,
EXCLUDE /Volumes/Vol[1-4]/.../*.cpp
Vol2, Vol3, and Vol4 volumes.
Exclude any .cpp file in any directory on the /fs1, /
EXCLUDE /fs[1-4]/.../*.cpp
fs2, /fs3 and /fs4 file systems.
Exclude the .cpp files found in the /fs2/source
EXCLUDE /fs2/source/*.cpp
directory.
Exclude any .o file in any directory on the /usr1, /
exclude /usr[1-3]/.../*.o
usr2, and /usr3 file systems.
Exclude the .o files found in the root directory in the
exclude /usr2/*.o
usr2 file system only.
Exclude any file that resides under the tmp directory
exclude /.../tmp/.../*
found in any file system.
Exclude the entire directory structure /var/spool
exclude.dir /var/spool
from all processing.
Exclude a single file system from backup processing.
exclude.fs /fs1

exclude.fs home:

Exclude all file systems mounted anywhere in the /

exclude.fs /test/myfs/fs01/.../*
test/myfs/fs01 and /test/myfs/fs02 directory exclude.fs /test/myfs/fs02/*
tree from backup processing.
Exclude the /home/mydir/test1 directory and any
exclude.dir /home/mydir/test1
files and subdirectories under it.

Chapter 2. Configure the IBM Spectrum Protect client 119

 Table 30. Using wildcard characters with include and exclude patterns (continued)
Task Pattern
Exclude all directories under the /home/mydir
exclude.dir /home/mydir/test*
directory with names beginning with test.
Exclude all directories directly under the /mydir
exclude.dir /.../mydir/test*
directory with names beginning with test, on any file
system.
Exclude the raw logical volume from image backup.
exclude.image /dev/hd0

Exclude all symbolic links or aliases (aliases apply to

EXCLUDE.ATTRIBUTE.SYMLINK /.../*
Mac OS X) from backup processing, except for the Docs INCLUDE.ATTRIBUTE.SYMLINK /Users/
directory for user1. user1/Docs/*

Related concepts
“Examples using wildcards with include and exclude patterns” on page 118
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.
Related reference
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.

Symbolic link and alias processing

The backup-archive client evaluates all exclude.fs and exclude.dir statements and removes the
excluded file spaces and directories.
After this initial evaluation, the client evaluates any include-exclude statements for controlling symbolic
link and alias processing (exclude.attribute.symlink and include.attribute.symlink)
against the remaining list of objects available for processing.
Alias processing applies to Mac OS X.
Table 31 on page 120 defines options for controlling symbolic link and alias processing.

Table 31. Options for controlling symbolic link and alias processing
Option Description Page
exclude.attribute.symlink Excludes a file or a group of files that are “Exclude options” on page
symbolic links or aliases from backup 374
processing only.
include.attribute.symlink Includes a file or a group of files that are “Include options” on page
symbolic links or aliases within broad 403
group of excluded files for backup
processing only.

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.

120 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 32. Options for controlling compression and encryption
Option Description Page
Compression processing
exclude.compression Excludes files from compression processing if “Exclude
compression=yes is specified. This option applies to options”
backups and archives. on page
374
include.compression Includes files for compression processing if “Include
compression=yes is specified. This option applies to options”
backups and archives. on page
403
Encryption processing
exclude.encrypt Excludes files from encryption processing. “Exclude
options”
on page
374
include.encrypt Includes files for encryption processing. “Include
options”
The data that you include is stored in encrypted form, and
on page
encryption does not affect the amount of data sent or
403
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.
Restriction: Client encryption with the include.encrypt
option is no longer supported for LAN-free backup and
archive operations to the IBM Spectrum Protect server
V8.1.1 and later levels, or V7.1.8 and later V7 levels. LAN-
free restore and retrieve operations of encrypted backup
versions and archive copies continue to be supported. If you
need to encrypt data by using the include.encrypt
option, in which data is encrypted before it is sent to the
server, use LAN-based backup or archive operations.

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.

Chapter 2. Configure the IBM Spectrum Protect client 121

 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 635
The preview archive command simulates an archive command without sending data to the server.
“Preview Backup” on page 636
The preview backup command simulates a backup command without sending data to the server.

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 dsm.sys 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.fs and exclude.dir
statements first, and removes the excluded file spaces, directories, and files from the list of objects
available for processing.
After evaluating all exclude.fs and exclude.dir statements, the client evaluates the include-exclude
statements for controlling symbolic link or alias processing (exclude.attribute.symlink and
include.attribute.symlink) from the bottom up and stops if it finds an include or exclude
statement that matches the file it is processing. After the include-exclude statements for controlling
symbolic link or alias processing are processed, the client evaluates the remaining 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.

122 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Example 1
Assume that La Pomme is not the startup disk.

EXCLUDE /.../*.cpp
INCLUDE "/Volumes/La Pomme/Foo/.../*.cpp"
EXCLUDE "/Volumes/La Pomme/Foo/Junk/*.cpp"

The file being processed is: /Volumes/La Pomme/Foo/Dev/test.cpp. Processing follows these
steps:
1. Rule 3 (the last include or exclude statement defined) is checked first because of bottom-up
processing. The pattern /Volumes/La Pomme/Foo/Junk/*.cpp does not match the file name
that is being processed.
2. Processing moves to Rule 2 and checks. This time, pattern /Volumes/La Pomme/Foo/.../
*.cpp matches the file name that is being processed. Processing stops, the option is checked, and
it is included.
3. File /Volumes/La Pomme/Foo/Dev/test.cpp is backed up.
Example 2
Assume that La Pomme is not the startup disk.

EXCLUDE /.../*.cpp
INCLUDE "/Volumes/La Pomme/Foo/.../*.cpp"
EXCLUDE "/Volumes/La Pomme/Foo/Junk/*.cpp"

The file being processed is: /Volumes/La Pomme/Widget/Sample File. 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, Volumes/La Pomme/Widget/Sample File is implicitly included
and is backed up.
Example 3
Assume that you defined the following statements for the include and exclude options:

exclude *.o
include /home/foo/.../*.o
exclude /home/foo/junk/*.o

The file being processed is: /home/foo/dev/test.o. Processing follows these steps:
1. Rule 3 (the last statement defined) is checked first because of bottom-up processing. The
pattern /home/foo/junk/*.o does not match the file name that is being processed.
2. Processing moves to Rule 2 and checks. This time, pattern /home/foo/.../*.o matches the file
name that is being processed. Processing stops, the option is checked, and it is include.
3. File /home/foo/dev/test.o is backed up.
Example 4
Assume that you defined the following statements for the include and exclude options:

exclude *.obj
include /home/foo/.../*.o
exclude /home/foo/junk/*.o

The file being processed is: /home/widg/copyit.txt . 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.

Chapter 2. Configure the IBM Spectrum Protect client 123

 4. Because a match is not found, file /home/widg/copyit.txt is implicitly included and backed
up.
Example 5
Assume that you defined the following statements for the include and exclude options:

exclude /.../*.o
include /home/foo/.../*.o
exclude /home/foo/junk/*.o

The current file being processed is: /home/lib/objs/printf.o. 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 /home/lib/objs/printf.o is not backed up.
Example 6
Assume that you defined the following statements for the include and exclude options:

exclude.attribute.symlink /.../*
exclude /.../*.o
include /home/foo/.../*.o
exclude /home/foo/junk/*.o

The current file being processed is: /home/lib/objs/printf.o. Processing follows these steps:
1. The exclude.attribute.symlink statement is checked first. If the printf.o file is a symbolic
link it is excluded, otherwise proceed to the next step. Note that the
exclude.attribute.symlink statements are always processed before the other include-
exclude statements, regardless of their position in the include-exclude list.
2. Rule 3 is checked and finds no match.
3. Rule 2 is checked and finds no match.
4. Rule 1 is checked and a match is found.
5. Processing stops, the option is checked, and it is excluded.
6. File /home/lib/objs/printf.o is not backed up.
Related concepts
“Exclude file spaces and directories” on page 114
Use exclude.dir statements to exclude all files and subdirectories in the specified directory from
processing.
“Processing options” on page 277
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 reference
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.
“Query Inclexcl” on page 652
The query inclexcl command displays a list of include-exclude statements in the order in which they
are processed during backup and archive operations. The list displays the type of option, the scope of the
option (archive, all, and so on), and the name of the source file.

124 IBM Spectrum Protect UNIX and Linux 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:
• “Starting a Java GUI session” on page 132
• “Starting a command-line session” on page 133
• “Starting a web client session” on page 136
• “Start the client scheduler automatically” on page 140
• “Changing your password” on page 140
You can also complete the following tasks:
• “Sorting file lists using the backup-archive client GUI” on page 142
• “Displaying online help” on page 143
• “Ending a session” on page 143

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.

Configuring by using the default security settings (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. The fast path scenario
minimizes the steps in the configuration process at endpoints.
This scenario 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 value at first connection. You can follow this scenario whether you first upgrade the
IBM Spectrum Protect server to V8.1.2 and later V8 levels, and then upgrade the client to these levels, or
vice versa.
Note: If a client connects to the IBM Spectrum Protect server by using V8.1.6 or later V8 levels, and is
using either Shared Memory or Named Pipes for communication, the SESSIONSECURITY parameter
value for the client transitions to STRICT. In this case, if you want to use TCP/IP for communication
instead of Shared Memory or Named Pipes, and the client does not already have the server's certificate,
then first reset the SESSIONSECURITY parameter to TRANSITIONAL. You must then connect to the
server to automatically obtain the certificates.
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. For more information, see “Configuring without automatic certificate distribution”
on page 128.

Client options that affect session security

The following client options specify security settings for the client. For more information about these
options, see “Client options reference” on page 306.

© Copyright IBM Corp. 1993, 2019 125

 • 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 later
server by using TLS for authentication.
• 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.
• 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. The value Yes indicates that SSL is used to encrypt all information,
including object data, when the client communicates with the server.
• SSLFIPSMODE. The default value No indicates that a Federal Information Processing Standards (FIPS)
certified SSL library is not required.
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 later server.
• SSLDISABLELEGACYTLS. A value of No indicates that the client does not require TLS 1.2 for SSL
sessions. It allows connection at TLS 1.1 and lower SSL protocols. When the client communicates with
a IBM Spectrum Protect server that is V8.1.1 or earlier, No is the default.
• LANFREESSL. The default value No indicates that the client does not use SSL when communicating with
the Storage Agent when LAN-free data transfer is configured.
• 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

• First, the server is upgraded to V8.1.2 or later. Then, the client is upgraded. The existing client is not
using SSL communications:
– No changes are required to the security options for the client.
– The configuration is automatically updated to use TLS when the client authenticates with the server.
• First, the server is upgraded to V8.1.2 or later. Then, the client is upgraded. The existing client is using
SSL communications:
– No changes are required to the security options for the client.
– SSL communication with existing server public certificate continues to be used.
– SSL communication is automatically enhanced to use the TLS level that is required by the server.
• First, the client is upgraded to V8.1.2 or later. Then, the server is upgraded later. The existing client is
not using SSL communications:
– No changes are required to the security options for the client.
– Existing authentication protocol continues to be used to servers at levels earlier than V8.1.2.
– The configuration is automatically updated to use TLS when the client authenticate with the server
after the server is updated to V8.1.2 or later.
• First, the client is upgraded to V8.1.2 or later. Then, the server is upgraded later. The existing client is
using SSL communications:
– No changes are required to the security options for the client.
– SSL communication with existing server public certificate continues to be used with servers at levels
earlier than V8.1.2.
– SSL communication is automatically enhanced to use the TLS level that is required by the server after
the server is updated to V8.1.2 or later.
• First, the client is upgraded to V8.1.2 or later. Then, the client connects to multiple servers. The servers
are upgraded at different times:

126 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 – No changes are required to the security options for the client.
– The client uses existing authentication and session security protocol to servers at versions earlier
than V8.1.2 , and automatically upgrade to use TLS authentication when initially connecting to a
server at V8.1.2 or later. Session security is managed per server.
• New client installation, server is at V8.1.2 or later:
– Configure the client according to a new installation.
– Default values for the security options automatically configure the client for TLS-encrypted session
authentication.
– Set the SSL parameter to the Yes value if encryption of all data transfers between the client and the
server is required.
• New client installation, server is at a version earlier than V8.1.2 :
– Configure the client according to a new client installation.
– Accept the default values for client session-security parameters if SSL encryption of all data transfers
is not required.
- Non-SSL authentication protocol is used until the server is upgraded to V8.1.2 or later.
– Set the SSL parameter to the Yes value if encryption of all data transfers between the client and the
server is required, and proceed with the manual configuration for SSL.
- See “Configuring IBM Spectrum Protect client/server communication with Secure Sockets Layer”
on page 70 for configuration instructions.
- SSL communication is automatically enhanced to use the TLS level that is required by the server
after the server is updated to V8.1.2 or later.
Related reference
Sslrequired
The sslrequired option specifies the conditions when SSL is or is not required when the client logs on
to the IBM Spectrum Protect server or storage agents. To actually enable SSL so client-to-server and
client-to-storage-agent communications are secure, you must set the client ssl option to yes. When
communicating with the IBM Spectrum Protect server V8.1.2 and later levels, and V7.1.8 and later V7
levels, this option no longer applies since SSL is always used.
Sslacceptcertfromserv
Use the sslacceptcertfromserv option to control whether the backup-archive client or the API
application accept and trust the IBM Spectrum Protect server's Secure Sockets Layer (SSL) public
certificate the first time they connect. This option applies only the first time that the backup-archive client
or the API application connects to the IBM Spectrum Protect server. When the SSL public certificate is
accepted, future changes to the certificate are not automatically accepted, and must be manually
imported to the backup-archive client. You can use this option to connect only to an IBM Spectrum
Protect server V8.1.2 and later levels, and V7.1.8 and later V7 levels.
Ssl
Use the ssl option to enable Secure Sockets Layer (SSL) to provide secure client and server
communications. When the backup-archive client communicates with an IBM Spectrum Protect server
V8.1.1 and earlier V8 levels, and V7.1.7 and earlier levels, it determines whether SSL is enabled. When
the backup-archive client communicates with an IBM Spectrum Protect server V8.1.2 and later levels,
and V7.1.8 and later V7 levels, SSL is always used and this option controls whether object data is
encrypted or not. For performance reasons, it might be desirable to not encrypt the object data.
Sslfipsmode
The sslfipsmode option specifies whether the client uses SSL Federal Information Processing
Standards (FIPS) mode for Secure Sockets Layer (SSL) communications with the server. The default is no.
Ssldisablelegacytls
Use the ssldisablelegacytls option to disallow the use of SSL protocols that are lower than TLS 1.2.
Lanfreessl

Chapter 3. Getting started 127

 Use the lanfreessl option to enable Secure Sockets Layer (SSL) to provide secure client and Storage
Agent communications. This option is deprecated if you are connecting to an IBM Spectrum Protect
server V8.1.2 and later levels, and V7.1.8 and later V7 levels.
Replsslport
The replsslport option specifies the TCP/IP port on the secondary server that is SSL-enabled. The
replsslport option is used when the client connects to the secondary server during a failover. This
option is deprecated if you are connecting to an IBM Spectrum Protect server V8.1.2 and later levels, and
V7.1.8 and later V7 levels.

Configuring 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. For example, 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 (CA).

Options that affect session security

The options for security settings are the same as those described in “Configuring by using the default
security settings (fast path)” on page 125, with the exception that you must set the
SSLACCEPTCERTFROMSERV option 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.

Uses cases for configuring the client without automatic certificate distribution
If automatic certificate distribution is not possible or wanted, use the dsmcert utility to import the
certificate. Obtain the necessary certificate from the IBM Spectrum Protect server or from a CA. The CA
can be from a company such as VeriSign or Thawte, or an internal CA that is maintained within your
company.
• First, the server is upgraded to V8.1.2. Then, the client is upgraded. The existing client is not using SSL
communications:
– Set the SSLACCEPTCERTFROMSERV option with the value No.
– Obtain the necessary certificate from the IBM Spectrum Protect server or from a CA and use the
dsmcert utility to import the certificate. See “Configuring IBM Spectrum Protect client/server
communication with Secure Sockets Layer” on page 70 for configuration instructions.
• First, the server is upgraded to V8.1.2 or later. Then, the client is upgraded. The existing client is using
SSL communications:
– No changes are required to the security options for the client. If the client already has a server
certificate for SSL communication, the SSLACCEPTCERTFROMSERV option does not apply.
– SSL communication with existing server public certificate continues to be used.
– SSL communication is automatically enhanced to use the TLS level that is required by the server.
• First, the client is upgraded to V8.1.2 or later. Then, the server is upgraded later. The existing client is
not using SSL communications:
– Set the SSLACCEPTCERTFROMSERV option with the value No.
– Existing authentication protocol continues to be used to servers at levels earlier than V8.1.2.
– Before the client connects to a V8.1.2 or later server:
- Obtain the necessary certificate from the IBM Spectrum Protect server or from a CA and use the
dsmcert utility to import the certificate. See “Configuring IBM Spectrum Protect client/server
communication with Secure Sockets Layer” on page 70 for configuration instructions.
• First, the client is upgraded to V8.1.2 or later. Then, the server is upgraded later. The existing client is
using SSL communications
– No changes are required to the security options for the client. If the client already has a server
certificate for SSL communication, the SSLACCEPTCERTFROMSERV option does not apply.

128 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 – SSL communication with existing server public certificate continues to be used with servers at levels
earlier than V8.1.2.
– SSL communication is automatically enhanced to use the TLS level that is required by the server after
the server is updated to V8.1.2 or later.
• First, the client is upgraded to V8.1.2 or later. Then, the client connects to multiple servers. The servers
are upgraded at different times:
– Set the SSLACCEPTCERTFROMSERV option with the value No.
– Existing authentication protocol continues to be used to servers at levels earlier than V8.1.2.
– Before the client connects to a V8.1.2 or later server, or when SSL communication is required at any
server level:
- Obtain the necessary certificate from the IBM Spectrum Protect server or from a CA and use the
dsmcert utility to import the certificate. See “Configuring IBM Spectrum Protect client/server
communication with Secure Sockets Layer” on page 70 for configuration instructions.
– The client uses existing authentication and session security protocol to servers at versions earlier
than V8.1.2, and automatically upgrade to use TLS authentication when initially connecting to a
server at V8.1.2 or later. Session security is managed per server.
• New client installation, server is at V8.1.2 or later:
– Configure the client according to a new installation.
– Set the SSLACCEPTCERTFROMSERV option with the value No.
– Obtain the necessary certificate from the IBM Spectrum Protect server or from a CA and use the
dsmcert utility to import the certificate. See “Configuring IBM Spectrum Protect client/server
communication with Secure Sockets Layer” on page 70 for configuration instructions.
– Set the SSL parameter to the Yes value if encryption of all data transfers between the client and the
server is required.
• New client installation, server is at a version earlier than V8.1.2, SSL-encrypted sessions are required:
– Configure the client according to a new installation.
– Set the SSL parameter to the Yes value.
– Obtain the necessary certificate from the IBM Spectrum Protect server or from a CA and use the
dsmcert utility to import the certificate. See “Configuring IBM Spectrum Protect client/server
communication with Secure Sockets Layer” on page 70 for configuration instructions.
• New client installation, server is at a version earlier than V8.1.2, SSL-encrypted sessions are not
required:
– Configure the client according to a new installation.
– 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.
– Before the client connects to a V8.1.2 or later server:
- Obtain the necessary certificate from the IBM Spectrum Protect server or from a CA and use the
dsmcert utility to import the certificate. See “Configuring IBM Spectrum Protect client/server
communication with Secure Sockets Layer” on page 70 for configuration instructions.
Related reference
Sslrequired
The sslrequired option specifies the conditions when SSL is or is not required when the client logs on
to the IBM Spectrum Protect server or storage agents. To actually enable SSL so client-to-server and
client-to-storage-agent communications are secure, you must set the client ssl option to yes. When
communicating with the IBM Spectrum Protect server V8.1.2 and later levels, and V7.1.8 and later V7
levels, this option no longer applies since SSL is always used.
Sslacceptcertfromserv

Chapter 3. Getting started 129

 Use the sslacceptcertfromserv option to control whether the backup-archive client or the API
application accept and trust the IBM Spectrum Protect server's Secure Sockets Layer (SSL) public
certificate the first time they connect. This option applies only the first time that the backup-archive client
or the API application connects to the IBM Spectrum Protect server. When the SSL public certificate is
accepted, future changes to the certificate are not automatically accepted, and must be manually
imported to the backup-archive client. You can use this option to connect only to an IBM Spectrum
Protect server V8.1.2 and later levels, and V7.1.8 and later V7 levels.
Ssl
Use the ssl option to enable Secure Sockets Layer (SSL) to provide secure client and server
communications. When the backup-archive client communicates with an IBM Spectrum Protect server
V8.1.1 and earlier V8 levels, and V7.1.7 and earlier levels, it determines whether SSL is enabled. When
the backup-archive client communicates with an IBM Spectrum Protect server V8.1.2 and later levels,
and V7.1.8 and later V7 levels, SSL is always used and this option controls whether object data is
encrypted or not. For performance reasons, it might be desirable to not encrypt the object data.
Sslfipsmode
The sslfipsmode option specifies whether the client uses SSL Federal Information Processing
Standards (FIPS) mode for Secure Sockets Layer (SSL) communications with the server. The default is no.
Ssldisablelegacytls
Use the ssldisablelegacytls option to disallow the use of SSL protocols that are lower than TLS 1.2.
Lanfreessl
Use the lanfreessl option to enable Secure Sockets Layer (SSL) to provide secure client and Storage
Agent communications. This option is deprecated if you are connecting to an IBM Spectrum Protect
server V8.1.2 and later levels, and V7.1.8 and later V7 levels.
Replsslport
The replsslport option specifies the TCP/IP port on the secondary server that is SSL-enabled. The
replsslport option is used when the client connects to the secondary server during a failover. This
option is deprecated if you are connecting to an IBM Spectrum Protect server V8.1.2 and later levels, and
V7.1.8 and later V7 levels.

Secure password storage

Beginning in IBM Spectrum Protect Version 8.1.2 and V7.1.8, 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 and V7.1.8, 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 70.
When you upgrade to the IBM Spectrum Protect V8.1.2 or later client from an earlier client that uses the
old password locations, the existing passwords are migrated to the following files in the new password
store:
TSM.KDB
The file that stores the encrypted passwords.
TSM.sth
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.
TSM.IDX
An index file that is used to track the passwords in the TSM.KDB file.
For Data Protection for VMware clients, the Data Protection for VMware GUI server administration
password is migrated to a keystore.

130 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Password locations on UNIX and Linux clients
On UNIX and Linux clients, the existing passwords in the TSM.PWD files are migrated to the new password
store in the same location. For root users, the default location for the password store is /etc/adsm. For
non-root users, the location of the password store is specified by the passworddir option.
The TSM.PWD file is deleted after the migration.
Note: The new password store will not be in the default location (/etc/adsm) in the following situations:
• The TSM.PWD file did not exist in the /etc/adsm directory.
• The options file specifies a passworddir option that points to a different location.

The trusted communications agent is no longer available

The trusted communications agent (TCA), previously used by non-root users in V8.1.0 and V7.1.6 and
earlier clients, is no longer available. Root users can use the following methods to allow non-root users to
manage their files:
Help desk method
With the help desk method, the root user runs all backup and restore operations. The non-root user
must contact the root user to request certain files to be backed up or restored.
Authorized user method
With the authorized user method, a non-root user is given read/write access to the password store by
using the passworddir option to point to a password location that is readable and writable by the
non-root user. This method allows non-root users to back up and restore their own files, use
encryption, and manage their passwords with the passwordaccess generate option.
For more information, see “Enable non-root users to manage their own data” on page 51.
If neither of these methods are satisfactory, you must use the earlier clients that included the TCA.

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

Chapter 3. Getting started 131

 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:
• From the main IBM Spectrum Protect GUI window, select File → Connection Information.
• Use the IBM Spectrum Protect server QUERY ADMIN command from the administrative command-line
client.
Related reference
Revokeremoteaccess
The revokeremoteaccess option restricts an administrator with client access privilege from accessing
a client workstation that is running the web client.
QUERY ADMIN command

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 Procedure
System
Mac OS X • Double-click the IBM Spectrum Protect application to start the backup-archive client
without system administrator privileges. When you run the client without system
administrator privileges, you can manage files that are owned by the current user.
• Double-click IBM Spectrum Protect for Administrators and select IBM Spectrum
Protect. After you enter a system administrator user name and password, the client
starts with system administrator privileges. When you run the client with system
administrator privileges, you can manage files that are owned by all users on the
system.
• You can also start the backup-archive client by using the dsmj command. You can run
the client as either a foreground or background process. The dsmj script is installed
in /Library/Application Support/tivoli/tsm/client/ba/bin.

AIX, Linux, On UNIX systems other than Mac OS X, the backup-archive client GUI must be run from
Solaris the X Window System. If you see the IBM Spectrum Protect icon on your desktop, the
client is already running. Double-click the icon to open the IBM Spectrum Protect
window. If the IBM Spectrum Protect icon is not displayed on your desktop, start the
backup-archive client graphical interface by using the dsmj command. You can run the
client as either a foreground or background process.

The backup-archive client locates and uses the options that are specified in the client system options file
(dsm.sys) and the client options files (dsm.opt).
Related concepts
“Configure the IBM Spectrum Protect client” on page 49

132 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 After installing the backup-archive client, you must configure it before performing any operations.

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 140
Your IBM Spectrum Protect administrator can require you to use a password to connect to the server.

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.
The client options file is dsm.sys.

Starting a command-line session

You can start a command-line session by invoking the dsmc command.
Note: If the /usr/bin directory contains a symbolic link to the IBM Spectrum Protect executable, and all
DSM environment variables are set, you can enter the dsmc command from any directory. Otherwise,
enter the fully qualified path of the command.
Note: On Mac OS X, system administrators can use the sudo command to gain additional authority so the
backup-archive client can access files for all users on the system.
On the command line enter dsmc followed by the command (batch mode). If the /usr/bin or opt/bin
directory contains a symbolic link to the IBM Spectrum Protect installation directory, you can enter the
dsmc command from any directory. Otherwise you can enter the fully qualified name.
One can start client with "dsmc" command only in case PATH environment variable is updates with path
to the client location.
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
“Options in interactive mode” on page 590
In interactive mode, options that you enter on the initial command line override the value that you
specified in your options file.
“UNIX and Linux client root and authorized user tasks” on page 49
An authorized user is any non-root user who has read and write access to the stored password (TSM.sth
file), or anyone who knows the password and enters it interactively. Authorized users use the
passworddir option to define the directory where their copy of the password file is saved.
“Using commands” on page 585

Chapter 3. Getting started 133

 The backup-archive client provides a command-line interface (CLI) that you can use as an alternative to
the graphical user interface (GUI). This topic describes how to start or end a client command session and
how to enter commands.

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 /home/proj1/file1.txt

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 449
The passwordaccess option specifies whether you want to generate your password automatically or set
as a user prompt.

Issuing a series of commands by using interactive mode

Use interactive mode when you want to issue a series of commands.

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:
• dsmc
• dsmc loop
The following prompt is displayed on your screen:

Protect>

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 /home/proj1/file1.txt

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.

134 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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:
• 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.
• 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"

• 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"'

• 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.
The following rules apply to these types of data:
• Fully qualified names
• The description that you specify in the archive command
• 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:
• If the character string is in an option file
• If the character string is in a list file
• If the character string is entered in interactive mode

Starting: Additional considerations

You can include options as arguments to dsmj and dsmc commands. For example, you can use options to
modify the format that displays dates, times, and numbers, or to include your password so that the
backup-archive client does not prompt for it.

About this task

In addition, if you have more than one server defined in dsm.sys and you want to contact a different
server for backup-archive services (other than the one specified in your client user-options file dsm.opt),
specify the server with the servername option.
For example:

dsmj -servername=server_b

The Java GUI (dsmj) accepts command-line parameters, such as the Java -X options. Because of this, you
can also now modify the Java Heap Size. For example:

dsmj -Xmx512M

Chapter 3. Getting started 135

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 GUI to connect
to the IBM Spectrum Protect V8.1.2 or later V8 server or the V7.1.8 or later V7 server.
If you are connected to the IBM Spectrum Protect V8.1.2 or later V8 server or the V7.1.8 or later V7
server, use the following alternatives to the web client GUI:
• To back up and restore your data, use the backup-archive client GUI or command-line interface. To
start the command-line interface, enter dsmc at the command line. To start the backup-archive client
GUI, enter dsmj for UNIX and Linux clients, or dsm for Windows clients.
For more information, see:
– Chapter 4, “Backing up your data,” on page 145
– Chapter 5, “Restoring your data,” on page 213
• To restore your data, use the web user interface. To start the web user interface, see
– “Starting a web user interface session for file-restore operations” on page 137
• To back up and restore NAS file servers using Network Data Management Protocol (NDMP), use the
backup-archive client GUI.
For more information, see:
– “Back up NAS file systems using Network Data Management Protocol” on page 189
– “Restore NAS file systems” on page 229
Tip: If you already upgraded the backup-archive client to V8.1.2 or later, you can uninstall it and reinstall
the V8.1.0 client to continue to use the web client. The IBM Spectrum Protect server administrator needs
to set the SESSIONSECURITY parameter on the node back to TRANSITIONAL. For more information, see
UPDATE NODE (Update node attributes).

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.
To run the web client from Firefox browsers, the option for Enable JavaScript must be enabled. By
default, this option is enabled in Firefox.

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

136 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 If you enter a different URL or click Back during an operation, the web client is disconnected and the
current operation ends.
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 62
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.

User privileges
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.
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:

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

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 131
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.
Related reference
“Revokeremoteaccess” on page 478
The revokeremoteaccess option restricts an administrator with client access privilege from accessing
a client workstation that is running the web client.

Starting a web user interface session for file-restore operations

The IBM Spectrum Protect backup-archive client provides a web user interface component, which can be
started and managed independently of web browser software. After you install and configure the web
user interface on your workstation, you can use the web user interface for file-restore operations. You can
restore files on behalf of a user without accessing the web user interface virtual machine. The web user
interface supports only client-to-server communications that use the Transport Layer Security (TLS) or
Secure Sockets Layers (SSL) protocols.

Chapter 3. Getting started 137

 Before you begin
To determine which web browsers are supported, see the software requirements topic for your operating
system.
To run the web user interface from Mozilla Firefox browsers, the option for Enable JavaScript must be
enabled. This option is enabled by default.

Procedure
1. In the installation directory, locate the client options file, dsm.opt or dsm.sys. For more information,
see “Client options file overview” on page 53.
2. Add the HTTPPORT option to the client options file. For example, specify the following value:
httpport 1581
3. Run the dsmc command to verify your configuration.
4. Run the dsmc query session command to validate that the TLS or SSL protocol is used. Review the
output to find the security information, which is similar to the following example,

SSL Information.........: TLSv1.2 TLS_RSA_WITH_AES_128_CBC_SHA

5. Start the client acceptor by taking the appropriate actions for your operating system:
• Run the dsmcad command from a command line.
6. Enter the following IBM Spectrum Protect server commands to register an administrator to access the
client data, and perform the file-restore operations on behalf of the node:

reg admin admin ID password

grant auth admin ID cl=node auth=access node=your node

where admin ID is the administrator's ID, password is the administrator's password, and node is the
node where file-restore operations are performed.
7. If you registered a new node, and do not have backup data stored on the IBM Spectrum Protect server
for that node, perform a backup. This backup provides you with test data that can be used for file-
restore operations with the web user interface. To back up the data, take one of the following actions:
• From the command line, run either the dsmc incremental or dsmc selective command. For
more information, see:
– “Incremental” on page 627
– “Selective” on page 698
• In the IBM Spectrum Protect backup-archive client GUI select Backup.
8. To start the File Restore user interface, in a supported web browser, enter the following URL:

https://hostname:9081/bagui/

where hostname specifies the address of the virtual machine that hosts the File Restore user interface.
9. In the login window, enter the administrator ID and password (as specified in step 7), and click Sign
In.

Downloading system logs

You can download problem-determination information, including system logs and trace file, pertaining to
IBM Spectrum Protect backup-archive client and web user interface operations. By default, this feature is
disabled, but it can be enabled by the system administrator.

Procedure
From the web user interface, select Download System Logs.

138 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
• If you have permission to download problem-determination information, a message indicates that the
download started, and that the logs are downloaded in the background.
• If you do not have permission to download problem-determination information, a message indicates
that downloading is not permitted and that the system administrator can change this permission. For
more information about changing this permission, see the enable_download_logs option in the “File
restore options” on page 140.
Restriction: Multiple requests to download system logs cannot be processed at the same time. A new
system log collection cannot be started until the initial system log collection is completed.

Results
Depending on the size of the log files and trace file, it can take several minutes for the system logs to be
downloaded.
The problem-determination information is collected into a compressed file. The file can be saved to a
selected location, or saved to the default location as specified in the browser configuration.
The compressed file name has the following format:
TIV-logs-TSM_CAD-<NODE NAME>-YYYY-MM-DD_hh-mm-ss.zip
The compressed file contains the following problem-determination information:
• ba/dsminfo.txt. This file contains IBM Spectrum Protect backup-archive client information from the
command query systeminfo, and includes the following information dsmerror.log,
dsmwebcl.log, and dsmsched.log.
• ba/trace.txt. If tracing is enabled, this file contains IBM Spectrum Protect backup-archive client
trace file information.
• ba/dsminstr.log. This file contains IBM Spectrum Protect backup-archive client instrumentation
information.
• The liberty_logs folder contains all logs and trace files that are related to the Liberty Server and the
file-restore API, including fr_api.log and messages.log.
• frGUI/FRLog.config. This file contains file-restore API logging and tracing configuration
information.
• The tsmVmGUI folder contains the file-restore information files, and including api-
jlog.properties, frConfig.props, traceConfig.properties, TsmApiLog.config, and
tsmserver.props.
• server.xml. This file contains configuration information that is related to the Liberty Server.

Specifying options for file restore operations

To allow administrators to configure and control file restore operations, specify the options in the
frConfig.props file.

Before you begin

By default, the frConfig.props file does not exist. However, you can create a file with the specified
name and save the file in the relevant directory as outlined in the procedure.

About this task

Complete these steps on the system where the IBM Spectrum Protect backup-archive client is installed.

Procedure
1. Go to the directory where the frConfig.props file is located.
For example, open a command prompt and enter the following command:

On AIX:

cd /usr/tivoli/tsm/tdpvmware/common/webserver/usr/servers/veProfile/tsmVmGUI

Chapter 3. Getting started 139

 On Linux:

cd /opt/tivoli/tsm/tdpvmware/common/webserver/usr/servers/veProfile/tsmVmGUI/

2. Open the frConfig.props file with a text editor in administrator mode and specify the option as
needed.
To determine which options to specify, see “File restore options” on page 140.
3. Save your changes and close the frConfig.props file.

Results
Modified options are applied to the IBM Spectrum Protect web user interface.

File restore options

The frConfig.props file controls file restore operations. You can configure the options in the
frConfig.props file.
enable_download_logs=false | true
Specify whether system logs can be downloaded by using the IBM Spectrum Protect web user
interface.
false
System logs cannot be downloaded by using the IBM Spectrum Protect web user interface. This
value is the default.
true
System logs can be downloaded by using the IBM Spectrum Protect web user interface.

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.
Related tasks
“Setting the client scheduler process to run as a background task and start automatically at startup” on
page 256
You can configure the IBM Spectrum Protect client scheduler to run as a background system task that
starts automatically when your system is started.

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. On Mac OS X clients, start the backup-archive client with IBM Spectrum Protect Tools for
Administrators.
2. From the main window, open the Utilities menu and select Change password.

140 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
3. Enter your current and new passwords, and enter your new password again in the Verify password
field.
4. Click Change.

Results
To change your password from the command-line client, enter this command:
For UNIX, Linux, and Windows clients:

dsmc set password

For Mac OS X clients, enter this command to change your password from the command-line client:

sudo 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.
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 b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9 . ! @ # $ % ^ & * _ - + = ` ( )
| { } [ ] : ; < > , ? / ~

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 b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9 . ! @ # $ % ^ & * _ - + = ` ( )
| { } [ ] : ; < > , ? / ~

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 b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 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 AIX, Linux, and Solaris systems:
Enclose the command parameters in single quotation marks (').
Command line example:
dsmc set password -type=vmguest 'Win 2012 SQL' 'tsml2dag\administrator'
'7@#$%^&7'

Chapter 3. Getting started 141

 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 140
You can start the client scheduler automatically when you start your workstation.
Related tasks
“Starting: Additional considerations” on page 135
You can include options as arguments to dsmj and dsmc commands. For example, you can use options to
modify the format that displays dates, times, and numbers, or to include your password so that the
backup-archive client does not prompt for it.
Related reference
“Password” on page 447
The password option specifies a password for IBM Spectrum Protect.
“Set Password” on page 706
The set password command changes the IBM Spectrum Protect password for your workstation, or sets
the credentials that are used to access another server.

Sorting file lists using the backup-archive client GUI

You can use the backup-archive client GUI to display, sort, or select files.

About this task

Table 33. 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 • Click the appropriate column heading in the File List box.

Display active and inactive • Click the Display Active/Inactive Files option from the View menu.
backup versions
• Click the Display both active and inactive files tool on the tool bar.

Display only active backup Click the Display active files only option from the View menu.
versions
Selecting files to restore or • Click the selection box next to the directory or file name that you
retrieve. want to restore or retrieve.
• Highlight the files that you want to restore or retrieve and click the
Select Items tool on the tool bar.
• Highlight the files that you want to restore or retrieve and click the
Select Items option from the Edit menu.

Deselecting files • Click the checked selection box next to the directory or file name.
• Highlight the files that you want to deselect and click the Deselect
Items tool on the tool bar.
• Highlight the files that you want to deselect and click the Deselect
Items option from the Edit menu.

Displaying file information • Highlight the file name, and click the View File Details button on the
tool bar.
• Highlight the file name, and select File Details from the View menu.

142 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 401
Use the inactive option to display both active and inactive objects.
“Pick” on page 451
The pick option creates a list of backup versions or archive copies that match the file specification you
enter.

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

• On the backup-archive client GUI:
– Open the help menu. Click Help or press F1.
– Click the Help button in the current window.
– On Mac systems, click the GUI question mark (?) icon, which displays online information about the
current operation.
• 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 626
Use the help command to display information about commands, options, and messages.

Ending a session
You can end a client session from the backup-archive client GUI or from the dsmc command line.

About this task

• From the backup-archive client GUI:
– Open the File menu and select Quit.
– Press Command+Q.
– Open the File menu and select Exit.
– Open the System menu and select Close.

Chapter 3. Getting started 143

 – For the web client: Open a different URL or close the browser.
• 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, press Ctrl-C or use the UNIX kill -15 command.
Note: Due to signal-handler design limitations with the dsmc command on UNIX and Linux, pressing
Ctrl-C or using the UNIX kill -15 command can lead to a core memory dump. If you need to avoid
such a core memory dump, use the UNIX kill -9 command from an available command line.
Related reference
“Loop” on page 633
The loop command starts an interactive command line session that is maintained until you enter quit.

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

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

144 IBM Spectrum Protect UNIX and Linux 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 following is a list of primary backup tasks.
• “Planning your backups ” on page 145
• “Pre-backup considerations (UNIX and Linux)” on page 147
• “Performing an incremental, selective, or incremental-by-date backup (UNIX and Linux)” on page 158
• “Deleting backup data” on page 170
• “Backing up files from one or more file spaces for a group backup (UNIX and Linux)” on page 172
• “Image backup” on page 178
• “Back up NAS file systems using Network Data Management Protocol” on page 189

Planning your backups

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 backing up data.
Read the list of tasks to determine whether you are ready to back up your data.
• Decide whether you want to back up files or archive them. See “When to back up and when to archive
files” on page 146 for more information.
• See “Pre-backup considerations (UNIX and Linux)” on page 147 for important considerations before
you back up your files and directories.
• Do you need to exclude files from backup services? See “Include-exclude options to control
processing” on page 150 for more information.
Related concepts
Installing the IBM Spectrum Protect backup-archive clients
The IBM Spectrum Protect backup-archive client helps you protect information on your workstations.

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:
• The selected management class contains a backup copy group.
• 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.
• 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.
• 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.
• The file is not excluded from backup by an exclude statement.

© Copyright IBM Corp. 1993, 2019 145

 • 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
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
“Storage management policies” on page 265
Storage management policies are rules your administrator defines in order to manage your backups and
archives on the server.
“Management classes and copy groups” on page 266
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.
Related reference
“Absolute” on page 306
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.

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:
• The number of versions that are maintained on the IBM Spectrum Protect server
• The number of days each additional backup copy is kept
• 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.
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.

146 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Related concepts
“Archive and retrieve your data (UNIX and Linux)” on page 241
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. Many of the windows
and concepts are similar.
“Restore data from a backup set” on page 216
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.

Pre-backup considerations (UNIX and Linux)

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.
AIX, Linux, and Solaris clients support LAN-free data movement.
Restriction: Client encryption with the include.encrypt option is no longer supported for LAN-free
backup and archive operations to the IBM Spectrum Protect server V8.1.1 and later levels, or V7.1.8 and
later V7 levels. LAN-free restore and retrieve operations of encrypted backup versions and archive copies
continue to be supported. If you need to encrypt data by using the include.encrypt option, in which
data is encrypted before it is sent to the server, use LAN-based backup or archive operations.

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.

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.

Chapter 4. Backing up your data 147

 Related reference
“Enablelanfree” on page 367
The enablelanfree option specifies whether to enable an available LAN-free path to a storage area
network (SAN) attached storage device.
“Lanfreecommmethod” on page 423
The lanfreecommmethod option specifies the communications protocol between the IBM Spectrum
Protect client and Storage Agent. This enables processing between the client and the SAN-attached
storage device.
“Lanfreeshmport” on page 425
Use the lanfreeshmport option when lanfreecommmethod=SHAREdmem is specified for
communication between the backup-archive client and the storage agent. This enables processing
between the client and the SAN-attached storage device.
“Lanfreessl” on page 426
Use the lanfreessl option to enable Secure Sockets Layer (SSL) to provide secure client and Storage
Agent communications. This option is deprecated if you are connecting to an IBM Spectrum Protect
server V8.1.2 and later levels, and V7.1.8 and later V7 levels.
“Lanfreetcpport” on page 425
The lanfreetcpport option specifies the TCP/IP port number where the IBM Spectrum Protect Storage
Agent is listening.
“Lanfreetcpserveraddress” on page 427
The lanfreetcpserveraddress option specifies the TCP/IP address for the IBM Spectrum Protect
Storage Agent.

Incremental backups on memory-constrained systems

Incremental backup performance suffers if the system has a low amount of memory available before
starting the backup.
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 434
The memoryefficientbackup option specifies the memory-conserving algorithm to use for processing
full file space backups.

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 700 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 700 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:

148 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
• 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.
• Use the client option memoryefficientbackup yes. The average memory that is used by the client
then becomes 700 bytes times the number of directories plus 700 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.
• UNIX and Linux clients might be able to use the virtualmountpoint client option to define multiple
virtual mount points within a single file system, each of which can be backed up independently by the
client.
• 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 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.
• Use the - incrbydate client option to perform an "incremental-by-date" backup.
• Use the exclude.dirclient option to prevent the client from traversing and backing up directories that
do not need to be backed up.
• Except for Mac OS X, use the client image backup function to back up the entire volume. An image
backup might actually use less system resources and run faster than incremental backup of some file
systems with a large number of small files.
• Reduce the number of files per file system by spreading the data across multiple file systems.
Related reference
“Snapdiff” on page 494
Using the snapdiff (snapshot difference) option with the incremental command streamlines the
incremental backup process. The command runs an incremental backup of the files that were reported as
changed by NetApp instead of scanning all of the volume for changed files.
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.
“Incrbydate” on page 420
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, unless you exclude the file
from backup.
“Memoryefficientbackup” on page 434
The memoryefficientbackup option specifies the memory-conserving algorithm to use for processing
full file space backups.
“Resourceutilization” on page 475
Use the resourceutilization option in your option file to regulate the level of resources the IBM
Spectrum Protect server and client can use during processing.
“Virtualmountpoint” on page 539

Chapter 4. Backing up your data 149

 The virtualmountpoint option defines a virtual mount point for a file system if you want to consider
files for backup that begin with a specific directory within that file system.

Include-exclude options to control processing

You might have files in your file systems that you do not want to back up. These files might be core files,
local caches of network file systems, operating system or application files that could be easily recovered
by reinstalling the program, or any other files that you could easily rebuild.
You can use the exclude and include options in your include-exclude options list to specify which files
to exclude from backup processing.
Use the include and exclude options in dsm.sys 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 containing other files you want to exclude.
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 chosen for you, or one you assign to the file 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.
Related tasks
“Creating an include-exclude list ” on page 112
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.
“Setting the client scheduler process to run as a background task and start automatically at startup” on
page 256
You can configure the IBM Spectrum Protect client scheduler to run as a background system task that
starts automatically when your system is started.

Data encryption during backup or archive operations

The way to ensure data security is by encrypting data. Use data encryption to protect data during a
backup or archive operation. Advanced Encryption Standard (AES) 128-bit encryption is the default
encryption option. For the highest level of data encryption, use 256-bit Advanced Encryption Standard
(AES) data encryption by specifying the encryptiontype option.
The data that you include is stored in encrypted form, and encryption does not affect the amount of data
that is sent or received.
The include.encrypt option is the only way to enable encryption on the backup-archive client. If no
include.encrypt statements are used encryption cannot 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.
Use the include and exclude options in dsm.sys 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.
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. Store the encryption key password for later
use. You can specify whether to save the encryption key password in a file that is named TSM.sth 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.

150 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 While restoring the encrypted file, the client prompts you for the key password to decrypt the file in the
following cases:
• The encryptkey option is set to Prompt.
• The key supplied by the user in the previous case does not match.
• The encryptkey option is set to Save and the locally saved key password does not match the
encrypted file.
Restriction: Client encryption with the include.encrypt option is no longer supported for LAN-free
backup and archive operations to the IBM Spectrum Protect server V8.1.1 and later levels, or V7.1.8 and
later V7 levels. LAN-free restore and retrieve operations of encrypted backup versions and archive copies
continue to be supported. If you need to encrypt data by using the include.encrypt option, in which
data is encrypted before it is sent to the server, use LAN-based backup or archive operations.
Related reference
“Encryptiontype” on page 368
Use the encryptiontype option to specify the algorithm for data encryption.
“Encryptkey” on page 369
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.
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.
“Include options” on page 403
The include options specify objects that you want to include for backup and archive services.

File system and ACL support

Special file systems contain dynamic information that is generated by the operating system; they contain
no data or files. The UNIX and Linux clients ignore special file systems and their contents.
The stand-alone package LSCqfs
Special file systems include the following types:
• The /proc file system on most of the UNIX platforms
• The /dev/fd file system on Solaris
• The /dev/pts on Linux
The backup-archive client can work on specific file system types that are commonly used. contains For a
list of supported file system types, see Table 34 on page 151.
Restriction: The table shows full support for NFS on AIX, including preservation of ACLs and extended
attributes. On other operating systems, NFS backups are supported, but the backups include only
standard POSIX metadata (access permissions, creation date, and so on). For more information about
backing up NFS file systems, see “Backup network file systems” on page 193.

Table 34. Supported file systems and ACL support

Platform File System ACL Support
AIX GPFS Yes
JFS Yes
JFS2 Yes
JFS2 NFSV4 Yes
VxFX Yes

Chapter 4. Backing up your data 151

 Table 34. Supported file systems and ACL support (continued)
Platform File System ACL Support
Linux x86_64 Btrfs Yes
XFS Yes
EXT2 Yes
EXT3 Yes
EXT4 Yes
ReiserFS Yes
GPFS Yes
JFS No
VxFS No
NSS Yes
Linux on Power Systems Servers Btrfs Yes
XFS Yes
EXT2 Yes
EXT3 Yes
EXT4 Yes
ReiserFS Yes
JFS No
GPFS Yes
Linux on z Systems® Btrfs Yes
XFS Yes
EXT2 Yes
EXT3 Yes
EXT4 Yes
ReiserFS Yes
JFS No
GPFS Yes

152 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 34. Supported file systems and ACL support (continued)
Platform File System ACL Support
macOS HFS Standard (HFS) Yes
HFS Extended (HFS+) Yes
HFS Extended case-sensitive Yes
(HFSX)
Xsan (XSAN) UNIX Yes
Universal disk format (UDF) Yes
ISO9660 Yes
Apple File System, Case Sensitive Yes
(APFSCS)
Apple File System (APFS) Yes
Solaris UFS Yes
VxFS Yes
QFS No
ZFS Yes

With file systems where NFS V4 ACLs are defined and used (Solaris ZFS and AIX JFS2 V2), even if only the
standard UNIX permissions or ACLs have changed (such as with the CHMOD command), the file or
directory is fully backed up again. With other file systems, this type of change causes only an attribute
update on the IBM Spectrum Protect server.
To process all other file systems, use the virtualmountpoint option to enable support for the
following items:
• To back up, restore, archive, and retrieve file data
• For basic UNIX and Linux permissions
• For change, access, and modification time stamps, and the directory tree structure
No other file system specific attributes, such as the ACL, are valid. The file system type for such file
systems is set to "UNKNOWN".
For example, if the /media/abc/DATA1 file system is not supported by the client, add the following
statement to dsm.sys to back up or archive the data in this file system:

VIRTUALMOUNTPOINT /media/abc/DATA1

This support is only available if the file system can use basic POSIX system calls, such as read or write
processing on your system.
Cross-platform backup and restore are not supported. For example, data backed up by an AIX client is not
available for restore by a Windows client and vice versa.
Note: Data that is backed up or archived by the Mac OS X client cannot be restored by any other client.
Additionally, the Mac OS X client cannot restore or retrieve data from any other client.
You can use the cross-file system type restore or retrieve method for ACL information if both the original
file system and the destination file system support compatible ACLs. For example, on Solaris, the ACL
information that is backed up from a VxFS file system is restored to a UFS file system because these file
systems support compatible ACLs. The ACL information is not restored during cross-file system restore or
retrieve operations if the original file system and the destination file system do not support ACLs,
The following restrictions apply to the QFS file system:

Chapter 4. Backing up your data 153

 • Image backup is not supported on QFS file systems.
• The Solaris backup-archive client does not support the combination of QFS and SAM needed to archive
files onto tertiary background storage, such as tapes. Instead, it recalls files from tape to disk
automatically if it finds migrated files during a backup.
• A QFS file system contains two hidden system files and a system directory that cannot be backed up;
and this is acceptable because a backup of these files is not needed. They contain internal data to
manage the file system. The internal data is automatically excluded from a backup and is re-created
automatically by the file system itself, if a restore of files in that file system is completed.
Incremental, selective, filelist back up, archive, restore, and retrieve processing of the Veritas file system
and its ACLs on AIX are supported. Restore of a Veritas volume on a Logical Volume Manager volume (and
vice versa) is allowed, provided both have the same file system type.
The following information pertains only to Mac OS X systems:
• On Mac OS X systems, the UFS and HFSX file systems are case-sensitive whereas the HFS+ file system
is not case-sensitive but is case-preserving. Files that you back up from a UFS or HFSX file system
(case-sensitive) might not be restored properly to an HFS+ file system (not case-sensitive) file system.
For example, on a UFS file system, files Afile and afile are seen as different files. However, on an
HFS+ file system the two files are seen as identical.
• On Mac OS X, if case-sensitive HFS+ or UFS file systems are used, it is important that the data from the
HFSX or UFS file system is not backed up to an HFS+ file system on the IBM Spectrum Protect server.
Either a new name must be used on the system or the existing file space on the IBM Spectrum Protect
server must be renamed. For example, consider a system that has a file system named /Volumes/fs2
and this system is repartitioned with a case-sensitive HFS+ file system. Either the /Volumes/fs2 file
system on the IBM Spectrum Protect server must be renamed, or a new name must be used on the local
system. If this renaming is not done, the HFSX case-sensitive data is mixed with the HFS+ case-
insensitive data that is already stored on the IBM Spectrum Protect server.
• On Mac OS X, aliases and symbolic links are backed up. However, the client does not back up the data
to which the symbolic links point.
• On Mac OS X, when files that are backed up from an HFS volume are restored to a UFS volume, the
resource forks are not assigned to the correct owner. Correct this problem by using the chown
command on the resource fork file to change the owner. The resource fork file stores structured data in
a file.
On Linux on POWER and Linux on System z, you must install libacl.so for the client to back up ACLs.
Important: If you are running GPFS for AIX, GPFS for Linux x86_64, or GPFS for Linux on z Systems in a
multinode cluster, and all nodes share a mounted GPFS file system, the client processes this file system
as a local file system. The client backs up the file system on each node during an incremental backup. To
avoid this, you can do one of the following things:
• Explicitly configure the domain statement in the client user-options file (dsm.opt) to list the file
systems you want that node to back up.
• Set the exclude.fs option in the dsm.sys file to exclude the GPFS file system from backup services.
If the GPFS cluster contains different platforms, you must use backup-archive clients on only one
platform to protect a single file system. Do not use backup-archive clients on more than one platform to
protect a GPFS file system that is shared among more than one platform
For example, assume that a cluster contains nodes on AIX, Linux x86, and Linux zSeries systems. You can
protect file system A with AIX backup-archive clients and protect file system B with Linux zSeries backup-
archive clients. Or you can protect file system A and file system B with AIX backup-archive clients. If you
protect file system A with an AIX backup-archive client, you must not protect file system A with a backup-
archive client on any platform other than AIX.

Support for cross operating system recovery for files stored in IBM Spectrum Scale file systems
In an IBM Spectrum Scale cluster with multiple operating system types, a file that holds ACL or extended
attribute metadata and was backed up on a source operating system, can be restored on a target

154 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 operating system. The ACL or extended attribute metadata is correctly restored correctly if both operating
system types on the source and the target use the same version of IBM Spectrum Scale.
The following are the supported source-operating-systems types:
• AIX
• Linux for IBM System Power big endian (pBE)
• Linux x86
• Linux for IBM System z
The following are the supported target-operating-system types:
• Linux for IBM System Power little endian (pLE)
• Linux x86
• Linux for IBM System z
The security settings for affected users and groups must match on both the source and the target
systems.
Do not mix operating system types for backup activity. Choose only one operating system type available
in your IBM Spectrum Scale cluster, and use it for all backup operations.

Maximum file size for operations

The maximum file size depends on the type of a file system. The backup-archive client does not check any
file size limit during backup, archive, restore, or retrieve operations.
If the file system allows creation of the file, the client backs up or archives the file.
The following table specifies the maximum file sizes for the native file systems on UNIX and Linux client
platforms.

Table 35. Maximum file size

Platform Max file size (in bytes)
AIX 6.1 (JFS2) size limitations Maximum JFS2 file system size: 32 TB
Maximum JFS2 file size: 16 TB
Minimum JFS2 file system size: 16 MB

All Linux clients 9 223 372 036 854 775 807 (8 EB-1)
Mac OS X HFS - 2 147 485 648 (2GB)
HFS+, HFSX, XSAN, and UFS -
9 223 372 036 854 775 808 (8EB)

Solaris 1 099 511 627 775 (1 TB-1)

Solaris (ZFS) 18 446 744 073 709 551 616 (16 EB)

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 by IBM Spectrum Protect.
Important: Do not exceed the 64 character limit for user and group names. If you do, the client shortens
the name to fall within this limit by using the following transformation: Take the first 53 characters,
append a forward slash (/), and then 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:
• The set access command

Chapter 4. Backing up your data 155

 • The fromowner option
• 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.

Mac OS X volume names

The backup-archive client backs up volumes based on their UNIX mount point name.
IBM Spectrum Protect maintains each volume name as a separate restore or retrieve volume. These
volume names become the names of file spaces on the server.
If you change the name of a volume you have already backed up, the client sees it as a new volume and
does not relate it to the previous one. Any backup of the volume backs up the files under the new name. A
mismatch might occur if you rename your volumes, or if you access IBM Spectrum Protect from a
different workstation than the one from which you backed up the files.

Mac OS X volume naming precautions

IBM Spectrum Protect creates all new file spaces on the server with the UNIX mount point of the volume.
If there are two volumes with the names such as "La Pomme" and "la pomme", two unique UNIX
mount points are created.
The following examples show the two mount points that are created:

/Volumes/La Pomme
/Volumes/la pomme

If duplicate volumes exist on your desktop, it is possible for the UNIX mount points to be different than
the last time the client did a backup. The client might not back up the data to the correct file system on
the IBM Spectrum Protect server.
You can check the file system where the client backs up the data:
1. In the Backup window, select a file system.
2. Click File → Show Info.
The UNIX mount point is in the Information dialog.
The best way to avoid any potential naming problems is to ensure that the volume names are unique.
Important:
• The client continues to use the existing file space names on the IBM Spectrum Protect Server. Only new
file spaces use the UNIX mount point for the name.
• Do not specify volumes with periods in the name (...). The client uses the sequence of periods as part of
include-exclude processing. The client reports an invalid include-exclude statement if a volume has a
sequence of periods in the name. The volume must be renamed.

Mac OS X volume naming precautions on dual boot systems

If you have more than one version of Mac OS X that you switch between, it is critical that you understand
how the client uses the UNIX mount paths for file space names on the IBM Spectrum Protect server.
For example, consider a dual-boot system that has two volumes, El Capitan and Sierra. The finder
and the backup-archive client GUI displays these as El Capitan and Sierra. However, the UNIX
mount points depend upon which version of Mac OS is running. If El Capitan is the startup disk, the UNIX
paths are:

/
/Volumes/Sierra

156 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 If Sierra is the startup disk, the UNIX paths are:

/
/Volumes/El Capitan

When a backup or archive operation is run, the file space names also depend on which version of Mac OS
X is running.
Both versions of Mac OS X back up to the / file system on the IBM Spectrum Protect server. When this
happens, the system files are intermixed.
To avoid potential problems on dual-boot systems, complete one of these tasks:
1. Select one version of Mac OS X on which to install and run IBM Spectrum Protect. This ensures that
the UNIX mount points are the same each time the client does a backup.
2. Configure each version of Mac OS X with a unique IBM Spectrum Protect node name. Then exclude the
other version of Mac OS X from backup processing with a domain statement in the system options file.
For example, if the volume Sierra is the startup disk, add this option to the system options file:

DOMAIN -/Volumes/El Capitan

If the volume El Capitan is the startup disk, add this to the system options file:

DOMAIN -/Volumes/Sierra

Mac OS X Unicode enablement

The Mac OS X client is Unicode enabled. New clients storing data on the server for the first time require no
special set up.
The server automatically stores files and directories as Unicode enabled. However, if you are upgrading to
the Unicode-enabled client, you need to plan the migration of existing file spaces so they can support
Unicode.
Any file spaces that are already on the server must be renamed so Unicode-enabled file spaces can be
created. Use the autofsrename option rename existing file spaces.
Related reference
“Autofsrename” on page 315
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.

Mac OS X Time Machine backup disk

Time Machine is the backup application available with Mac OS X.
IBM Spectrum Protect can be used at the same time as Mac OS X Time Machine application. However,
due to the unique nature of how the Mac OS X Time Machine application backs up data, consider the
following items before using the backup-archive client to back up the Mac OS X Time Machine data:
• The Mac OS X Time Machine backup disk makes extensive use of both file and directory hard links to
minimize disk usage. For example, if the disk backed up with the Mac OS X Time Machine application is
5 GB, the first backup copies 5 GBs of data to the Mac OS X Time Machine backup disk.
Subsequent backups only copy the files that have changed since the previous backup. All files and
directories that have not changed are hard-linked with the version that was copied during the previous
backup.
The Finder shows each backup as 5 GB, for a total size of 10 GB. However, because of the use of hard
links, the total disk usage is only slightly larger than 5 GB.
All hard-linked objects that are not already on the IBM Spectrum Protect server are backed up.
For example, 10 GB of data would be sent to the IBM Spectrum Protect server.

Chapter 4. Backing up your data 157

 • When files that are restored are hard-linked, the client recreates the original hard link. Recreating the
original hard link can only be done if all files that are hard-linked are restored at the same time.
Restoring all the hard-linked files at the same time is not a practical method for a large backup disk that
uses the Mac OS X Time Machine application.
• When the Mac OS X Time Machine application copies files to the backup disk, ACLs are added to the
files to protect them from deletion. the backup-archive can back up and restore files with ACLs.
However, any files that are restored must have these restrictive ACLs in place.
Tip: For best results, exclude the Time Machine application backup data. All Time Machine application
data is in a directory named Backups.backupdb.
Related concepts
“System files to exclude” on page 116
There are some system files that should be placed in the client options file so that they are excluded.

Performing an incremental, selective, or incremental-by-date backup (UNIX

and Linux)
Your administrator might have set up schedules to automatically back up files on your workstation. The
following sections discuss how to back up files without using a schedule.
There are two types of incremental backup: full incremental and partial incremental.
Related tasks
“Setting the client scheduler process to run as a background task and start automatically at startup” on
page 256
You can configure the IBM Spectrum Protect client scheduler to run as a background system task that
starts automatically when your system is started.

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 file systems, 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 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:
• Back up new files.

158 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
• 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
If only the following attributes change, the attributes are updated on the IBM Spectrum Protect server,
but the file is not backed up:
– File owner
– File permissions
– Inode
– Group ID
– Change time (ctime) attribute (for objects in GPFS file systems only and if the updatectime option
is set to yes). For more details, see the updatectime option.
– Icon location (Mac OS X only)
– Type or creator (Mac OS X only)
• 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.
– The change time (ctime) attribute is updated since the last backup (for GPFS file systems only). For
more details, see the updatectime option.
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.
• 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.
• 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.
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.

Chapter 4. Backing up your data 159

 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
“Storage management policies” on page 265
Storage management policies are rules your administrator defines in order to manage your backups and
archives on the server.
Related reference
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.
“Preservelastaccessdate” on page 457
Use the preservelastaccessdate option to specify whether a backup or archive operation changes
the last access time.
“Updatectime” on page 535
Use the updatectime option to check the change time (ctime) attribute during an incremental backup
operation.

Journal-based backup on AIX and Linux

Journal-based backup is an alternate method of backup that uses a change journal maintained by the
IBM Spectrum Protect journal daemon process.
On AIX, journal-based backup is supported on JFS and JFS2 file systems.
On Linux, journal-based backup is supported on Ext2, Ext3, Ext4; XFS, ReiserFS, JFS, VxFS, and NSS, and
for a local file system shared through NFS. GPFS is not supported for journal-based backups.
To support journal-based backup you must install and configure the IBM Spectrum Protect journal
daemon.
A backup of a particular file system will be journal-based when the journal daemon has been installed and
configured to journal the particular file system, and a valid journal has been established for the file
system. Journal-based backup is enabled by successfully completing a full incremental backup.
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:
• An object is selected as a backup candidate if it exists in the local list. but does not 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).
• 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 back up and expire by querying the journal
daemon 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.
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. Large change journals might create 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.

160 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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.
Here are some limitations of journal-based backup:
• 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.
• Other platform-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.
• 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.
• 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.
• The “Skipaclupdatecheck” on page 494 option has no effect during journal-based backups. No matter
how this option is set, when performing journal-based backups of a file system, the client always backs
up a file if its ACL or extended attributes have been changed since the last backup.
You should perform periodic full incremental backups and more frequent journal backups. Traditional
incremental backup compares the entire server inventory of files against the entire local file system.
Therefore, incremental backup is always the most comprehensive backup method.
Note: 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.

Restore processing with journal-based backups (AIX and Linux)

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.

Chapter 4. Backing up your data 161

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.
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.
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.
Related tasks
“Backing up data using the Java GUI” on page 166
You can back up specific files, entire directories, or entire file systems from the directory tree.

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:
• Does not expire backup versions of files that you delete from the workstation.
• Does not rebind backup versions to a new management class if you change the management class.
• Does not back up files with attributes that change, unless the modification dates and times also
change.
• 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.

162 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 On AIX and Linux, journal-based backup does have some limitations. See “Journal-based backup on
AIX and Linux” on page 160 for information.
NetApp snapshot difference
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.
• 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.
• 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.
• 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.
• Policy changes such as changing the policy from mode=modified to mode=absolute are not
detected.
• 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.
• Snapshot differential backup operations are not supported in the IBM Spectrum Protect for Virtual
Environments environment. You cannot run snapshot differential backup operations of a file system
that resides on a NetApp filer on a host where the Data Protection for VMware or Data Protection for
Microsoft Hyper-V data mover is also installed.
The NetApp software determines what is a changed object, not IBM Spectrum Protect.
If you run a full volume backup of an NFS-mounted NetApp or N-Series volume, all the snapshots
under the snapshot directory might also be backed up.
To avoid backing up all snapshots under the snapshot directory, do one of the following actions:
• Run NDMP backups
• Run backups using the snapshotroot option
• 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.
• Exclude the snapshot directory from backups.
On Linux systems, the snapshot directory is in .snapshot.
Note: The .snapshot directory is not backed up for some versions of Red Hat Linux, so you are not
required to exclude it.

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.

Chapter 4. Backing up your data 163

 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 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:
• 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.
• The snapdiffhttps option does not apply to vFilers because the HTTPS protocol is not supported on
the NetApp vFiler.
• 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 tasks
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.
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.
Related reference
Snapdiffhttps
Specify the snapdiffhttps option to use a secure HTTPS connection for communicating with a NetApp
filer during a snapshot differential backup.
Snapdiff
Using the snapdiff (snapshot difference) option with the incremental command streamlines the
incremental backup process. The command runs an incremental backup of the files that were reported as
changed by NetApp instead of scanning all of the volume for changed files.

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 104.
This method is available only at the command-line interface.

164 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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, you are using a Linux system with an NFS mounted file system /vol/vol1 hosted on the
file server homestore.example.com. The /net/home1 directory is the mount point of /vol/vol1.
Issue the following command:

dsmc incr /net/home1 -snapdiff -snapdiffhttps

Related concepts
“Snapshot differential backup with an HTTPS connection” on page 163
You can use a secure HTTPS connection for the backup-archive client to communicate with a NetApp filer
during a snapshot differential backup.
Related reference
“Snapdiffhttps” on page 501
Specify the snapdiffhttps option to use a secure HTTPS connection for communicating with a NetApp
filer during a snapshot differential backup.

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:
• Does not cause the server to update the date and time of the last incremental.
• Backs up directory and file entries even if their size, modification timestamp, or permissions have not
changed.
• Does not expire deleted files.
• Does not rebind backup versions to a new management class if you change the management class.
Related tasks
“Backing up data using the Java GUI” on page 166
You can back up specific files, entire directories, or entire file systems from the directory tree.
Related reference
“Selective” on page 698
The selective command backs up files that you specify. If you damage or mislay these files, you can
replace them with backup versions from the server.

Solaris global zone and non-global zones backups

For Solaris zones, perform incremental and selective backups of file systems within the zone where these
file systems were created.
Treat each non-global zone as a separate system that has its own IBM Spectrum Protect node name and
run backups from within each of the zones.
If you run incremental or selective backups of non-global zones from the global zone, the global-zone
administrator must decide which files in the non-global zone are included or excluded in backups. For
example, device, system and kernel files of the non-global zones are not automatically excluded from
backups, but they must not be backed up. Restoring such files can make a non-global zone unusable.

Chapter 4. Backing up your data 165

Saving access permissions
When you back up your files, the backup-archive client also saves standard UNIX access permissions
assigned to the files.
Depending on your operating system, it also saves extended permissions. For example, for files on an AIX
workstation, the client saves access control lists.
It is possible for an authorized user to back up files for another user, but this should not cause ownership
conflicts. The backup server properly records that the file belongs to the original owner. The authorized
user does not need to grant the original owner access to the backup versions.

Setting a virtual mount point

If you are an authorized user and you want to back up files beginning with a specific directory within a file
system, you can define that directory as a virtual mount point.
Defining a virtual mount point within a file system provides a direct path to the files you want to back up,
saving processing time. It is more efficient than defining the file system with the domain option and then
using an exclude option to exclude the files you do not want to back up. It also allows you to store
backups and archives for specific directories in separate storage file spaces.
Related reference
“Virtualmountpoint” on page 539
The virtualmountpoint option defines a virtual mount point for a file system if you want to consider
files for backup that begin with a specific directory within that file system.

Backing up data using the Java GUI

You can back up specific files, entire directories, or entire file systems from the directory tree.

About this task

You can locate the files you want to back up by searching or filtering. Filtering displays only the files
matching the filter criteria for your backup.
Use the backup-archive client Java GUI to back up your data as follows:

Procedure
1. Click Backup in the IBM Spectrum Protect window. The Backup window appears.
2. Expand the directory tree if necessary. Click on the selection boxes next to the object or objects you
want to back up. To search or filter files, click the Find icon on the tool bar.
3. Enter your search criteria in the Find Files (Backup) window.
4. Click the Search button. The Matching Files (Backup) window appears.
5. Click the selection boxes next to the files you want to back up and close the Matching Files (Backup)
window.
6. Enter your filter criteria in the Find Files (Backup) window.
7. Click the Filter button. The Backup window displays the filtered files.
8. Click the selection boxes next to the filtered files or directories you want to back up.
9. Select one of the following backup types from the pull-down menu: (1) To run an incremental
backup, click Incremental (complete), (2) To run an incremental-by-date backup, click Incremental
(date only), (3) To run a selective backup, click Always backup.
10. Click Backup. The Backup Task List window displays the backup processing status.

Results
Consider the following items when you back up your data using the Java GUI.
• To modify specific backup options, click the Options button. The options you select are effective during
the current session only.

166 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • 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. Select Utilities → View Policy Information from the backup-archive client
Java GUI or web client GUI to view the backup policies defined by the IBM Spectrum Protect server for
your client node.
• To perform an automatic incremental backup of your default domain, select Actions → Backup Domain.
Your default domain is set with the domain option in your client user-options file (dsm.opt). If you do
not have the domain option set, the default domain is all local file systems.
• You can use the Preferences editor to exclude file systems in your default domain from backup
processing.
Related concepts
“Storage management policies” on page 265
Storage management policies are rules your administrator defines in order to manage your backups and
archives on the server.
Related reference
“Domain” on page 349
The domain option specifies what you want to include for incremental backup.

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 these commands to perform different tasks.

Table 36. Command-line backup examples

Task Command Considerations
Incremental backups
Perform an incremental dsmc incremental See “Incremental” on page 627 for more
backup of your client information about the incremental
domain. command.
Back up the /fs1 dsmc incremental - See “Domain” on page 349 for more
and /fs2 file systems in domain="/fs1 /fs2" information about the domain option.
addition to the /home, /
usr, and /datasave file
systems defined in your
client domain.
Back up the / dsmc incremental -domain="/ See “Domain” on page 349 for more
Volumes/fs1 and / Volumes/fs1 /Volumes/fs2" information about the domain option.
Volumes/fs2 file
systems in addition to the
volumes defined in your
client domain.
Back up all local file dsmc incremental -domain="all- You cannot use the (-) operator in front
systems defined in your local -/home" of the domain keyword all-local. See
client domain except for “Domain” on page 349 for more
the /home file system. information. For Windows clients, you
can also exclude the system state
domain from backup processing in this
way.
Back up only the /fs1 dsmc incremental /fs1 /fs2 None
and /fs2 file systems.

Chapter 4. Backing up your data 167

Table 36. Command-line backup examples (continued)
Task Command Considerations
Back up all files in the / dsmc incremental /home/ - See “Subdir” on page 515 for more
home directory and all its subdir=yes information about the subdir option.
subdirectories.
Back up all files in the / dsmc incremental /Users/ - See “Subdir” on page 515 for more
Users directory and all its subdir=yes information about the subdir option.
subdirectories.
Assuming that you dsmc incremental /usr - The backup-archive client considers the
initiated a snapshot of snapshotroot=/snapshot/day1 snapshotroot value as a file space
the /usr file system and name. See “Snapshotroot” on page 504
mounted the snapshot for more information.
as /snapshot/day1, 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 /usr.
Incremental-by-date backup
Perform an incremental- dsmc incremental -incrbydate Use the incrbydate option with the
by-date backup of your incremental command to back up new
default client domain. and changed files with a modification
date later than the last incremental
backup stored at the server. See
“Incrbydate” on page 420 for more
information about the incrbydate
option.
Selective backups
Back up all files in the / dsmc selective /home/proj/ or Use the selective command to back
home/proj or / dsmc selective /Users/van/ up specific files or directories regardless
Users/van/Documents Documents/ of whether they have changed since your
directory. last incremental backup. You can use
wildcards to back up multiple files at
once. See “Selective” on page 698 for
more information about the selective
command.
Back up all files in the / dsmc selective /home/proj/ - If you specify -subdir=yes when
home/proj directory and subdir=yes backing up a specific path and file, the
all its subdirectories. client recursively backs up all
subdirectories under that path, and any
instances of the specified file that exist
under any of those subdirectories.
If a subdirectory is a mounted file
system, the client does not back up the
files in that subdirectory when you use
the subdir=yes option. See “Subdir” on
page 515 for more information about the
subdir option.

168 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 36. Command-line backup examples (continued)
Task Command Considerations
Back up all files in the / dsmc selective /Users/van/ If you specify -subdir=yes when
Users/van/Documents Documents/ -subdir=yes backing up a specific path and file, the
directory and all its client recursively backs up all
subdirectories. subdirectories under that path, and any
instances of the specified file that exist
under any of those subdirectories.
If a subdirectory is a mounted file
system, the client does not back up the
files in that subdirectory when you use
the subdir=yes option. See “Subdir” on
page 515 for more information about the
subdir option.

Back up the /home/ dsmc selective /home/dir1/ If you specify the

dir1/h1.doc and / h1.doc /home/dir1/test.doc removeoperandlimit option with the
home/dir1/test.doc incremental or selective
files. commands, the 20-operand limit is not
enforced and is restricted only by
available resources or other operating
system limits. This allows you to specify
more than 20 files on a single command.
See “Removeoperandlimit” on page 466
for more information about this option.
Back up the / dsmc selective /Users/ann/ If you specify the
Users/ann/Documents/ Documents/h1.doc /Users/ann/ removeoperandlimit option with the
h1.doc and / Documents/test.doc incremental or selective
Users/ann/Documents/ commands, the 20-operand limit is not
test.doc files. enforced and is restricted only by
available resources or other operating
system limits. This allows you to specify
more than 20 files on a single command.
See “Removeoperandlimit” on page 466
for more information about this option.
Back up a list of files in selective -filelist=/home/ Use the filelist option to process a
the /home/ filelist.txt list of files. See “Filelist” on page 387 for
filelist.txt file. more information.
Back up all files listed in dsmc selective -filelist=/ Use the filelist option to process a
the /Users/ Users/filelist.txt list of files. See “Filelist” on page 387 for
filelist.txt file. more information.

Chapter 4. Backing up your data 169

Table 36. Command-line backup examples (continued)
Task Command Considerations
Assuming that you dsmc selective /usr/dir1/sub1/ The client considers the snapshotroot
initiated a snapshot of -subdir=yes -snapshotroot=/ value as a file space name. See
the /usr file system and snapshot/day1 “Snapshotroot” on page 504 for more
mounted the snapshot information.
as /snapshot/day1, run
a selective backup of
the /usr/dir1/sub1
directory tree from the
local snapshot and
manage it on the IBM
Spectrum Protect server
under the file space
name /usr.

Related reference
“Incremental” on page 627
The incremental command backs up all new or changed data in the locations that you specify, unless
you exclude them from backup services.
“Selective” on page 698
The selective command backs up files that you specify. If you damage or mislay these files, you can
replace them with backup versions from the server.

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. To determine if you have this authority,
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.

About this task

Important: When you delete backup files, you cannot restore them. Verify that the backup files are no
longer needed before you delete them. The client 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.

Procedure
To delete backup copies using the backup-archive client GUI or web client:
1. Select Utilities > Delete Backup Data from the 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. Click the selection boxes next to objects that you want to delete.
4. 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.
5. Click Delete to begin deleting the selected items.

Results
Note:
• If you specify Delete Active Objects or Delete Inactive Objects, only the files are considered for
removal.

170 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • If you specify Delete Active Objects or Delete Inactive Objects and select a directory that contains no
files for removal, the following message is displayed during the delete backup operation:

ANS5030E No objects on server match query.

The last parent inactive directory is removed based on retention policy settings on the server.
• A directory is deleted only if you select Delete All Objects.
• To delete file spaces, click Utilities > Delete Filespaces from the main window.
• To delete backup copies using the command-line client, use the delete backup command.
Related reference
“Delete Backup” on page 618
The delete backup command deletes files, images, and virtual machines that were backed up to IBM
Spectrum Protect server storage. Your administrator must give you authority to delete objects.

Deleting file spaces

If your IBM Spectrum Protect administrator gives you authority, you can delete entire file spaces from the
server. When you delete a file space, you delete all the files and images, both backup versions and archive
copies, that are contained within the file space. For example, if you delete the /tmp file space, you are
deleting every backup for every file in that file system and every file you archived from that file system.
Carefully consider whether you want to delete a file space.

About this task

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.
You can delete individual backup versions by using the delete backup command.
You can delete file spaces using the backup-archive client GUI or command line clients. To delete NAS
file spaces, use the web client or command line client.
To delete a file space using the GUI, perform the following steps:

Procedure
1. Select Utilities > Delete Filespaces from the main window.
2. Click the selection boxes next to the file spaces you want to delete.
3. Click the Delete button. The client prompts you for confirmation before deleting the file space.
Related reference
“Class” on page 321
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.
“Delete Backup” on page 618
The delete backup command deletes files, images, and virtual machines that were backed up to IBM
Spectrum Protect server storage. Your administrator must give you authority to delete objects.
“Delete Filespace” on page 622

Chapter 4. Backing up your data 171

 The delete filespace command deletes file spaces in IBM Spectrum Protect server storage. A file
space is a logical space on the server that contains files you backed up or archived.

Backing up files from one or more file spaces for a group backup (UNIX and
Linux)
You can use the backup group command to create and back up a group containing a list of files from
one or more file space origins to a virtual file space on the IBM Spectrum Protect server.
Restriction: The backup group command does not apply to Mac OS X.
A group backup allows you to create a consistent point-in-time backup of a group of files that is managed
as a single logical entity:
• All objects in the group are assigned to the same management class.
• Existing exclude statements for any files in the group are ignored.
• All objects in the group are exported together.
• 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 using the mode option.
For example, to perform a full backup of all the files named in the /home/dir1/filelist1 file to the
virtual file space /virtfs containing the group leader /home/group1 file, enter:

dsmc backup group -filelist=/home/dir1/filelist1 -groupname=group1 -virtualfsname=

/virtfs -mode=full

Related concepts
“Restore data from a backup set” on page 216
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.
Related reference
“Backup Group” on page 600
Use the backup group command to create and back up a group containing a list of files from one or
more file space origins to a virtual file space on the IBM Spectrum Protect server.
“Include options” on page 403
The include options specify objects that you want to include for backup and archive services.
“Mode” on page 435
Use the mode option to specify the backup mode to use when performing specific backup operations.

Backing up data with client-node proxy support (UNIX and Linux)

Backups of multiple nodes that share storage can be consolidated to a common target node name on the
IBM Spectrum Protect server.

About this task

Consolidating backups from multiple nodes to a common target node name on the server is helpful in
configurations where the workstation that is responsible for performing the backups can change over
time, such as within a cluster.

172 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 An agent node is a client node that is granted authority to perform client operations on behalf of a target
node.
A target node is a client node that grants authority to one or more agent nodes to perform client
operations on its behalf.
Use the asnodename option with the appropriate command to back up, archive, restore, and retrieve data
under the target node name on the server.
The asnodename option also allows data to be restored from a different system than the one that
performed the backup.
Consider the following features when you use a proxy node to back up or restore data on other nodes:.
• A proxy operation uses the settigns 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.
• All of the agent nodes in the multiple node environment must be running the same operating system
type.
• Do not use target nodes as traditional nodes, especially if you encrypt your files before you back them
up to the server.
• You cannot access another node (either from the GUI drop-down or by using the fromnode option).
• You cannot perform NAS backup or restore.

Procedure
1. Install the backup-archive client on all nodes in a shared data environment.
2. Register each node with the IBM Spectrum Protect server. Register the common target node name to
be shared by each of the agent nodes that are used in your shared data environment.
3. Register each of the nodes in the shared data environment with the IBM Spectrum Protect server.
Register the agent node name that is used for authentication purposes. Data is not stored on the
server, under that node name, when the asnodename option is used.
4. The IBM Spectrum Protect server administrator must grant proxy authority to all nodes in the shared
environment to access the target node name by using the GRANT PROXYNODE command.
5. Use the QUERY PROXYNODE administrative client command to display the client nodes of the
authorized user that was granted by the GRANT PROXYNODE command.
Related reference
“Asnodename” on page 309
Use the asnodename option to allow agent nodes to back up or restore data on behalf of another node
(the target node). This enables concurrent operations from multiple nodes to store data to the same
target node and file space in parallel.

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 173

 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:
• Open the tree window and check that the target node name specified by the As Node Name field
appears.
• 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:
• If you change the encryption key, you must repeat the previous steps.
• 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 operations 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.
Start the schedules using dsmc sched client command:
The following examples show the administrative client-server commands using the scheduler on multiple
nodes.
• The administrator registers all of the nodes to be used by issuing the following commands:
– register node NODE-A
– register node NODE-B
– register node NODE-C
• The administrator grants proxy authority to each agent node using 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
• The administrator defines the schedules using the following commands:

174 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 – define schedule standard proxy1 description="NODE-A proxy schedule"
action=incremental options="-asnode=NODE-Z" objects=/Volumes/Xsan1
startdate=05/21/2005 starttime=01:00
– define schedule standard proxy2 description="NODE-B proxy schedule"
action=incremental options="-asnode=NODE-Z" objects=/Volumes/Xsan2
startdate=05/21/2005 starttime=01:00
– define schedule standard proxy3 description="NODE-C proxy schedule"
action=incremental options="-asnode=NODE-Z" objects=/Volumes/Xsan3
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.
You can also use the client acceptor daemon (dsmcad), with managedservices set to schedule in the
systems options file.
Note:
• Each schedule can be started from a different workstation or LPAR.
• After running the schedules, any proxied client can query and restore all of the backed up data.
• 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
Use the asnodename option to allow agent nodes to back up or restore data on behalf of another node
(the target node). This enables concurrent operations from multiple nodes to store data to the same
target node and file space in parallel.
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.
DEFINE SCHEDULE command

Examples of how to schedule a backup of an IBM PowerHA SystemMirror cluster

This section shows lists some examples of how to back up an IBM PowerHA SystemMirror cluster.

About this task

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>

In the following examples, IBM PowerHA SystemMirror is configured for two AIX hosts, host_a and
host_b. Along with their own local data, the hosts are sharing disk storage which has two file spaces: /
disk1 and /disk2.
The CLUSTERNODE example shows how the clusternode option is used in a current IBM PowerHA
SystemMirror environment.
• The administrator defines 3 nodes on the IBM Spectrum Protect server: host_a, host_b,
cluster_group, using the following commands: (1) REGISTER NODE host_a mysecretpa5s, (2)
REGISTER NODE host_b mysecretpa5s, (3) REGISTER NODE cluster_group mysecretpa5s.

Chapter 4. Backing up your data 175

 • The administrator defines a dsm.opt file on host_a and host_b (note that the opt files are different on
each host), using the following commands: (1) NODENAME host_a (option can be left as
default), (2) DOMAIN /home /usr ... etc..
• The administrator defines a dsm.opt file located somewhere on one of the cluster disk groups, for
example, /disk1/tsm/dsm.opt, using the following commands: (1) NODENAME cluster_group, (2)
DOMAIN /disk1 /disk2, (3) CLUSTERNODE YES.
• The administrator defines a schedule on the IBM Spectrum Protect server, using the following
command: DEFINE SCHEDULE STANDARD CLUSTER_BACKUP.
• The administrator defines associations for each of the 3 nodes, using the following command: DEFINE
ASSOC STANDARD CLUSTER_BACKUP host_a,host_b,cluster_group. At any one time, there are
three instances of the backup-archive client schedule running (with the scheduler for cluster_group
being part of the cluster resources that failover whenever the cluster group disk resources failover.
Thus, it would be running on either host_a or host_b but not both simultaneously).
• All three node names contain data on the IBM Spectrum Protect server.
The ASNODE example shows a generic solution which could be applied to UNIX cluster solutions to which
we do not have support, for example: Veritas Cluster Server for Solaris.
• The administrator defines 3 nodes on the IBM Spectrum Protect server host_a, host_b,
cluster_group:

REGISTER NODE host_a mysecretpa5s

REGISTER NODE host_b mysecretpa5s
REGISTER NODE cluster_group mysecretpa5s

• The administrator defines a proxy node relationship between host_a and host_b to hacmp_cluster

GRANT PROXYNODE TARGET=cluster_group AGENT=host_a,host_b

• The administrator defines a dsm.opt file on host_a and host_b to handle the local file systems:

NODENAME host_a (option can be left as default)

DOMAIN /home /usr ... etc.

NODENAME host_b (option can be left as default)

DOMAIN /home /usr ... etc.

• The administrator defines a dsm.opt file on the cluster resource to handle the backup of the clustered
resources, e.g. /disk1/tsm/dsmcluster.opt (the nodename is the default nodename, which is
either host_a or host_b, depending on which workstation contains the cluster group at any given
time):

DOMAIN /disk1 /disk2

ASNODE cluster_group

• The administrator defines a schedule on the IBM Spectrum Protect server:

DEFINE SCHEDULE STANDARD CLUSTER_BACKUP

• The administrator defines associations for each one of the 3 nodes.

DEFINE ASSOC STANDARD CLUSTER_BACKUP host_a,host_b,cluster_group

• At any one time, there are three instances of the backup-archive client schedule running with the
scheduler for node hacmp_cluster running on either host_a or host_b but not both (it is included in
the cluster resources that would failover). This scheduler would point to the dsmcluster.opt that is
defined on each host. The three instances would be started as:

[host_a] dsmc sched

[host_b] dsmc sched
[cluster_group] dsmc sched -optfile=/disk/tsm/dsmcluster.opt

• All three node names contain data on the IBM Spectrum Protect server.

176 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
For more information about the server scheduler commands, see the server documentation.

Scheduling a backup of a GPFS file system

Use the scheduler and proxy relationships to back up a GPFS file system.

About this task

Assume that three nodes in a GPFS cluster participate in the backup operation. Nodes node_1, node_2,
and node_3 are used for authentication only. The objects are backed up to file spaces that belong to node
node_gpfs.

Procedure
1. Define four nodes on the IBM Spectrum Protect server.

REGISTER NODE node_1 mysecretpa5s

REGISTER NODE node_2 mysecretpa5s

REGISTER NODE node_3 mysecretpa5s

REGISTER NODE node_gpfs mysecretpa5s

2. Define a proxy relationship between the nodes.

GRANT PROXYNODE TARGET=node_gpfs AGENT=node_1, node_2, node_3

3. Define a schedule.

DEFINE SCHEDULE STANDARD GPFS_SCHEDULE ACTION=incremental

OBJECTS="/gpfs"

DEFINE ASSOCIATION STANDARD GPFS_SCHEDULE node_gpfs

4. Choose one of the GPFS systems to run the schedule. Specify the nodename and asnodename options
in the dsm.sys options file on all systems in the GPFS cluster. The value for the asnodename option
must be the same on all systems.
Definitions in the dsm.sys options file on node 1:

nodename node_1
asnodename node_gpfs

Definitions in the dsm.sys options file on node 2:

nodename node_2
asnodename node_gpfs

Definitions in the dsm.sys options file on node 3:

nodename node_3
asnodename node_gpfs

5. Start the scheduler on the system that is chosen to run the schedule.

DSMC SCHED

Related information
mmbackup command: IBM Spectrum Protect requirements
Guidance for integrating IBM Spectrum Scale AFM with IBM Spectrum Protect
Considerations for using IBM Spectrum Protect include and exclude options with IBM Spectrum Scale
mmbackup command

Chapter 4. Backing up your data 177

Associate a local snapshot with a server file space (UNIX and Linux)
Use the snapshotroot option with the incremental and selective commands in conjunction 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.
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 504
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.

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.
You must be a root user to perform this task, and image backup does not apply to Mac OS X.
An image backup provides the following benefits:
• Backs up file systems that contain a large number of files faster than a full file system incremental
backup.
• Improves the speed with which the client restores file systems that contain many small files.
• Conserves resources on the server during backups since only one entry is required for the image.
• Provides a point-in-time picture of your logical volume, which might be useful if your enterprise must
recall that information.
• 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 static image backup prevents write access to the volume by other system applications
during the operation. Use the dynamicimage option to back up the volume as is, without remounting it
read-only. Corruption of the backup can occur if applications continue to write to the volume while the
backup is running. Writing to a volume while an image backup is running can result in inconsistent data
and data loss after a restore operation is run. The dynamicimage option overrides the copy serialization
value in the management class to perform an image backup. After restoring an image backup taken with
the dynamicimage option, always run the chkdsk utility.
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.
Restriction: Do not use dynamic image backups for file systems, because the file system might provide
inconsistent data even when there is no write activity. Also, dynamic image backup might result in a fuzzy
image, which might not be valid or complete when restored.
If the backup-archive client fails to mount the file system after it restores an image, run fsck. However,
running fsck can affect the integrity of large amounts of data. Do not use dynamic image backup for AIX
JFS2 file systems. The client does not allow dynamic image backup for AIX JFS2 file systems. If you
specify dynamicimage=yes for a JFS2 file system, the client performs a snapshot-based image backup.
If the snapshot cannot be created for some reason, the client instead performs a static image backup.
Attention: To prevent data loss, avoid using the dynamicimage option, and ensure that there is
no write activity on the volume while the backup is in progress.

178 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 For AIX JFS2 file systems, the amount of data that is backed up to the IBM Spectrum Protect server
during static or snapshot image backup is reduced by backing up only those blocks used by the file
system or smaller than the imagegapsize option. This method of backing up your data improves the
performance of image backup. For more information, see “Imagegapsize” on page 400.
For AIX clients only: By default, the client performs an online snapshot image backup of JFS2 file
systems, during which the volume is available to other system applications.
For Linux clients only: By default, the client performs a snapshot image backup of file systems that exist
on a logical volume that is created by the Linux Logical Volume Manager. The volume is available to other
system applications while the snapshot image backup is performed.
For Linux clients: Image backup of DASD devices with raw-track access mode on Linux on z Systems is
not supported.
The image backup operation is not supported on any partition that resides on a multipath device.
Attention: File systems that are managed by IBM Spectrum Protect for Space Management are
not enabled for image backup.
Related tasks
“Snapshot-based file backup and archive and snapshot-based image backup” on page 185
For backup-archive clients running on AIX 5.3 or later JFS2 file systems as root user, snapshot-based
image backup is created using snapshots by default.

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.
• Ensure that no other application is using the volume when you run a static image backup. To ensure a
consistent image during backup processing, if a file space is detected on the volume the client
unmounts and remounts the volume as read only, so that no other applications can write to it. If the
volume is in use when the client attempts to unmount, the backup fails. If the client cannot unmount
and remount the volume as read only because it is in use, and snapshot image backup is not available,
you can use the dynamicimage option to force the client to perform an image backup without
unmounting and remounting the volume in read-only mode. Set the dynamicimage option in an
include.image statement or from the command line. The backup can be corrupted if applications
write to the volume while the backup is in progress. This can be corrected by running fsck after a
restore to fix any corrupted blocks.
If no file system is detected on the volume being backed up, ensure that all applications writing to the
volumes are quiesced. The backup-archive client uses the file system table and mount table to detect
the supported file systems.
Do not include system files in an image backup because file systems being actively used cannot be
unmounted.
For AIX and Linux only: If you perform an image backup of a mounted file system which is mounted to
another mount point and specified in the file system table, then after completing the image backup, all
mount options for this file system, except read or write state, is lost.
Important: If a mounted file system has nested mount points, unmount them before attempting a
backup. Otherwise, the client is unable to unmount the volume. The file system is rendered busy if it
contains any mounts.
• 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.
• You can exclude a volume from image backup using the exclude.image option.
• You must use the mount point for the file system volume on which you want to perform an image
backup. The client will not back up a file system volume without the use of a mount point. Back up file

Chapter 4. Backing up your data 179

 systems using the mounted name. For example, if /dev/lv01 is formatted as a file system mounted
on /home, enter this command to perform an image backup of this volume:

dsmc backup image /home

Back up raw volumes using the device name. For example, if /dev/lv02 is a raw volume, enter this
command to perform an image backup of this volume:

dsmc backup image /dev/lv02

If you back up a raw volume which is formatted as a file system, ensure that the file system is not
mounted and does not have an entry in /etc/filesystems.
Related concepts
“Storage management policies” on page 265
Storage management policies are rules your administrator defines in order to manage your backups and
archives on the server.
Related reference
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.
“Include options” on page 403
The include options specify objects that you want to include for backup and archive services.

Volume device type support for an image backup

This topic lists several devices that are supported by the backup image command.
The following table lists the devices supported by the backup image command. A raw device might be a
disk slice, a partition, or a logical volume.

Table 37. Volume device-type support for an image backup

Logical volume manager Raw device types Sample device name Backup image command
support
AIX Logical Volume Mgr Logical Volumes /dev/lv00 AIX
Sun Solstice DiskSuite Metadevices /dev/md/dsk/dl Solaris
Volume Manager
Solaris Volume Manager Metadevices /dev/md/dsk/dl Solaris
Veritas Volume Mgr Logical Volumes /dev/vx/dsk/rootdg/vol01 Solaris
- AIX AIX
/dev/vg00/lvol01
- Solaris

Raw Disk Partitions /dev/hda1, /dev/sda3 Linux x86_64,

Linux on POWER

Raw Disk Disk devices /dev/sda Linux x86_64

/dev/mapper/mpathX

Raw Disk Partitions /dev/dasdxx Linux on System z

Linux Logical Volume Mgr Logical Volumes /dev/myvolgroup/ All Linux
myvolume

Raw Disk Disk Slices /dev/dsk/c0tld0s0 Solaris

180 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 For raw devices, the backup-archive client backs up the volume on an as-is basis. That is, no snapshot is
taken, and applications can continue to write to the volume while it is being backed up. IBM Spectrum
Protect cannot guarantee the consistency of the data when backing up at the physical disk level;
corruption can occur if the data on the volume is changing while the backup is in progress.
The client must support the raw device type on the specific platform in order to perform an image backup
of a raw device. If you want to perform an image backup for a file system mounted on a raw device, the
raw device must be supported. Remember to specify raw devices by their block device name.
For the Linux clients, image backup is only supported on partitions with id 0x83 or logical volumes
created with the Linux Logical Volume Manager. Backing up other partitions, such as extended partitions
that contain mounted file systems or database data, might produce inconsistent backup data if the data
changes during the image backup operation.
For AIX and Solaris: You can perform image operations on volumes created using Veritas Volume
Manager. The client initially supports static (default) and dynamic image type for backup.
For Solaris 10 clients, only use image backup for file systems that are assigned from the global zone to
the non-global zone by exporting the device, specifying add device and set match. Do not use image
backup for other file systems in the non-global zones because the non-global zone does not have the
authority to mount or unmount the file system. Also, for Solaris 10 clients, do not use the overlap device
of the root disk (c0t0d0s2) for raw device backup. Avoid using this feature on disks or slices that are used
as swapping devices.
Meta devices created by the Veritas Volume Manager must be listed, including the disk group in /etc/
vfstab, to be recognized by the backup-archive client for an image backup of file systems. The file
systems should be unmounted. Raw devices should not be listed in /etc/vfstab. For example, the
following is the correct meta device name to be used in the /etc/vfstab file:

/dev/vx/dsk/<disk group>/<meta device name>

Specifying /dev/vx/dsk/ would not be recognized correctly, and you would receive an error
(ANS1134E).
Disk slices containing cylinder 0 should not be backed up or restored. In this case the VTOC is
overwritten. If you need to back up the first disk slice, exclude cylinder 0 by starting the disk slice from
cylinder 1 (use the format utility). The backup-archive client does not check whether cylinder 0 is
contained in the device that is overwritten during a restore.

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.

Chapter 4. Backing up your data 181

 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
• Restores the most recent image on the server.
• 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.
• Restores new and changed files from the incremental backups.
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 Java GUI” on page 166
You can back up specific files, entire directories, or entire file systems from the directory tree.
“Performing an image backup using the GUI” on page 183
If the image backup feature is configured, you can create an image backup where the real volume is
available to other system applications.
“Restoring an image using the GUI” on page 214
You can use the GUI to restore an image of your file system or raw logical volume.

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:
• 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.
• 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:
• The file system can have no previous full incremental backups.

182 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • 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.
• If this is the first image backup for the file system, a full image backup is performed.
• 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 183
If the image backup feature is configured, you can create an image backup where the real volume is
available to other system applications.
“Restoring an image using the GUI” on page 214
You can use the GUI to restore an image of your file system or raw logical volume.

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 38. Comparing incremental image backup methods

Method 1: Using image backup with file system Method 2: Using image backup with incremental-
incremental by-date image backup
Files are expired on the server when they are Files are not expired on server. After the image
deleted from the file system. On restore, you have incremental restore completes, all of the files that
the option to delete files which are expired on are deleted on the file system after the image
server from 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 image backup is faster because the
incremental backups. client does not query the server for each file that is
copied.
Restore is much faster compared to a full Restore is much faster compared to a full
incremental file system restore. incremental file system restore.
Directories deleted from the file system after the Directories and files deleted from the file system
last image backup are not expired. 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 backup-archive client GUI image backup option, the
backup operation is run according to the setting of the snapshotproviderimage option. The
snapshotproviderimage option defaults to an AIX JFS2 snapshot for AIX and a Linux LVM snapshot
for Linux. You can override the default by using the Preferences editor Snapshot tab and the Image
Snapshot Preferences.
For Solaris clients, selecting the image backup option performs a static image backup by default. For
static image backup, the client unmounts and remounts the volume as read-only, so that no other
applications can access it. You can override the default value by using the include.image option and

Chapter 4. Backing up your data 183

 selecting dynamicimage yes. For dynamic image backup, the client performs the image backup without
making the file system read-only during the backup.
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.

Results
• To perform a static image backup, select Image Backup from the drop-down list.
• For AIX and Linux clients only: To perform a snapshot image backup, use the
snapshotproviderimage option.
• 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 snapshot-based image backup:
• To modify specific backup options, click the Options button. The options you select are effective only
during the current session.
• To modify specific backup options, click the Options button. The options you select are effective only
during the current session.
Linux only: The IBM Spectrum Protect Version 5.4 (and newer) client will not recognize any LVM1 volumes
for image operations. However, it allows prior image backups of LVM1 volumes to be restored on LVM2
volumes. Table 39 on page 184 shows the combinations involving the old and new client levels handling
LVM1 and LVM2 volumes for different image operations.

Table 39. LVM1 and LVM2 image operation comparisons

Mixed Volumes
IBM Spectrum
Protect client LVM1 Backup and LVM2 Backup and Backup: LVM1, Backup: LVM2,
version Restore Restore Restore: LVM2 Restore: LVM1
V5.3 and prior YES Only static image for NO NO - raw volumes
file system are not supported
V5.4 and beyond YES
NO YES NO
Error msg LVM1 vol must have Restore to LVM1 vol
ANS1090E been backed up fails
displayed using prior client

Related reference
“Snapshotproviderimage” on page 504

184 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Use the snapshotproviderimage option to enable snapshot-based image backup, and to specify a
snapshot provider.

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.
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 602
The backup image command creates an image backup of one or more volumes on your system.
“Mode” on page 435
Use the mode option to specify the backup mode to use when performing specific backup operations.
“Restore Image” on page 677
The restore image command restores a file system or raw volume image that was backed up using the
backup image command.

Snapshot-based file backup and archive and snapshot-based image backup

For backup-archive clients running on AIX 5.3 or later JFS2 file systems as root user, snapshot-based
image backup is created using snapshots by default.

About this task

Optionally, you can enable snapshot-based file level backup and archive operations by specifying the
snapshotproviderfs option. If for some reason a snapshot cannot be taken, the client attempts to
perform a static image backup or regular file backup.
If you want to specify snapshot-based file backup and archive, set the option snapshotproviderfs to
JFS2. This is applicable to all JFS2 file systems for that client.
Important: Use snapshot-based file backup and archive and snapshot-based image backup for all of your
AIX JFS2 file systems.
For example, to turn on snapshot-based file backup and archive for all JFS2 file systems on the client,
specify the following in the server stanza in the dsm.sys file:

snapshotproviderfs JFS2

To explicitly turn off snapshot-based file backup and archive for all JFS2 file systems on the client, specify
the following in the server stanza in the dsm.sys file:

snapshotproviderfs NONE

To turn on snapshot-based file backup and archive for only one specific JFS2 file system on the client,
specify the following in the server stanza in the dsm.sys file:

snapshotproviderfs NONE

include.fs /kalafs1 snapshotproviderfs=JFS2

To turn off snapshot-based file backup and archive for only one specific JFS2 file system on the client,
specify the following in the server stanza in the dsm.sys file:

snapshotproviderfs JFS2

include.fs /kalafs2 snapshotproviderfs=NONE

Chapter 4. Backing up your data 185

 To turn on snapshot-based file backup and archive for only one specific operation on the client, specify
the following on the command line:

dsmc incr -snapshotproviderfs=JFS2 /kalafs1

To turn off snapshot-based file backup and archive for only one specific operation on the client, specify
the following in the server stanza in the dsm.sys file:

snapshotproviderfs JFS2

Then perform the backup command. For example:

dsmc incr -snapshotproviderfs=NONE /kalafs2

Related reference
“Snapshotproviderfs” on page 503
Use the snapshotproviderfs option to enable snapshot-based file backup and archive operations, and
to specify a snapshot provider.

Protecting Btrfs file systems

Btrfs file systems can be included as file specifications for backup and restore commands, archive and
retrieve commands, and on backup image and restore image commands. You can also specify Btrfs
subvolumes as file specification to the backup and restore, and archive and retrieve functions. You cannot
use the backup-archive client image backup or image restore commands on a Btrfs subvolume.
Btrfs file systems are supported on SLES 11 SP2, or later, on IBMSystem x, System p, and System z.
If you want to create a static image backup of the entire Btrfs file system, you must unmount all the
subvolumes so the backup-archive client can unmount or mount the Btrfs file system during the backup
process. You can avoid the mounting and unmounting requirements if you perform a snapshot-based
image backup of the Btrfs file system instead of a static image backup.
Image backup and image restore functionality is not available for Btrfs subvolumes. If you try to back up a
subvolume by using the image backup, the following message is displayed:
ANS1162E Filesystem could not be mounted

You can mount a Btrfs subvolume by using either the subvolume name or the subvolume ID.
On Btrfs file systems, journal backup can be performed both at the file system and the subvolume level. If
you perform journal-based backups on a Btrfs file system, the journal that is created is for the entire file
system; there is not a separate journal for each subvolume.
Restriction: On Linux systems, some file systems such as ext2, ext3, ext4, btrfs, and xfs use a universally
unique identifier (UUID) to identify themselves to the operating system. If you create an image backup of
such a volume and you restore it to a different location, you might have two volumes with the same UUID.
If you use UUID to define your file systems in /etc/fstab, be aware that the backup-archive client
might be unable to correctly mount the restored file system because the UUIDs conflict. To avoid this
situation, restore the image to its original location. If you must restore it to a different location, change
the UUID of either the original or restored volume before you mount the restored file system. Refer to the
Linux documentation for instructions on how to change a UUID. You might also need to manually edit
the /etc/fstab file so the original volume, the restored volume, or both volumes can be mounted.

186 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Backing up and restoring Btrfs file systems
You can back up or restore, or archive and retrieve, Btrfs file systems by using the backup-archive client
incremental, selective, restore, archive, and retrieve commands.

About this task

If you used a version of the backup-archive client that is older than Version 7.1 to back up a Btrfs file
system, the file system type was listed as Unknown, in the IBM Spectrum Protect server GUI and
command output. The Unknown file system type is displayed because before IBM Spectrum Protect 7.1,
Btrfs file systems were not formally supported. If you use a backup-archive V7.1 client (or newer) to back
up that same Btrfs file system, all files that have Access Control Lists (ACLs) and extended attributes
(XATTRs) are backed up again, even if their content has not changed since the last backup that was
created by the older version of the client. Also, after a Btrfs file system is backed up by the V7.1 (or
newer) client, the file system type is correctly shown as Btrfs in the IBM Spectrum Protect server GUI
and command output.
Even with a V7.1 or newer client, copying a file on a Btrfs file system might cause the file to be included in
the next backup operation. For example, if you copy a file by using the cp command with the -p or -
preserve options (preserve mode, ownership, and time stamps), and if the file’s attributes are changed,
the access ACL extended attribute (system.posix_acl_access) is changed. Because an extended attribute
is changed, the client backs up the entire file, rather than just updating the attributes for the file.

Procedure
1. Mount the file system that you want to protect or recover.
For example, use the following syntax to mount a file system: mount /dev/sdb1 on /btreefs1
type btrfs (rw)
2. Protect or recover the file system by performing one of the following operations:
Operation Command

Back up the file dsmc incr /btreefs1

system

Restore the file dsmc restore /btreefs1/

system -subdir=yes -replace=yes

Archive the file dsmc archive /btreefs1/

system -subdir=yes

Retrieve the file dsmc retrieve /btreefs1/

system -subdir=yes -replace=yes

Back up a file Create the file system snapshot. Use the btrfs subvolume snapshot
system snapshot command. The snapshot directory that is specified in this example is the
btreefs1_snap directory on the file system named /btreefs1.

btrfs subvolume snapshot /btreefs1/

/btreefs1/btreefs1_snap

Issue the backup-archive client incremental command. Specify the

snapshotroot option and the location of the Btrfs snapshot.

$DSM_DIR/dsmc incr /btreefs1

-snapshotroot=/btreefs1/btreefs1_snap

Perform an image All subvolumes must be unmounted before you create an image backup.
backup

Chapter 4. Backing up your data 187

 Operation Command

dsmc backup image /btreefs1

-snapshotproviderimage=none

To avoid having to unmount the subvolumes, create a snapshot-based image

backup.

dsmc backup image /btreefs1

Restore an image All subvolumes must be unmounted before you restore an image backup.
backup
dsmc restore image /btreefs1

Backing up and restoring Btrfs subvolumes

You can back up or restore, or archive and retrieve, Btrfs subvolumes by using the backup-archive client
incremental, selective, restore, archive, and retrieve commands.

Procedure
1. List the subvolumes and determine their IDs.

btrfs subvolume list /btreefs1

ID 256 top level 5 path @
ID 262 top level 5 path @/btreefs1_sub1

2. Make the directory to use as the mount point for the subvolume.

mkdir /btreefs1_sub1

3. Mount the subvolume.

For example, to mount the subvolume on device sdb1 at /btreefs1_sub1, use the following syntax:
mount -t btrfs -o subvolid=262 /dev/sdb1 /btreefs1_sub1
Protect or recover the subvolume by using one or more of the following operations:

Operation Command
Back up a subvolume Both incremental and selective backups are supported.

dsmc incr /btreefs1_sub1

dsmc sel /btreefs1_sub1/ -subdir=yes

Restore a subvolume dsmc restore /btreefs1_sub1/

-subdir=yes -replace=yes

Archive a subvolume dsmc archive /btreefs1_sub1/

-subdir=yes

Retrieve a subvolume dsmc retrieve /btreefs1_sub1/

-subdir=yes -replace=yes

Back up a Btrfs Create the subvolume snapshot. Use the btrfs subvolume snapshot
subvolume snapshot command. The snapshot directory that is specified in this example is the /

188 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Operation Command
btreefs1/btreefs1_sub1_snap directory, for the subvolume named
btreefs1_sub1.

btrfs subvolume snapshot

/btreefs1/btreefs1_sub1
/btreefs1/btreefs1_sub1_snap

Issue the backup-archive client incremental command. Specify the snapshot

root option and the location of the Btrfs snapshot.

dsmc incr /btreefs1_sub1

-snapshotroot=/btreefs1
/btreefs1_sub1_snap

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:
• LAN-free data transfer.
• High performance and scalable backups and restores.
• Backup to local tape devices without network traffic.
The following support is provided:
• Full file system image backup of all files within a NAS file system.
• Differential file system image backup of all files that have changed since the last full image backup.
• Parallel backup and restore operations when processing multiple NAS file systems.
• Choice of interfaces to initiate, monitor, or cancel backup and restore operations:
– Backup-archive client GUI (available only for connections to IBM Spectrum Protect Version 8.1.2 or
later servers, or V7.1.8 or later V7 servers)
– The backup-archive client command line interface (available only for connections to IBM Spectrum
Protect V8.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:
• Archive and retrieve

Chapter 4. Backing up your data 189

 • Client scheduling. Use server commands to schedule a NAS backup.
• Detection of damaged files.
• Data-transfer operations for NAS data stored by IBM Spectrum Protect:
– Migration
– Reclamation
– Export
– Backup set generation
Related concepts
“NDMP support requirements (Extended Edition only)” on page 8
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.
“Processing NAS file systems” on page 409
Use the include.fs.nas option to bind a management class to NAS file systems and to control whether
Table of Contents information is saved for the file system backup.
Related reference
“Diffsnapshot” on page 343
The diffsnapshot option controls whether the backup-archive client creates the differential snapshot
when it runs a snapshot difference incremental backup.
“Incremental” on page 627
The incremental command backs up all new or changed data in the locations that you specify, unless
you exclude them from backup services.
“Snapdiff” on page 494
Using the snapdiff (snapshot difference) option with the incremental command streamlines the
incremental backup process. The command runs an incremental backup of the files that were reported as
changed by NetApp instead of scanning all of the volume for changed files.
“Snapshotroot” on page 504
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.

Backing up NAS file systems with the backup-archive client GUI using NDMP protocol
For both the backup-archive client GUI and the client command line interface, you must specify
passwordaccess=generate 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 backup-archive client GUI. The IBM Spectrum Protect
server must be configured to grant authority to the client node for NAS backup and restore operations.
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 backup-archive client GUI 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 backup-archive client GUI must be connected to the IBM Spectrum Protect Version 8.1.2 or later
server, or V7.1.8 or later V7 server.
To back up NAS file systems using the backup-archive client GUI:
1. Click Backup from the main window. The Backup window is displayed.

190 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 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 backup-archive client GUI 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.
Consider the following items when you back up NAS file systems using the backup-archive client GUI:
• 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).
• 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.
• To delete NAS file spaces, select Utilities > Delete Filespaces.
• Backup options do not apply to NAS file spaces and are ignored during a NAS backup operation.
Related concepts
“Processing NAS file systems” on page 409
Use the include.fs.nas option to bind a management class to NAS file systems and to control whether
Table of Contents information is saved for the file system backup.
“Restore NAS file systems” on page 229
You restore NAS file system images using the backup-archive client GUI or command line interface.
Related reference
“Toc” on page 531
Use the toc option with the backup nas command or the include.fs.nas option to specify whether
the backup-archive client saves table of contents (TOC) information for each file system backup.
Related information
Configuring the server to grant authority to a client node for NAS backup and restore operations

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).

Chapter 4. Backing up your data 191

 Table 40 on page 192 lists the commands and options that you can use to back up NAS file system
images from the command line.

Table 40. NAS options and commands

Option or command Definition Page
domain.nas Use the domain.nas option to specify the volumes “Domain.nas” on page
to include in your default domain for NAS backups. 354
exclude.fs.nas Use the exclude.fs.nas option to exclude file “Exclude options” on
systems on the NAS file server from an image page 374
backup when used with the backup nas
command.
This option is for AIX and Solaris clients only.

include.fs.nas Use the include.fs.nas option to bind a “Include options” on

management class to Network Attached Storage page 403
(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..
This option is for AIX and Solaris clients only.

query node Use the query node command to display all the “Query Node” on page
nodes for which a particular administrative user ID 654
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 NAS” on page
backup of one or more file systems that belong to a 606
Network Attached Storage (NAS) file server.
toc Use the toc option with the backup nas “Toc” on page 531
command or the include.fs.nas option to
specify whether Table of Contents (TOC)
information is saved for each file system backup.
monitor process Use the monitor process command to display “Monitor Process” on
current backup and restore processes for all NAS page 635
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 NAS page 615
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 “Query Backup” on page
option to display information about file system 640
images backed up for a NAS file server.
query filespace Use the query filespace command with the “Query Filespace” on
class option to display a list of file spaces page 646
belonging to a NAS node.

192 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 40. NAS options and commands (continued)
Option or command Definition Page
delete filespace Use the delete filespace command with the “Delete Filespace” on
class option to display a list of file spaces page 622
belonging to a NAS node so that you can choose
one to delete.

• 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 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.
• Regardless of client platform, NAS file system specifications use the forward slash (/) separator, as in
this example: /vol/vol0.
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 531
Use the toc option with the backup nas command or the include.fs.nas option to specify whether
the backup-archive client saves table of contents (TOC) information for each file system backup.

Backup network file systems

You can configure the backup-archive client to protect files that are accessed with either Network File
System (NFS) or Common Internet File System (CIFS) protocols.
Backup performance is better when you install the backup-archive client where the file system physically
exists. But sometimes it is necessary to access file systems by using NFS or CIFS to back up or recover
data on remote shared drives. The backup-archive client on AIX, Linux, Mac OS X, and Solaris operating
systems can back up, archive, restore, and retrieve file data on an NFS or CIFS-mounted shared drive. The
operations are valid on all versions of the NFS protocol, including NFS version 2, NFS version 3, and NFS
version 4.
The backup-archive can back up and restore access control lists when it is configured to use NFS version
4.
The following restrictions apply when the backup-archive client protects data on network file system
volumes:
• Backup-archive clients cannot complete image backups of network file system volumes.
• Backup-archive clients on AIX cannot complete snapshot-based file backups or archive files on network
file system volumes.
• Backup-archive clients cannot complete journal-based backups of network file system volumes.
• Backup-archive clients might not be able to back up NetApp volume snapshots if they are accessed by
using the NFS protocol. If the NetApp filer provides different device identifiers for its volume snapshots,
these snapshots might be excluded from backups. The behavior depends on the OS version, the NetApp
filer version, and the settings.

Back up NFS file systems with the global namespace feature

NFS V4 clients can back up NFS file systems that are mounted by using the global namespace feature,
which is called a referral. All file systems in the global namespace are backed up under a single file space.
The following examples show the file systems in the global namespace that are backed up under a single
file space:

Chapter 4. Backing up your data 193

 server 'publications' has /doc file system
server 'projects' has /projects file system
server 'data' has /data file system

The server account1 is the main NFS server that exports all these files systems by using a referral, and it
is the server that all of the clients recognize. The /etc/exports directory on account1 looks like the
following examples:

/doc -vers=4,refer=/doc@publications
/projects -vers=4,refer=/projects@projects
/data -vers=4,refer=/data@data

The client payroll mounts directories from the account1 server and can access all three file systems:

payroll:/#mount -o vers=4 account1:/ /mnt

payroll:/#ls /mnt
doc/ projects/ data/

The client payroll can back up the /mnt file as one NFS file system, which backs up all other file systems.
Important: Using the virtualmountpoint option can improve system performance when you back up
NFSV4 file systems by using the global namespace. Add the following entries in a stanza in dsm.sys to
back up each mounted directory as a separate file space:

VIRTUALMOUNTPOINT /doc
VIRTUALMOUNTPOINT /projects
VIRTUALMOUNTPOINT /data

Back up AIX workload partition file systems

Using the backup-archive client on AIX, you can back up and restore local partition file data within the
global partition by using the local partition name space available within the global partition.
Each workload partition (WPAR) has its own security domain, so only the global root user is guaranteed to
have access to all of the data.
The WPARs are partitions that are created entirely in software within a single AIX system image, with the
following attributes:
• Usually the WPAR appears to be a complete stand-alone AIX system
• There is no hardware assist or configuration
Workload partitions provide a secure and isolated environment for enterprise applications in terms of
process, signal, and file system space. Software running within the context of a workload partition
appears to have its own separate instance of AIX.
The following example shows a WPAR configuration from within the global WPAR:
Global partition:
System name: shimla
File system: /home /opt
WPAR #1 configuration:
Name: wpar1
File system: /home; name in global WPAR: /wpars/wpar1/home
WPAR #2 configuration:
Name: wpar2
File system: /data; name in global WPAR: /wpars/wpar2/data
There are two ways to back up WPAR data, as follows:
• Back up all WPAR file systems as the file spaces within the global partition. The file space name must be
used to identify the WPAR to which it belongs. All of the data is managed on one node by using one

194 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 schedule. Using the example configuration, here is a sample dsm.sys file with one server stanza for all
file systems, both global and local:

SErvername shimla
TCPPort 1500
TCPServeraddress server.example.com
nodename shimla
PasswordAccess generate
Domain /wpars/wpar1/home /wpars/wpar2/data /home /opt

• Back up each WPAR file system under a different node name. This method provides file space name
segregation for each WPAR. Each WPAR must have a separate node name and a scheduler that is
running within the global partition. Also, three scheduler services must be set up, each using a different
dsm.opt file corresponding to the server stanza name. This method allows each WPAR backup
operation to be managed independently of the others. Using the example configuration, here is a
sample dsm.sys file with three server stanzas: one for wpar1, one for wpar2, and one for global
partition shimla:

SErvername shimla_wpar1
TCPPort 1500
TCPServeraddress server.example.com
nodename wpar1
PasswordAccess generate
Domain /wpars/wpar1/home

SErvername shimla_wpar2
TCPPort 1500
TCPServeraddress server.example.com
nodename wpar2
PasswordAccess generate
Domain /wpars/wpar2/data

SErvername shimla
TCPPort 1500
TCPServeraddress server.example.com
nodename shimla
PasswordAccess generate
Domain /home /opt

Backing up Solaris Zettabyte file systems

On Solaris SPARC and Solaris x86 systems, you can backup Zettabyte file systems (ZFS), by using ZFS
snapshots. The advantage of this approach, over an ordinary incremental or selective backup, is that the
files and folders in a snapshot are always in a read-only state, so they cannot be changed during a
backup.

About this task

You create a ZFS snapshot by using Oracle Solaris ZFS commands. For example:

zfs snapshot tank/myZFS@mySnapshot

In this example, the ZFS pool name is called tank and the ZFS file system name is myZFS. Files that
belong to this ZFS snapshot are in the subdirectory named tank/myZFS/.zfs/snapshot/
mySnapshot/.

Procedure
Use either of these two methods to backup a ZFS snapshot.
• Backup each file of the snapshot by using the snapshotroot option.
For example:

dsmc inc -snapshotroot=/tank/myZFS/.zfs/snapshot/mySnapshot /tank/myZFS

Chapter 4. Backing up your data 195

 This option allows the administrator to replace the current snapshot path with the ZFS file system
path, so that the files and folders are backed up under the original file system.
• Backup the complete snapshot by using Oracle Solaris ZFS commands.
For example:

zfs send tank/myZFS@mySnapshot > /tmpdir/mySnapshotFile

The advantage of backing up the complete snapshot is that the full file system can be restored, in a
disaster recovery scenario.
Related concepts
“Restoring Solaris Zettabyte (ZFS) file systems” on page 235
Zettabyte File Systems (ZFS) use storage pools to manage physical storage.
Related reference
“Snapshotroot” on page 504
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.

AIX JFS2 encrypted file system backup

Use AIX JFS2 Encrypted File System (EFS) to back up files either in clear text or raw format. With clear
text format, the file is decrypted by EFS as it is read. With raw format, the data is not decrypted. The
default is raw format, but when you set the efsdecrypt option to yes, you get clear text backups.

About this task

Important: Whenever you run a backup that includes any files encrypted on an EFS, you must ensure that
you use the correct specification of the efsdecrypt option. If the efsdecrypt option value changes
between two incremental backups, all encrypted files on EFS file systems are backed up again, even if
they have not changed since the last backup. For example, if you are running an incremental backup of
encrypted files that were previously backed up as raw, then ensure that efsdecrypt is specified as no.
If you change efsdecrypt to yes, all of the files are backed up again in clear text even if they are
unchanged, so ensure that you use this option carefully.
If you attempt to restore an encrypted file to either a work station that does not support EFS, or a file
system where EFS is not active, an error message is written and the file is skipped.
Here are some reasons to back up EFS using clear text encryption:
• This type of decryption is useful if you want to use the IBM Spectrum Protect backup-archive client
encryption or another type of hardware encryption (for tape systems, for example).
• You can use clear text for long term archival of data, because the data is stored independent of the
platform or encryption scheme.
Here are some things to consider when backing up a file in clear text:
• The user who invoked the backup-archive client must be able to decrypt it
• The user can have read access to a file, but not have access to the key
In the following scenarios an error message is issued:

Procedure
1. The user is running in root guard mode, and EFS has the concept of two types of root. Root admin is
the traditional mode. A root in guard mode will not have access to the unencrypted data, unless the
user is the owner or a member of the file group.

196 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 2. The user is running with a non-root user ID and attempting an archive of a file to which they have read
access, but the user is not the owner or member of the file group. EFS will not allow the data to be
decrypted.

Results
Here are some considerations when backing up EFS raw data:
• The backup-archive client will not honor the client encryption setting, which prevents double
encryption, but only at the client. The server has no knowledge that the data is encrypted so any
encryption done by a tape drive, for example, still occurs.
• The client will not honor the compression setting, so the client will not even try to compress the data.
• The client does not automatically back up or restore the keystore files. When you are restoring
encrypted files, you might also have to restore keystores in order to decrypt the data.
Tips:
1. To protect the keystore, make sure the contents of /var/efs are included in your periodic backups.
2. For the keystore data, use IBM Spectrum Protect storage policy with an unlimited number of
versions.
• Encrypted file system (EFS) files backed up in raw mode (default) cannot be restored by a backup-
archive client prior to V5.5, or by a client on another UNIX platform.

Back up AIX JFS2 extended attributes

AIX Enhanced Journal File System (JFS2) provides backup processing for named extended attributes for
all file systems that support named extended attributes.
These extended attributes are automatically backed up with each object that contains extended
attributes data, and no additional action is required.
When the file system is defined with the v2 format, the only file system that supports named extended
attributes is JFS2. You can use JFS2 for extended attributes for files and directories, but you cannot use
JFS2 for extended attributes on symbolic links.

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 41 on page 198 lists the backup and restore capabilities for VMware virtual machines that the
backup-archive client can implement on Linux platforms.

Chapter 4. Backing up your data 197

Table 41. Backup and restore capabilities for VMware virtual machines on Linux platforms
Capability Comment

Full VM incremental- A full VM backup is required before you can create incremental backups. If you
forever backup: 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-forever- Requires you to create a full VM backup one time only. The full VM backup copies
incremental VM backup: 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-forever-incremental 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-forever-incremental backup.
The incremental-forever-incremental backup mode provides the following
benefits:
• Improves the efficiency of backing up virtual machines.
• Simplifies data restore operations.
• 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.

Item recovery for files and Provides the capability to recover files and folders from a full backup of a virtual
folders from a full backup machine. Item recovery is available only with the IBM Spectrum Protect recovery
of the virtual machine: agent.

Full restore of the virtual Restores all of the file systems, virtual disks, and the virtual machine
machine: configuration.

Related concepts
“Parallel backups of virtual machines” on page 202
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.
Related tasks
“Preparing the environment for full backups of VMware virtual machines” on page 199

198 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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.
“Creating full backups for VMware virtual machines” on page 200
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.

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:
• 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.
• 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:
a) Set and export the LD_LIBRARY_PATH environment variable to point to the client installation
directory. For example:
export LD_LIBRARY_PATH=/opt/tivoli/tsm/client/ba/bin
b) Add the client installation directory to the path of each account that uses backup-archive client
commands, for example, dsmc, dsmcad, or dsmj.
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

Where my_server_name is the full computer name of the vStorage backup server and my_password
is the password to access the server.

Related tasks
“Creating full backups for VMware virtual machines” on page 200
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 199

 Related reference
“Backup VM” on page 608
“Query VM” on page 659
Use the query VM command to list and verify the successful backups of virtual machines (VMs).
“Restore VM” on page 681
Use the restore vm command to restore a virtual machine (VM) that was previously backed up.
“Vmchost” on page 545
Use the vmchost option with the backup VM, restore VM, or query VM commands to specify the host
name of the VMware VirtualCenter or ESX server that you want to backup, restore, or query.
“Vmcpw” on page 546
Use the vmcpw option with the backup VM, restore VM, or query VM commands to specify the
password for the VMware VirtualCenter or the ESX user ID that is specified with the vmcuser option.
“Vmcuser” on page 548
Use the vmcuser option with the backup VM, restore VM, or query VM commands to specify the user
name of the VMware VirtualCenter or ESX server that you want to backup, restore, or query.
“Vmvstortransport” on page 580
The vmvstortransport option specifies the preferred transports order (hierarchy) to use when backing
up or restoring VMware virtual machines. If you do not include a given transport using this option, that
transport is excluded and is not used to transfer data.

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.

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 199
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:

200 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 backed up successfully: 1
virtual machine vmname backed up to nodename NODE
Total number of virtual machines failed: 0
Total number of virtual machines 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

b) If errors occur in the restore processing, view the client error log for more information.
Tip: The log file is saved to /opt/ibm/Tivoli/TSM/baclient/dsmerror.log
Related concepts
“Parallel backups of virtual machines” on page 202
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.
Related tasks
“Preparing the environment for full backups of VMware virtual machines” on page 199
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.
Related reference
“Backup VM” on page 608
“Domain.vmfull” on page 355
The domain.vmfull option specifies the virtual machines (VMs) to include in your full virtual machine
image backup operations.
“Query VM” on page 659
Use the query VM command to list and verify the successful backups of virtual machines (VMs).
“Restore VM” on page 681
Use the restore vm command to restore a virtual machine (VM) that was previously backed up.
“Mode” on page 435
Use the mode option to specify the backup mode to use when performing specific backup operations.
“Vmchost” on page 545
Use the vmchost option with the backup VM, restore VM, or query VM commands to specify the host
name of the VMware VirtualCenter or ESX server that you want to backup, restore, or query.
“Vmcpw” on page 546
Use the vmcpw option with the backup VM, restore VM, or query VM commands to specify the
password for the VMware VirtualCenter or the ESX user ID that is specified with the vmcuser option.
“Vmcuser” on page 548
Use the vmcuser option with the backup VM, restore VM, or query VM commands to specify the user
name of the VMware VirtualCenter or ESX server that you want to backup, restore, or query.
“Vmmc” on page 564
Use the vmmc option to store virtual machine backups by using a management class other than the
default management class. For VMware VM backups, the vmmc option is valid only if the
vmbackuptype=fullvm option is set.
“Vmvstortransport” on page 580

Chapter 4. Backing up your data 201

 The vmvstortransport option specifies the preferred transports order (hierarchy) to use when backing
up or restoring VMware virtual machines. If you do not include a given transport using this option, that
transport is excluded and is not used to transfer data.

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 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 8
Before you can back up or archive your FastBack client data, you must install the required software.
“Configuring the client to back up and archive Tivoli Storage Manager FastBack data” on page 94
Before you can back up or archive Tivoli Storage Manager FastBack client data, you must complete
configuration tasks.
Related reference
“Fbclientname” on page 382
Use the fbclientname option with the backup fastback or archive fastback commands.
“Fbpolicyname” on page 383
Use the fbpolicyname option with the backup fastback or archive fastback commands.
“Fbvolumename” on page 386
Use the fbvolumename option with the backup fastback or archive fastback commands.

Display backup processing status

During a backup, by default the backup-archive client displays the status of each file it attempts to back
up.
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 Java 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 42 on page 203 lists some informational messages and meanings.

202 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 42. Client command line informational messages
Informational message Meaning
Directory--> Indicates the directory that you back up.
Normal File-->. Any file that is not a directory, symbolic link, or special file.
Special File--> Special files define devices for the system or temporary files that are
created by processes. There are three basic types of special files:
FIFO (first-in, first-out), block, and character. FIFO files are also
called pipes. Pipes are created by one process to temporarily allow
communication with another process. These files cease to exist when
the first process finishes. Block and character files define devices.
The client processes only device and named pipe special files. Socket
special files are not processed.
Symbolic Link--> Indicates that the client backs up a symbolic link.
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 As indicated. When using journal-based backup, the number of
inspected: 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 As indicated.

backed up:
Total number of objects This is a count of the objects that were encrypted during backup or
encrypted: 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 These are files whose attributes, such as file owner or file
updated: permissions, have changed.
Total number of objects See “Bind management classes to files” on page 273 for more
rebound: information.
Total number of objects This is a count of the objects that are deleted from the client
deleted: workstation after being successfully archived on the server. The
count is zero for all backup commands.
Total number of objects See the section about full and partial incremental backup for more
expired: information.
Total number of objects Objects can fail for several reasons. Check the dsmerror.log for
failed: details.
Total snapshot difference For snapshot difference incremental backups, this represents the
objects: total number of objects backed up and the total number of objects
expired.
Total objects deduplicated: Specifies the number of files that are deduplicated.

Chapter 4. Backing up your data 203

Table 42. Client command line informational messages (continued)
Informational message Meaning
Total number of bytes Specifies the sum of the sizes of the files that are selected for the
inspected: operation. For example, the total number of bytes that are inspected
for this command is the number of bytes that are used on the
volume /Volumes/BUILD:

dsmc INCREMENTAL /Volumes/BUILD/* -SU=Yes

Total bytes before Specifies the number of bytes to send to the IBM Spectrum Protect
deduplication: 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.
Total bytes after Specifies the number of bytes that are sent to the IBM Spectrum
deduplication: 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 Specifies the sum of the sizes of the files that are processed for the
processed: operation.
Data transfer time: The sum of the times that each backup, archive, restore, or retrieve
session takes to send data across the network. This number does not
include the time for the client to read the data from disk before the
data is sent, nor the time to wait for server transactions to complete.
This number can be greater than the elapsed processing time if the
operation uses multiple concurrent sessions to move data, such as
multi-session backup and restore operations.
This number includes the time that it takes to send data more than
once due to retries, such as when a file changes during a backup
operation.

Network data transfer rate: The average rate at which the network transfers data between the
client and the server. This statistic is calculated by dividing the total
number of bytes transferred by the time to transfer the data over the
network. This statistic does not include the time for the client to read
the data from disk before the data is sent, nor the time to wait for
server transactions to complete.
Aggregate data transfer rate: The total number of bytes transferred during a backup, archive,
restore, or retrieve operation, divided by the total elapsed time of the
operation.
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%

204 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 42. Client command line informational messages (continued)
Informational message Meaning
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.
Total number of bytes The total number of bytes transferred during the backup, archive,
transferred: restore, or retrieve operation. This value includes data that is sent
more than once due to retries, such as when a file changes during a
backup operation.
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 A sum of sizes of files selected for the operation.
inspected:
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 (UNIX and Linux): Additional considerations

There are some special situations that you need to consider before you back up your data.

Stored files
When you back up and archive files, IBM Spectrum Protect stores the backups and archives in a file space
in storage that has the same name as the file system or virtual mount point from which the files
originated.
For example, if you have a file system named /home, and you back up a file named doc1 in the /home/
monnett directory, IBM Spectrum Protect stores the file in a file space named /home. If you later
define /home/monnett as a virtual mount point, any files you back up from the /home/monnett
directory, such as doc2, are stored in a file space named /home/monnett. If you enter this command:

dsmc query backup "/home/monnett/*"

IBM Spectrum Protect looks for files in the /home/monnett file space. It always looks for a file in the file
space with the longest name that matches the file specification you include in a command. It locates the
file named doc2 that was backed up after the virtual mount point was defined. However, it does not
locate the file named doc1 because that file was backed up before the virtual mount point was defined
and the backup was stored in the /home file space.
To list or restore the doc1 file using a command, you must explicitly specify the file space name by
enclosing it in braces. For example:

dsmc query backup "{/home}/monnett/*"

dsmc restore {/home}/monnett/doc1

If you subsequently remove the /home/monnett virtual mount point, and you then back up additional
files in the /home/monnett directory, the backups are once again stored in the /home file space. For
example, if you now back up a file named doc3 in the /home/monnett directory, it is stored in the /home
file space. It is not stored in the existing /home/monnett file space.

Chapter 4. Backing up your data 205

 However, because the /home/monnett file space already exists, when you try to query or restore the
doc3 file, IBM Spectrum Protect looks for the file in the /home/monnett file space unless you specify
the correct file space name. For example:

dsmc query backup "{/home}/monnett/*"

dsmc restore {/home}/monnett/doc2

Note: You must explicitly specify the file space name only when there can be more than one resolution to
the file specification.
For example, if the following file spaces exist in storage:

/home
/home/monnett
/home/monnett/project1
/home/monnett/project1/planning

then enter:

dsmc query backup "/home/monnett/project1/planning/*"

IBM Spectrum Protect looks for files only in the /home/monnett/project1/planning file space, even
if one or more of the other file spaces contains a path with the same name. But, when you enter one of the
following:

dsmc query backup "{/home}/monnett/project1/planning/*"

dsmc query backup "{/home/monnett}/project1/planning/*"
dsmc query backup "{/home/monnett/project1}/planning/*"

IBM Spectrum Protect looks for files only in the /home file space, the /home/monnett file space, or the /
home/monnett/project1 file space, depending on which form you use.

Special file systems

Special file systems contain dynamic information generated by the operating system; they contain no
data or files. The backup-archive client ignores special file systems and their contents.
Special file systems include the following:
• the /proc file system on most of the UNIX platforms
• the /dev/fd file system on Solaris
• the /dev/pts on Linux

NFS or virtual mount points

When files are backed up and archived from a file system or virtual mount point, the client does not follow
the nested NFS or virtual mount points (if any are defined on a file system). The nested NFS or virtual
mount points will not be backed up or archived.

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 assigned to the file with an include option in the include-
exclude options list. The selected management class must contain a backup copy group in order for the
file to be backed up.
Select Utilities → View Policy Information from the backup-archive client GUI to view the backup
policies defined by the IBM Spectrum Protect server for your client node.
Related concepts
“Storage management policies” on page 265

206 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Storage management policies are rules your administrator defines in order to manage your backups and
archives on the server.

Back up symbolic links

The backup-archive client backs up symbolic links differently than it does regular files and directories.
The way that the client backs up symbolic links depends on options settings, whether the target directory
is accessible, and the way you specify objects.
A UNIX symbolic link is a file that contains a pointer to another file or directory. The object the symbolic
link points to is called the target object.
A symbolic link can be backed up as path information to a target directory, or it can be backed up as a
directory. If the symbolic link is backed up as a directory, the files and folders in the target directory can
also be backed up.
Note: Symbolic link processing as described here does not apply to Mac OS X. Symbolic links are always
backed up as files and are never followed.
Related reference
“Archsymlinkasfile” on page 308
The archsymlinkasfile option specifies whether the backup-archive client follows a symbolic link and
archives the file or directory to which it points, or archives the symbolic link only. Use this option with the
archive command.
“Followsymbolic” on page 391
During a backup operation, the followsymbolic option specifies whether you want to use a symbolic
link as a virtual mount point. During a restore or retrieve operation, the followsymbolic option
specifies how the backup-archive client restores a directory whose name matches a symbolic link on the
restore target file system.
“Virtualmountpoint” on page 539
The virtualmountpoint option defines a virtual mount point for a file system if you want to consider
files for backup that begin with a specific directory within that file system.

Examples: Incremental or selective backup of symbolic links

How the client backs up a symbolic link depends on whether the target of the symbolic link is a file or a
directory, and how you specify the symbolic link on the incremental or selective backup command.
If a symbolic link points to a file, the client only backs up the path information. The client does not back
up a file that is the target of a symbolic link.
If a symbolic link points to a directory, the backup depends on how the directory is specified on the
command.
If a directory is specified with a trailing slash on a selective or incremental backup command, the client
saves the symbolic link as a directory, and backs up the contents of the target directory.
If the symbolic link is entered without a trailing slash, or if a symbolic link is not explicitly stated in a
backup file specification, the client backs up only the path information to the target directory. The
contents of the target directory are not backed up.
In the following examples, assume that symdir is a symbolic link to target directory /fs1/
guest/. /fs1/guest/ contains these objects:
/fs1/guest/file (a file)
/fs1/guest/dir1 (a directory)
/fs1/guest/dir1/file1 (a file)
Example 1
dsmc incr /home/gillis/symdir/
In this example, the client backs up the symbolic link as a directory, and backs up the contents of the
target directory /fs1/guest/. If you specify the subdir=yes option, the client backs up subdirectories
of /fs1/guest/.

Chapter 4. Backing up your data 207

 Example 2
dsmc incr /home/gillis/symdir/dir1
Example 3
dsmc incr /home/gillis/symdir/dir1/
In examples 2 and 3, the client backs up the symbolic link as a directory, and backs up the /dir1/
subdirectory of the target directory. the trailing slash is relevant only for the symbolic link; it is not
relevant for subdirectories of the symbolic link. If you specify the subdir=yes option, the client backs up
subdirectories of /fs1/guest/dir1. Backup copies that are stored on the IBM Spectrum Protect server
have a path like /home/gillis/symdir/dir1/file1.
Example 4
dsmc incr /home/gillis/symdir
In example 4, because there is no trailing slash after the symbolic link, the client backs up only the path
to the target directory. The client does not back up the symbolic link as a directory, and does not back up
files nor folders in the target directory.
Example 5
dsmc incr /home/gillis/
In example 5, because the symbolic link is not explicitly stated in the backup file specification, the client
backs up only the path to the target directory. The client does not back up the symbolic link as a directory,
and does not back up files nor folders in the target directory.
Restriction: If you back up a symbolic link as a directory, a future incremental backup that does not back
up that symbolic link as a directory expires that symbolic link as a directory, and expires the files and
directories in that directory.
For example, assume that you first back up the symbolic link symdir as a directory, and back up the
contents of the target directory. The command in example 1 does this. The client creates backup copies
with a high-level path /home/gillis/symdir/. In this example, the client creates backup copies with
these paths:
/home/gillis/symdir/
/home/gillis/symdir/file
/home/gillis/symdir/dir1
/home/gillis/symdir/dir1/file1
The contents of /home/gillis are backed up using the following command:

dsmc inc /home/gillis/ -subdir=yes

This command processes the value symdir as a symbolic link and does not process any objects that the
symbolic link points to. Hence, the client expires backup copies in the /home/gillis/symdir/
directory that were created in example 1.

Incremental backup of a domain only

The client backs up a symbolic link during an incremental backup of the domain, if the symbolic link is
defined as a virtual mount point and the followsymbolic option is set to yes.
The client backs up a symbolic link and the target directory when all of the following conditions are true:
• The client performs an incremental backup of the domain.
• The symbolic link is defined as a virtual mount point using the virtualmountpoint option.
• followsymbolic=yes
The virtualmountpoint and followsymbolic options add the symbolic link to the domain. The
Incremental command backs up the domain, which includes the symbolic link target.
Related reference
“Followsymbolic” on page 391

208 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 During a backup operation, the followsymbolic option specifies whether you want to use a symbolic
link as a virtual mount point. During a restore or retrieve operation, the followsymbolic option
specifies how the backup-archive client restores a directory whose name matches a symbolic link on the
restore target file system.
“Virtualmountpoint” on page 539
The virtualmountpoint option defines a virtual mount point for a file system if you want to consider
files for backup that begin with a specific directory within that file system.

Hard links
When you back up files that are hard-linked, the backup-archive client backs up each instance of the
linked file.
For example, if you back up two files that are hard-linked, the client backs up the file data twice.
When you restore hard-linked files, the client attempts to reestablish the links. For example, if you had a
hard-linked pair of files, and only one of the hard-linked files is on your workstation, when you restore
both files, they are hard-linked. The files are also hard-linked even if neither of the files exists at the time
of restore, if both of the files are restored together in a single command. The one exception to this
procedure occurs if you back up two files that are hard-linked and then break the connection between
them on your workstation. If you restore the two files from the server using the standard (or classic)
restore process, the client respects the current file system and does not re-establish the hard link.
Important: If you do not back up and restore all files that are hard-linked at the same time, problems
occur. To ensure that hard-linked files remain synchronized, back up all hard links at the same time and
restore those same files together.

Sparse files
Sparse files do not have disk space allocated for every block in the whole address space, leading to holes
within the file. Holes are detected by their content, which is always zeros, and these zeros take up space.
The default is to restore the sparse file without the holes, which would leave more free disk space. The
backup-archive client detects sparse files during a backup operation and marks them as sparse on the
IBM Spectrum Protect server.
Note: Sparse files do not apply to Mac OS X.
The backup-archive client backs up a sparse file as a regular file if client compression is off.
Related reference
“Compression” on page 326
The compression option compresses files before you send them to the server.
“Makesparsefile” on page 429
Use the makesparsefile option with the restore or retrieve commands to specify how sparse files
are recreated.

NFS hard and soft mounts

When the backup-archive client connects to an NFS file system, you can use either a hard mount or a soft
mount.
The client uses the nfstimeout option value to determine how long to wait for an NFS system call to
respond before timing out; this setting applies to hard and soft mounts. The default is 0 seconds. This
means that the client uses the default behavior of NFS system calls.
Be aware of the consequences of hard and soft mounts if the mount becomes stale (for example, if the
server for the file system is not available).
Hard mount
If the NFS file system is hard mounted, the NFS daemons try repeatedly to contact the server. The
NFS daemon retries will not time out, they affect system performance, and you cannot interrupt them,
but control returns to the client when the nfstimeout value is reached.

Chapter 4. Backing up your data 209

 Soft mount
If the NFS file system is soft mounted, NFS tries repeatedly to contact the server until either:
• A connection is established
• The NFS retry threshold is met
• The nfstimeout value is reached
When one of these events occurs, control returns to the calling program.
Note: On UNIX and Linux systems, the nfstimeout option can fail if the NFS mount is hard. If a hang
occurs, deactivate the nfstimeout option and mount the NFS file system soft mounted, as follows:

mount -o soft,timeo=5,retry=5 machine:/filesystem /mountpoint

The parameters are defined as follows:

soft
Generates a soft mount of the NFS file system. If an error occurs, the stat() function returns
with an error. If the option hard is used, stat() does not return until the file system is available.
timeo=n
Sets the timeout period for a soft mount error to n tenths of a second.
retry=n
Sets the number of times to try the mount, where n is an integer; the default is 10000.

Deleted file systems

When a file system or drive has been deleted, or it is no longer backed up by the backup-archive 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.
If you do not need to keep any of the backup versions, use the delete backup command to delete all
backup versions in the file space. Your IBM Spectrum Protect server administrator must give you the
authority to use this command. Use the query session command to determine whether you have
"delete backup" authority. Alternatively, you can ask your IBM Spectrum Protect server administrator to
delete the file space for you.
Related concepts
“Storage management policies” on page 265
Storage management policies are rules your administrator defines in order to manage your backups and
archives on the server.

Opened files
The backup-archive client looks for files that have changed between the start and the completion of the
backup of the file.
Some files on your system might be in use, or open, when you try to back them up. Because an open file
can change, a backup action might not reflect the correct contents of the file at a given time.
Consider whether the file is important, and whether you can build the file again. If the file is not
important, you might not want to back it up. Or, if the file is important, a root user on your workstation can
ensure the file is closed before backup.
If your backups run on a schedule, a root user can use the preschedulecmd option to enter a command
to close the file. For example, if the open file is a database, use the quiesce command of the database to
shut down the database. A root user 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, ensure that you
close the application that uses the file before you start the backup.

210 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 The client can back up the file even if it is open and gets changed during the backup. This is only useful if
the file is usable even if it changes during backup. To back up these files, assign the files a management
class with the serialization dynamic or shared dynamic.
Related concepts
“Display information about management classes and copy groups” on page 267
You can display policy information with the command-line interface or with a graphical user interface.
“Select a management class for files” on page 270
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.

Wildcard characters
You can use the operating system wildcard characters in file specifications with the backup-archive client.
These characters let you select groups of files that have similar names.
In a command, wildcard characters can only be used in the file name or extension. They cannot be used
to specify destination files, file systems, or directories. When using wildcard characters in non-loop mode,
as in dsmc sel "/home/ledger.*", enclose the parameter containing the asterisk in quotation marks
to ensure the system does not interpret the wildcard character and produce unexpected results. Wildcard
character information is covered in the following table.
Important: Use an asterisk (*) instead of a question mark (?) as a wildcard character when trying to
match a pattern on a multibyte code page, to avoid unexpected results.
This table shows some wildcard patterns and how to specify them.

* (Asterisk) Zero or more characters that match all files:

*.cpp With a cpp extension
hm*.* Starting with hm, regardless of extension, but must have the '.' character
hm* Starting with hm, whether an extension exists or not
*h*.* With an h somewhere in the file name, regardless of extension, but must
have .

? (Question mark) One character that matches all files with:

?.cpp The extension cpp with one, and only one, character in the file name
hm?.cpp Three-character names beginning with hm and that have the cpp extension

* ? (Asterisk and Asterisk and question mark combinations matching:

question mark)
??hm.* All four-character file names ending in hm., no matter what extension they
have

In a path name for a file specification, you cannot specify a directory whose name contains an asterisk (*)
or a question mark (?). The client recognizes those characters only as wildcard characters.

Chapter 4. Backing up your data 211

212 IBM Spectrum Protect UNIX and Linux 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.
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.
Attention: Do not restore operating system files, like base system directories, kernel modules, or
patches, to their original location while the file system is running. The operating system might
hang or crash.
The following are the primary restore tasks:
• “Restoring an image” on page 213
• “Restoring data using the GUI” on page 231
• “Command line restore examples” on page 232
• “Restore data from a backup set” on page 216
• “Restoring data to a point in time” on page 224
• “Restore NAS file systems” on page 229
• “Authorizing another user to restore or retrieve your files” on page 236
• “Restoring or retrieving files from another client node” on page 237
• “Restore or retrieve files to another workstation” on page 238
• “Restoring a disk in case of disk loss” on page 238
• “Deleting file spaces” on page 239
Refer to IBM Spectrum Protect for Space Management for UNIX and Linux for details about restoring
migrated files and the restoremigstate option.
Related tasks
“Starting a web client session” on page 136
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.

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:
• 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.
• Ensure that the volume to which you are restoring the image is at least as large as the image that is
being restored.

© Copyright IBM Corp. 1993, 2019 213

 • On Linux systems, some file systems such as ext2, ext3, ext4, btrfs, and xfs use a universally unique
identifier (UUID) to identify themselves to the operating system. If you create an image backup of such
a volume and you restore it to a different location, you might have two volumes with the same UUID. If
you use UUID to define your file systems in /etc/fstab, be aware that the backup-archive client might
be unable to correctly mount the restored file system because the UUIDs conflict. To avoid this
situation, restore the image to its original location. If you must restore it to a different location, change
the UUID of either the original or restored volume before you mount the restored file system. Refer to
the Linux documentation for instructions on how to change a UUID. You might also need to manually
edit the /etc/fstab file so the original volume, the restored volume, or both volumes can be mounted.
• The file system or volume you are restoring to must be the same type as the original.
• 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.
• You cannot restore an image to where the IBM Spectrum Protect client program is installed.
• 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.
• If for some reason a restored image is corrupted, you can use the fsck tool to attempt to repair the
image.
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, the client 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 401
Use the imagetofile option with the restore image command to specify that you want to restore the
source image to a file.
“Verifyimage” on page 539
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.

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.

214 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 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:
• 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. The stored image on the IBM
Spectrum Protect server is the same size as the volume capacity.
– File system type
– Backup date and time
– Management class assigned to image backup
– Whether the image backup is an active or inactive copy
• To modify specific restore options, click the Options button. Any options you change are effective
during the current session only.
• 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.
Related reference
“Imagetofile” on page 401
Use the imagetofile option with the restore image command to specify that you want to restore the
source image to a file.
“Verifyimage” on page 539

Chapter 5. Restoring your data 215

 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.

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:
• From the IBM Spectrum Protect server
• From portable media on a device attached to your client workstation
• 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.
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:
• 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.
• 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.
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:
• 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.
• 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.
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

216 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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.

Table 43. Backup set GUI restore restrictions

Backup set location
Local IBM Spectrum
(location=file Protect Server
Data type in the or IBM Spectrum Protect Server (TOC (TOC not
backup set location=tape) available) available)
file Restore entire Restore entire backup set, or selected Restore entire
backup set only. objects in the backup set. backup set only.
image Cannot be Restore entire backup set, or selected Cannot be
restored. objects in the backup set. restored.
system state Restore entire Restore entire backup set, or selected Restore entire
backup set only. objects in the backup set. 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 44. Backup set command-line restore restrictions

Backup set location
Data type in
the backup Local (location=file or IBM Spectrum Protect IBM Spectrum Protect
set location=tape) Server (TOC available) Server (TOC not available)
file Commands: Commands: Commands:

restore restore restore backupset

restore backupset restore backupset

image Cannot be restored Command: Cannot be restored

restore image

system state Command: Commands: Command:

restore backupset restore backupset restore backupset

restore systemstate

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 428
The localbackupset option specifies whether the backup-archive client GUI bypasses initial logon with
the IBM Spectrum Protect server to restore a local backup set on a standalone workstation.
“Query Backupset” on page 643
The query backupset command queries a backup set from a local file, tape device (if applicable), or
the IBM Spectrum Protect server.
“Query Image” on page 650

Chapter 5. Restoring your data 217

 The query image command displays information about file system images that are stored on the IBM
Spectrum Protect server, or that are inside a backup set from the IBM Spectrum Protect server, when the
backupsetname option is specified.
“Restore” on page 664
The restore command obtains copies of backup versions of your files from the IBM Spectrum Protect
server, or inside a backup set.
“Restore Backupset” on page 668
The restore backupset command restores a backup set from the IBM Spectrum Protect server, a
local file, or a local tape device. You can restore the entire backup set, or, in some cases, specific files
within the backup set.
“Restore Image” on page 677
The restore image command restores a file system or raw volume image that was backed up using the
backup image command.

Restore backup sets: considerations and restrictions

This topic lists some considerations and restrictions that you must be aware of when restoring backup
sets.

Backup set restore considerations

Consider the following when restoring backup sets:
• 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.
• 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.
• 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.
• 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.
• 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.
• If a backup set contains files from several owners, the backup set itself is owned by the root user ID,
and non-root user IDs cannot see the backup set. In this case, non-root user IDs can restore their files
by obtaining the backup set name from the IBM Spectrum Protect administrator. Non-root users can
restore only their own files.
• 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:
• A backup set data that was backed up with the API cannot be restored or used.

218 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • 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.
• 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 428
The localbackupset option specifies whether the backup-archive client GUI bypasses initial logon with
the IBM Spectrum Protect server to restore a local backup set on a standalone workstation.
“Restore” on page 664
The restore command obtains copies of backup versions of your files from the IBM Spectrum Protect
server, or inside a backup set.
“Restore Image” on page 677
The restore image command restores a file system or raw volume image that was backed up using the
backup image command.
“Restore Backupset” on page 668
The restore backupset command restores a backup set from the IBM Spectrum Protect server, a
local file, or a local tape device. You can restore the entire backup set, or, in some cases, specific files
within the backup set.

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.
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.
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.

Chapter 5. Restoring your data 219

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.
• 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.
• 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:
• 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.
• 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.
• 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.
• The following features of a backup set restore from the server are not available when restoring locally:
1. Image restore.
2. 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.

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:

220 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • restore
• restore backupset
• restore image
Use the appropriate command for the location of the backup set and the data in the backup set. For more
information, see Table 44 on page 217.
Related reference
“Query Backupset” on page 643
The query backupset command queries a backup set from a local file, tape device (if applicable), or
the IBM Spectrum Protect server.
“Query Image” on page 650
The query image command displays information about file system images that are stored on the IBM
Spectrum Protect server, or that are inside a backup set from the IBM Spectrum Protect server, when the
backupsetname option is specified.
“Restore” on page 664
The restore command obtains copies of backup versions of your files from the IBM Spectrum Protect
server, or inside a backup set.
“Restore Backupset” on page 668
The restore backupset command restores a backup set from the IBM Spectrum Protect server, a
local file, or a local tape device. You can restore the entire backup set, or, in some cases, specific files
within the backup set.
“Restore Image” on page 677
The restore image command restores a file system or raw volume image that was backed up using the
backup image command.

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:
• Ensure that the client is configured for automated client failover.
• 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 88.
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.

Chapter 5. Restoring your data 221

 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 /build.sh

The following output is displayed:

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
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
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.

Restore an image to file

When you back up an image, the backup-archive client backs up the first sector of the volume, but when
the data is restored, it skips the first sector to preserve the original logical volume control block of the
destination volume.
When you restore an image to file, entire volume contents, including the first sector, are restored to the
file.

222 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 AIX LVM volumes from original volume groups contain the Logical Volume Control Block (LVCB) on the
first sector (512 bytes) of the volume. The LVCB contains volume specific meta-data that should be
preserved by applications using the volume.
When you copy the file, containing the image, onto an LVM volume from the original volume group, you
need to skip the LVCB from both the file and destination volume. The following dd command can be used
for this purpose.

dd if=<filename> of=/dev/<vol> bs=512 skip=1 seek=1

The dd command sets the block size to 512 bytes, which makes copying very slow. It is better to use
bs=1m or similar. Here is an alternative way to copy image data:
1. Save the original first sector to a file:

dd if=/dev/<vol> of=firstblk.tmp bs=512 count=1

2. Copy the restored image:

dd if=<filename> of=/dev/<vol> bs=1m

3. Restore the original first sector:

dd if=firstblk.tmp of=/dev/<vol> bs=512 count=1

With the introduction of big and scalable volume group formats on AIX, it is possible that the first sector
of the logical volume cannot contain LVCB and is available for the data. If you use big or scalable volume
groups on your system, and need to restore the whole volume including the first sector, restore the
volume to file and then copy it to a destination volume. The following dd command can be used for this
purpose.

dd if=<filename> of=/dev/<vol> bs=1m

Related concepts
“Restoring an image using the command line” on page 215
Use the restore image command to restore an image using the IBM Spectrum Protect command line
client.
Related tasks
“Restoring an image using the GUI” on page 214
You can use the GUI to restore an image of your file system or raw logical volume.

Manage GPFS file system data with storage pools

With Global Parallel File Systems (GPFS) technology, you can manage your data using storage pools. A
storage pool is a collection of disks or RAIDs with similar properties that are managed together as a
group.
The group under which the storage pools are managed together is the file system. The automated
placement and management of files on the storage pool level is done by policies. A policy is a set of rules
that describes the life cycle of user data, based on the attributes of the file.
When a file is created, the placement policy determines the initial location of the data of the file and
assigns the file to a storage pool. All data written to that file is placed in the assigned storage pool. The
management policy determines file management operation, such as migration and deletion. The files
within a GPFS file system are distributed over different storage pools, depending on the enabled
placement and migration policies.
During restore, the files are placed on the correct storage pool. The IBM Spectrum Protect server is not
aware of pool-to-pool migrations, so the files are placed on the storage pool from where the backup has
taken place. The policy engine replaces the files based on migration policies.

Chapter 5. Restoring your data 223

 If a storage pool ID is stored in the extended attributes of the file, and that storage pool is available, the
file is always placed in that storage pool. If the storage pool is not available, the file is placed according to
the placement policy. If the placement policy does not match the file, the file is placed in the system pool.
GPFS handles the placement of files after a restore as follows:
• The file is placed in the pool that can be selected by matching the saved file attributes to a RESTORE
rule
• The file is placed in the pool that it was in when it was backed up
• The file is placed based on the current placement policy
• The file is placed in the system storage pool
The GPFS RESTORE rule allows you to match files against their saved attributes rather than the current
file attributes. If the file attributes do not match, GPFS tries to restore the file in the sequence described
above.
For more information about the GPFS RESTORE rule, read the GPFS documentation about policies and
rules.
The following restrictions apply:
• The restore of stub files does not work with multiple storage pools, or with files that have ACLs
• Unlink of filesets are not allowed
• The ctime option of GPFS should be set to no (default), to prevent unwanted Backup-Archive backups
of files after GPFS file migration from pool to pool
For information about using storage pools, see the IBM Spectrum Protect server documentation.
Related reference
Data storage in storage pools
Related information
IBM Spectrum Scale product information
mmbackup command: IBM Spectrum Protect requirements
Considerations for using IBM Spectrum Protect include and exclude options with IBM Spectrum Scale
mmbackup command

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 a file space, directory, or 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:

224 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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:
• 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.
• 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.
• 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.
• 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
“Storage management policies” on page 265
Storage management policies are rules your administrator defines in order to manage your backups and
archives on the server.
Related reference
“Backup Image” on page 602

Chapter 5. Restoring your data 225

 The backup image command creates an image backup of one or more volumes on your system.

Restoring data from a retention set

You can restore data from retention sets by using a point-in-time restore operation. With this operation,
you restore data that was active on the server at the time when the retention set was created on the
backup-archive client or the IBM Spectrum Protect for Virtual Environments client.

Before you begin

Before you restore data from a retention set, ensure that the server to which you want to restore the files
is online.
Restriction: You can restore only one set of the files for a specific node even though the same files might
be stored in more than one retention set at a specific point in time.

About this task

You can run a point-in-time restore operation from the backup-archive client command line or by using
the client GUI.
To start a point-in-time restore operation by using the client GUI, follow the instructions in “Restoring
data to a point in time” on page 224.

Procedure
To restore data from a retention set by using the command-line client, complete the following steps:
1. Determine the point in time from which to restore data. On the server command line, issue the QUERY
RETSET command. For example, if the retention set ID is 42, issue the following command:

query retset 42

Retention Set ID: 42

Retention Rule Name: XMP1
Point-In-Time Date: 01/07/2019 05:00:00 PM
Retention Period: 60
Expiration Date: 03/08/2019 05:00:00 PM
Retention Set State: Active
Total File Sizes (MB): 180
Last Update by (administrator): SERVER_CONSOLE
Last Update Date/Time: 01/07/2019 05:00:12 PM
Description: Example 1: weekly retention rule runs on Monday
at 5:00pm
Retention Set Contents: GRASSHOPPER:/home GRASSHOPPER:/home/hannigan/b-
uild CRICKET:/home/hannigan/build FLEA:\\flea-
\c$

2. To list the contents of the retention set, on the backup-archive client command line, issue the query
backup command. Specify the pitdate and pittime options with the date and time of the retention
set's snapshot. For example:

query backup {/home/hannigan/build}/* -su=y -pitdate=01/07/2019 -pittime=17:00:00

3. Restore the contents of the retention set. On the client command line, issue the restore command.
Specify the pitdate and pittime options with the date and time of the retention set's snapshot. For
example:

restore {/home/hannigan/build}/* -su=y -pitdate=01/07/2019 -pittime=17:00:00

226 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Results
The data is restored to the server.
Related tasks
“Restoring data to a point in time” on page 224
Use a point-in-time restore to restore files to the state that existed at a specific date and time.
Related reference
“Query Backup” on page 640
The query backup command displays a list of backup versions of your files that are stored on the IBM
Spectrum Protect server, or that are inside a backup set from the server when the backupsetname
option is specified.
“Restore” on page 664
The restore command obtains copies of backup versions of your files from the IBM Spectrum Protect
server, or inside a backup set.
Related information
Configuring rules for long-term data retention

Restore AIX encrypted files

When files are backed up in raw format from an AIX JFS2 Encrypted File System (EFS), you can only
restore them to the same or another JFS2 EFS. They cannot be restored to any different file system, or on
a different platform.
When EFS files are backed up in clear text, then you can restore them anywhere. If you restore them to a
JFS2 EFS, they are automatically re-encrypted only if the directory to which they are restored has the AIX
"EFS inheritance" option set.
After restoring a file that was backed up in raw format, you might find that the file cannot be decrypted.
The encryption key originally used for the file might no longer be available in the keystore of the user. In
this case, you must restore the keystore used at the time of backup.
For information on backing up EFS data, refer to “AIX JFS2 encrypted file system backup” on page 196.

Restore AIX workload partition file systems

All the files that are created by the local workload partition (WPAR), and backed up by the backup-archive
client that is installed at the global WPAR, can be restored by the client installed at the global WPAR.
Here are some global partition and WPAR configuration examples:

Global partition:

system name: shimla

file system: /home /opt

WPAR #1 configuration:

name: wpar1

file system: /home; name in global WPAR: /wpars/wpar1/home

WPAR #2 configuration:

name: wpar2

file system: /data; name in global WPAR: /wpars/wpar2/data

There are two ways to restore WPAR data, depending on the method used to back up the WPAR data files:

Chapter 5. Restoring your data 227

 • Restore all WPAR file systems as the file spaces within the global partition. The file space name must be
used to identify the WPAR to which it belongs. All of the data is managed on one node using one
schedule. Using the example configuration mentioned previously, here is a sample dsm.sys file with
one server stanza for all file systems, both global and local:

SErvername shimla

TCPPort 1500

TCPServeraddress server.example.com

nodename shimla

PasswordAccess generate

Domain /wpars/wpar1/home /wpars/wpar2/data /home /opt

Use the following command to restore each file space:

dsmc restore /wpars/wpar1/home/*

dsmc restore /wpars/wpar2/data/*
dsmc restore /home/*
dsmc restore /opt/

• Restore each WPAR file system from a different node name, if it is backed up under a different node
name. Each WPAR must have a separate node name and a scheduler running within the global partition.
Also, three scheduler services must be set up, each using a different dsm.opt file corresponding to the
server stanza name. This method allows each WPAR restore operation to be managed independent of
the others. Using the example configuration mentioned previously, here is a sample dsm.sys file with
three server stanzas: one for wpar1, one for wpar2, and one for global partition shimla:

SErvername shimla_wpar1
TCPPort 1500
TCPServeraddress server.example.com
nodename wpar1
PasswordAccess generate
Domain /wpars/wpar1/home

SErvername shimla_wpar2
TCPPort 1500
TCPServeraddress server.example.com
nodename wpar2
PasswordAccess generate
Domain /wpars/wpar2/data

SErvername shimla
TCPPort 1500
TCPServeraddress server.example.com
nodename shimla
PasswordAccess generate
Domain /home /opt

Table 45. Sample WPAR restore commands with dsm.opt file

In dsm.opt file Sample restore command
servername shimla_wpar1 dsmc restore /wpars/wpar1/home/*
servername shimla_wpar2 dsmc restore /wpars/wpar2/data/*
servername shimla dsmc restore /home/*
dsmc restore /opt/*

228 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Restore NAS file systems
You restore NAS file system images using the backup-archive client GUI or command line interface.
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
“Processing NAS file systems” on page 409
Use the include.fs.nas option to bind a management class to NAS file systems and to control whether
Table of Contents information is saved for the file system backup.

Restoring NAS file systems using the backup-archive client GUI

You can use the backup-archive client GUI to restore NAS file systems.

Before you begin

The backup-archive client GUI must be connected to the IBM Spectrum Protect Version 8.1.2 or later
server, or V7.1.8 or later V7 server.

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
backup-archive client GUI 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:
• 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).

Chapter 5. Restoring your data 229

 • 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.
• To delete NAS file spaces, select Utilities > Delete Filespaces. You can delete both workstation and
remote objects.

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 46. NAS options and commands

Option or command Definition Page
query node Displays all the nodes for which a particular “Query Node” on page
administrative user ID has authority to perform 654
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.

query backup Use the query backup command with the class “Query Backup” on page
option to display information about file system 640
images backed up for a NAS file server.
query filespace Use the query filespace command with the “Query Filespace” on
class option to display a list of file spaces page 646
belonging to a NAS node.
restore nas Restores the image of a file system belonging to a “Restore NAS” on page
Network Attached Storage (NAS) file server. 679
monitor process Displays current backup and restore processes for “Monitor Process” on
all NAS nodes for which an administrative user has page 635
authority. The administrative user can then select
one process to monitor.
cancel process Displays current backup and restore processes for “Cancel Process” on
all NAS nodes for which an administrative user has page 615
authority. From the display, the administrative user
can select one process to cancel.
delete filespace Use the delete filespace with the class “Delete Filespace” on
option to display a list of file spaces belonging to a page 622
NAS node so that you can choose one to delete.

Regardless of client platform, NAS file system specifications use the forward slash (/) separator, as in this
example: /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.

230 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Restore active or inactive backups
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 → Display active files only item. If you try to restore more than one version at a
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 401
Use the inactive option to display both active and inactive objects.

Restoring data using the GUI

This section lists the steps to follow to restore backup versions of individual files or subdirectories.

Procedure
1. Click Restore from the main window. The Restore window appears.
2. Expand the directory tree. Select the selection boxes next to the files or directories you want to
restore. To search or filter files, click the Find icon on the tool bar.
3. Enter your search criteria in the Find Files (Restore) window.
4. Click the Search button. The Matching Files (Restore) window appears.
5. Click the selection boxes next to the files you want to restore and close the Matching Files (Restore)
window.
6. Enter your filter criteria in the Find Files (Restore) window.
7. Click the Filter button. The Restore window displays the filtered files.
8. Click the selection boxes next to the filtered files or directories you want to restore.
9. To modify specific restore options, click the Options button. Any options you change are effective
during the current session only.
10. Click Restore. The Restore Destination window appears. Enter the information in the Restore
Destination window.
11. Click Restore. The Restore Task List window displays the restore processing status.

Results
Note: On Mac OS X, consider the following items when restoring data using the GUI:
1. When IBM Spectrum Protect Tools for Administrators is used to start the client, the client is running
with a UID of zero. This means that if you create a folder to restore your files to, that folder is owned by
root. To access the files you must change the permissions of the folder. You can change the folder
owner from a terminal window using the sudo chown command. See your operating system
documentation for more information on how to accomplish this.

Chapter 5. Restoring your data 231

 2. When restoring files with the replace option set to no, existing files will not be overwritten, but
existing directories are overwritten. To leave existing directories intact during a restore operation,
select the Options button ⇒ All selected files and directories dropdown menu ⇒ Files only option.
3. When folders are restored from a UFS or HFSX file system to a HFS file system and they differ only in
case, the client restores the contents of both folders to one folder.

Command line restore examples

This topic lists some examples of restore commands to use for specific tasks.
The following table shows examples of how to use the restore command to restore objects from IBM
Spectrum Protect server storage.

Table 47. Command-line restore examples

Task Command Considerations
Restore the most recent backup dsmc restore /Users/ If the file you are restoring no
version of the /Users/monnett/ monnett/Documents/h1.doc - longer resides on your workstation,
Documents/h1.doc file, even if latest and you have run an incremental
the backup is inactive. 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 427
for more information.
Display a list of active and inactive dsmc restore "/Users/ If you try to restore both an active
backup versions of files from which monnett/Documents/*"-pick - and inactive version of a file at the
you can select versions to restore. inactive same time, only the active version is
restored. See “Pick” on page 451
and “Inactive” on page 401 for
more information.
Restore the /Users/monnett/ dsmc restore /Users/ If you do not specify a destination,
Documents/h1.doc file to its monnett/Documents/h1.doc the files are restored to their
original directory. original location.
Restore the /Users/monnett/ dsmc restore /Users/ None
Documents/h1.doc file under a monnett/Documents/h1.doc /
new name and directory. Users/gordon/Documents/
h2.doc
Restore the files in the /Users dsmc restore /Users/ - When restoring a specific path and
directory and all of its subdir=yes file, IBM Spectrum Protect
subdirectories. recursively restores all
subdirectories under that path, and
any instances of the specified file
that exist under any of those
subdirectories. See “Subdir” on
page 515 for more information
about the subdir option.
Restore all files in the /Users/ dsmc restore - See “Pitdate” on page 452 and
gordon/Documents directory to pitd=8/17/2003 - “Pittime” on page 453 for more
their state as of 1:00 PM on August pitt=13:00:00 /Users/ information about the pitdate and
17, 2003. gordon/Documents/ pittime options.

232 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 47. Command-line restore examples (continued)
Task Command Considerations
Restore all files from the /Users/ dsmc restore "/Users/mike/ If the destination is a directory,
mike/Documents directory that Documents/*.bak" /Users/ specify the delimiter (/) as the last
end with .bak to the /Users/ mike/projectn/ character of the destination. If you
mike/projectn/ directory. omit the delimiter and your
specified source is a directory or a
file spec with a wildcard, you
receive an error. If the projectn
directory does not exist, it is
created.
Restore files specified in the dsmc restore -filelist=/ See “Filelist” on page 387 for more
restorelist.txt file to a Users/user2/Documents/ information about restoring a list of
different location. restorelist.txt /Users/ files.
NewRestoreLocation/

Related reference
“Restore” on page 664
The restore command obtains copies of backup versions of your files from the IBM Spectrum Protect
server, or inside a backup set.

Examples: Command line restores for large amounts of data

If you need to restore a large number of files, you can get faster performance by using the restore
command instead of the GUI. In addition, you can improve performance by entering multiple restore
commands at one time.
For example, to restore all the files in your /home file system, enter:

dsmc restore /home/ -subdir=yes -replace=all -tapeprompt=no

However, if you enter multiple commands for the directories in the /home file space, you can restore the
files faster.
For example, you could enter these commands:

dsmc restore /home/monnett/ -subdir=yes -replace=all -tapeprompt=no

dsmc restore /home/gillis/ -subdir=yes -replace=all -tapeprompt=no
dsmc restore /home/stewart/ -subdir=yes -replace=all -tapeprompt=no

You can also use the quiet option with the restore commands 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 user-options file, you do not need to include those 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. Be sure you do not use any overlapping file specifications in the commands.
To display a list of the directories in a file space, use the query backup command. For example:

dsmc query backup -dirsonly -subdir=no /Users/

As a general rule, you can enter from 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 how much memory
you have and network utilization.
The speed at which you can restore the files also depends on how many tape drives are available on the
server, and whether your administrator is using collocation to keep file spaces assigned to as few volumes
as possible.

Chapter 5. Restoring your data 233

 For example, if /Users/user1 and /Users/user2 are on the same tape, the restore for /Users/
user2 must wait until the restore for /Users/user1 is complete. However, if /Users/user3 is on a
different tape, and there are at least two tape drives available, the restore for /Users/user3 can begin
at the same time as the restore for /Users/user1.
Set the system ulimit values to unlimited (-1) if you are restoring very large (2 GB) files with HSM or the
backup-archive client. The client can restore these large files with enough system resources. If the ulimits
are set to lower values, there might be restore failures.

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:
• The client queries the server for a list of files backed up for the client file space you want to restore.
• 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.
• 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.
• The client tells the server to restore file data and directory objects.
• 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, todate, the client uses a no-query
restore method for restoring files and 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 IBM Spectrum Protect GUI client, an example of an unrestricted wildcard command would be to
select a folder from the restore tree window. An example of a restricted wildcard command would be to
select individual files from a folder.
Using the command-line client, an example of an unrestricted wildcard command would be:

"/Users/user1/Documents/2004/*"

/home/mydocs/2004/*

234 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 An example of a restricted wildcard file specification would be:

/Users/user1/Documents/2004/sales.*

/home/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.
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 perform restartable restores using the GUI, follow these steps:
1. Select Actions –> Restartable restores from the main panel.
2. Select the restartable restore session you want to complete.
3. Click the Restart button at the bottom of the panel.
Related reference
“Resourceutilization” on page 475
Use the resourceutilization option in your option file to regulate the level of resources the IBM
Spectrum Protect server and client can use during processing.
“Restore” on page 664
The restore command obtains copies of backup versions of your files from the IBM Spectrum Protect
server, or inside a backup set.

Restoring Solaris Zettabyte (ZFS) file systems

Zettabyte File Systems (ZFS) use storage pools to manage physical storage.
How you restore a ZFS file system depends on how it was backed up.
• If you backed up all files and folders as separate objects, you can restore them by performing a file-
level restore. For example:

dsmc restore /tank/myZFS/ -subdir=yes -replace=all

Do not perform a file-level restore operation in a disaster recovery scenario. Even though you
successfully restore all system files and folders from a backup-archive client-created backup, the
restored system might be unstable or fail.
• If you backed up an entire ZFS snapshot as a single file, you need to restore the snapshot file from the
server into a temporary location. For example:

dsmc restore /tmpdir/mySnapshotfile

Chapter 5. Restoring your data 235

 You can then restore the file system from the snapshot file by using the Oracle Solaris ZFS commands.
For example:

zfs receive tank/myZFS@mySnapshot < /tmpdir/mySnapshotFile

The advantage of restoring ZFS from a snapshot file is that the full file system can be restored, in a
disaster recovery scenario.
For detailed information about restoring data on ZFS file systems, see the product documentation that
is available from Oracle. If you are restoring a ZFS root pool, see the topics that describe how to re-
create your root pool and recover root pool snapshots.
Related tasks
“Backing up Solaris Zettabyte file systems” on page 195
On Solaris SPARC and Solaris x86 systems, you can backup Zettabyte file systems (ZFS), by using ZFS
snapshots. The advantage of this approach, over an ordinary incremental or selective backup, is that the
files and folders in a snapshot are always in a read-only state, so they cannot be changed during a
backup.

Additional restore tasks

This section discusses some advanced considerations for restoring data.

Authorizing another user to restore or retrieve your files

You can authorize another user on the same workstation or a different workstation to restore backup
versions or retrieve archive copies of your files.

About this task

This permits you to share files with other people or with other workstations that you use with a different
node name. To authorize a user on another workstation to restore or retrieve your files, the other
workstation must be running one of the UNIX clients and must be registered with your server.
Note: Mac OS X can only restore Mac OS X nodes.
To authorize another user to restore or retrieve your files:

Procedure
1. Click Utilities → Node Access List from the main window. The Node Access List window appears.
2. Click the Add button. The Add Access Rule window appears.
3. In the Add Access Rule window, select an item in the Permit Access to field to specify the type of
data that the other user can access. You can select either Backed up Objects or Archived Objects.
4. In the Grant Access to Node field, type the node name of the host workstation of the user that can
access your data.
5. In the User field, type the name of the user on a node who can access your data.
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 which 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. For the Java GUI: 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 the OK button to save the access rule and close the Add Access Rule window.

236 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 the OK button. If you do not want
to save your changes, click Cancel or close the window.

Results
In the client command line interface, 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 616
The delete access command deletes authorization rules for files that are stored on the server.
“Query Access” on page 637
The query access command shows who was given access to backup versions or archive copies of
specific files.
“Set Access” on page 701
The set access command gives users at other nodes access to your backup versions or archived
copies.

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.

About this task

You can display file spaces of another user on the server, restore the backup versions of another user, or
retrieve the archive copies of another user to your local file system:

Procedure
1. Click Utilities from the main window.
2. Click Access Another Node. The Access Another Node window appears.
3. Type the node name of the host workstation of the user in the Node name field. Type the user name in
the User name field.
4. Click the Set button.

Results
If you are using commands, use the fromnode and fromowner options to indicate the node name and
the name of the user who owns the files.
For example, to restore files to one of your own file systems that were backed up from a workstation
named Node1 and owned by a user named Ann, enter:

dsmc restore -fromn=node1 -fromo=ann "/home/proj/*" /home/gillis/

Use the query filespace command to get a list of file spaces. For example, to get a list of file spaces
owned by Ann on Node1, enter:

dsmc query filespace -fromn=node1 -fromo=ann

Related reference
“Fromnode” on page 394
The fromnode option permits one node to perform commands for another node. A user on another node
must use the set access command to permit you to query, restore, or retrieve files for the other node.
“Query Filespace” on page 646

Chapter 5. Restoring your data 237

 The query filespace command displays a list of file spaces for a node. The file spaces are stored on
the IBM Spectrum Protect server, or inside a backup set from the server when the backupsetname
option is specified. You can also specify a single file space name to query.
“Restore” on page 664
The restore command obtains copies of backup versions of your files from the IBM Spectrum Protect
server, or inside a backup set.
“Retrieve” on page 693
The retrieve command obtains copies of archived files from the IBM Spectrum Protect server. You can
retrieve specific files or entire directories.

Restore or retrieve files to another workstation

From a different workstation, you can restore or retrieve files you have already backed up from your own
workstation. You must know the IBM Spectrum Protect password assigned to your node.
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. The virtualnodename option cannot be
set to the hostname of the workstation. You can use the virtualnodename option when you start IBM
Spectrum Protect or you can add the virtualnodename option to your client user options file dsm.opt.
Use the virtualnodename option on the dsmj command if you are borrowing the workstation of another
user and you do not want to update their client user-options file.
IBM Spectrum Protect prompts you for the password for your original node. After you enter the correct
password, all file systems from your original workstation appear in the Restore or Retrieve window. You
can restore or retrieve files as if you were working on your own workstation.
Important: When you use this method to access files, you have access to all files backed up and archived
from your workstation. You are considered a virtual root user.
You can use the virtualnodename option in a command. For example, to restore your projx files, enter:

dsmc restore -virtualnodename=nodeone "/home/monnett/projx/*"

If you do not want to restore or retrieve the files to the same directory name on the alternate workstation,
enter a different destination.
The considerations for retrieving files are the same as restoring files.

Restoring a disk in case of disk loss

You can only recover your files if you can run the client. If the disk that contains the client is lost (from
theft or hardware failure, for example), you must reinstall the client before you can recover your files. If
you also lose the disk that contains the operating system and communication software, you must recover
them before you can connect to the IBM Spectrum Protect server.

About this task

To protect yourself against these kinds of losses, you need to put together a set of installation media that
you can use to restore your system to a state that lets you contact the server and begin recovering data.
The installation media should contain:

Procedure
1. A startable operating system that lets you perform basic functions.
2. A correctly configured communication program that lets you establish communications with the
server.
3. A client with appropriate customized options files. You can use the client command line interface to
complete this task.

238 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Results
The communication package you use determines what files you need. Consult your operating system and
communication software manuals to set up your installation media.
If you also have the IBM Spectrum Protect for Space Management installed on your workstation, your
installation media should include the HSM command line client.
Note: Your administrator can schedule restore operations, which can be very useful when you need to
restore a large number of files.
Related concepts
Backup and restore on space managed file systems

Deleting file spaces

If your IBM Spectrum Protect administrator gives you authority, you can delete entire file spaces from the
server.

About this task

When you delete a file space, you delete all the files and images, both backup versions and archive
copies, that are contained within the file space. For example, if you delete the file space for your /home/
monnet file system, you are deleting every backup for every file in that file system and every file you
archived from that file system. Carefully consider whether you want to delete a file space. You must be
an authorized user to perform this task.
You can delete individual backup versions by using the delete backup command.
You can delete file spaces using the backup-archive client GUI or client command line interface. To delete
NAS file spaces, use the web client or client command line interface.
To delete a file space using the GUI, perform the following steps:

Procedure
1. Select Utilities→ Delete Filespaces from the main window.
2. Click the selection boxes next to the file spaces you want to delete.
3. Click the Delete button. 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 321
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.
“Delete Backup” on page 618
The delete backup command deletes files, images, and virtual machines that were backed up to IBM
Spectrum Protect server storage. Your administrator must give you authority to delete objects.
“Delete Filespace” on page 622

Chapter 5. Restoring your data 239

 The delete filespace command deletes file spaces in IBM Spectrum Protect server storage. A file
space is a logical space on the server that contains files you backed up or archived.

Enable SELinux to restore files on the Red Hat Enterprise Linux 5 client
If you are a non-root user, and you are trying to restore files on the Red Hat Enterprise Linux 5 client, you
must first enable SELinux.
If you do not enable SELinux, you will have problems if you restore files that have modified extended
attributes.

240 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Chapter 6. Archive and retrieve your data (UNIX and
Linux)
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. Many of the windows
and concepts are similar.
All the primary archive and retrieve procedures in this topic also apply to the web client, except for the
Preferences editor procedures.
You can complete the following primary archive and retrieve tasks:
• “Archiving data with the GUI” on page 241
• “Archive data examples by using the command line” on page 242
• “Deleting archive data” on page 245
• “Retrieving data with the GUI” on page 248
• “Retrieve data examples by using the command line” on page 248
Related concepts
“Backing up your data” on page 145
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.
Related tasks
“Starting a web client session” on page 136
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.

Archive files
To archive files, you must specifically select the files to archive. You can select the files by using a file
specification or by selecting them from a directory tree.
Your administrator might set up schedules to archive certain files on your workstation automatically. The
following sections cover how to archive files without using a schedule.
Related tasks
“Setting the client scheduler process to run as a background task and start automatically at startup” on
page 256
You can configure the IBM Spectrum Protect client scheduler to run as a background system task that
starts automatically when your system is started.

Archiving data with the GUI

You can archive a file or a group of files by using file names. You can select files that match your search
criteria by using a directory tree.

Procedure
Archive files with the following procedure.
1. Click Archive from the main window.

© Copyright IBM Corp. 1993, 2019 241

 2. In the Archive window, expand the directory tree by clicking the plus sign (+) or the folder icon next
to an object in the tree. 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.
5. In the Matching Files window, click the selection boxes next to the files you want to archive and
close the Matching Files window.
6. Enter your filter criteria in the Find Files window.
7. Click Filter. The Archive window displays the filtered files.
8. Click the selection boxes next to the filtered files or directories that you want to archive.
9. Enter the description, accept the default description, or select an existing description for your archive
package in the Description box.
The maximum length of a description is 254 characters. When an existing archive description is used,
the files or directories that are selected are added to the archive package. All archived packages with
the same description are grouped for retrieves, queries, and deletions.
10. To modify specific archive options, click Options.
Any options that you change are effective during the current session only.
11. Click Archive.
The archive Task List window displays the archive processing status.

Archive data examples by using the command line

You request archive services when you want to preserve copies of files in their current state, either for
later use or for historical or legal purposes. Examples of archiving data by using the command line are
shown.
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 choose to delete the original file from your workstation.
The following table shows examples of using the archive command to archive objects.

Table 48. Command line archive examples

Task Command Considerations
Archive all files in the /home/ dsmc archive "/home/proj1/ Use wildcards to archive more than
proj1 directory with a file *.txt" one file at a time.
extension of .txt.
Archive all files in the /home/ dsmc archive /home/jones/ Retrieve the archived files to your
jones/proj/ directory and delete proj/ -deletefiles workstation whenever you need
the files on your workstation. them again. For more information
about the deletefiles option,
see “Deletefiles” on page 340.
Archive the /home/jones/h1.doc dsmc archive /home/jones/ If you specify the
and /home/jones/test.doc h1.doc /home/jones/test.doc removeoperandlimit option with
files. the archive command, the 20-
operand limit is not enforced and is
restricted only by available
resources or other operating
system limits. With this option, you
can specify more than 20 files on a
single command. For more
information about this option, see
“Removeoperandlimit” on page
466.

242 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 48. Command line archive examples (continued)
Task Command Considerations
Archive a list of files in the / dsmc archive -filelist=/ Use the filelist option to
home/avi/filelist.txt file. home/avi/filelist.txt process a list of files. For more
information, see “Filelist” on page
387.
Archive the /home/jones/ dsmc archive /home/jones/ If you do not specify a description
ch1.doc file and assign a ch1.doc - with the archive command, the
description to the archive. description="Chapter 1, default is Archive Date:x, where
first version" x is the current system date. For
more information about the
description option, see
“Description” on page 341.
Archive all of the files in the / dsmc archive /home/jones/ For more information about the
home/jones/proj/ directory and proj/ -subdir=yes subdir option, see “Subdir” on
its subdirectories. page 515.
Use the v2archive option with the dsmc archive "/home/relx/ The backup-archive client archives
archive command to archive only dir1/" -v2archive only files in the /home/relx/dir1
files in the /home/relx/dir1 directory. Directories that exist in
directory, but not the relx or dir1 the path are not processed. For
directories. more information about the
v2archive option, see
“V2archive” on page 537.
Use the archmc option with the dsmc archive – For more information about the
archive command to specify the archmc=ret2yrs /home/plan/ archmc option, see “Archmc” on
available management class for proj1/budget.jan page 308. For more information
your policy domain to which you about management classes, see
want to bind your archived files. Chapter 9, “Storage management
policies,” on page 265.
Assume that you initiated a dsmc archive /usr/dir1/ The client considers the
snapshot of the /usr file system sub1/ -subdir=yes - snapshotroot value as a file
and mounted the snapshot as / snapshotroot=/snapshot/day1 space name. For more information,
snapshot/day1. You archive see “Snapshotroot” on page 504.
the /usr/dir1/sub1 directory
tree from the local snapshot and
manage it on the IBM Spectrum
Protect server under the file space
name /usr.

Related reference
“Archive” on page 593
The archive command archives a single file, selected files, or all files in a directory and its
subdirectories on a server.

Associate a local snapshot with a server file space

To associate data on the local snapshot with the real file space data that is stored on the IBM Spectrum
Protect server, use the snapshotroot option.
By using the snapshotroot option with the archive command with a vendor-acquired application that
provides a snapshot of a logical volume, you can associate the data on the local snapshot with the real file
space data that is stored on the IBM Spectrum Protect server.
You cannot use the snapshotroot option to take a volume snapshot, but you can use the option to
manage data that is created by a volume snapshot.

Chapter 6. Archive and retrieve your data (UNIX and Linux) 243
 Related reference
“Snapshotroot” on page 504
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.

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.

Before you begin

All agent nodes in the multiple node environment should be of the same platform type. Do not use target
nodes as traditional nodes. Use them only for multiple node processing.
Consider the following features of a proxied session:
• 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.
• You cannot perform a system state or system services backup or restore.
• You cannot access another node (either from the GUI drop down or use of the fromnode option).
• You cannot perform a NAS backup or restore.

About this task

Consolidating archived files to a common target node name on the server is useful when the workstation
responsible for performing the archive can change over time, such as with a Xsan or cluster. The
asnodename option also 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 V5.3 and higher.
Tivoli Storage Manager FastBack clients are also backed up using client node proxy.
Configuring your environment for proxied operations is a multiple step procedure that involves setting
options and commands on the backup-archive client and on the server.

Procedure
Perform steps “1” on page 244 through “5” on page 244 to install the client and grant proxy authority to
the nodes that can perform archive procedures on behalf of another node.
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 is not 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.
Step “6” on page 244 sets ensures that archived files are encrypted on the server.
6. Set the encryptkey option in the options file.

244 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Specify encryptkey=save in the options file to save the encryption key in the IBM Spectrum
Protect password file. Back up at least one file with asnode=ProxyNodeName to create a local
encryption key on each agent node in the multiple node environment.
Specify encryptkey=prompt in the options file if you want the node users to manage the
encryption key. Ensure that users of the agent nodes in the multiple node environment are using the
same encryption key.
Repeat this step if you change the encryption key. Use the same encryption key for all files that are
backed up, in the shared environment.
Perform steps “7” on page 245 to step “10” on page 245 to enable multinode operation, from the GUI.
7. 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.
8. Select Edit > Preferences to open the preferences window.
9. Select the General tab and fill in the As Node Name field with the name of the proxy authorized
target node.
10. Click Apply and then OK to close the preferences window.
Perform step “11” on page 245 to verify that your client node is now accessing the server as the target
node.
11. Open the tree window and verify that the target node name specified by the As Node Name field is
displayed.
Alternatively, you can verify that the target node name shows in the Accessing As Node field in the
Connection Information window.
12. Optional: To return to single node operation, delete the As Node Name from the Accessing As Node
field in the General > Preferences tab.
Related reference
Asnodename
Use the asnodename option to allow agent nodes to back up or restore data on behalf of another node
(the target node). This enables concurrent operations from multiple nodes to store data to the same
target node and file space in parallel.
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.

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.

Chapter 6. Archive and retrieve your data (UNIX and Linux) 245
 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 616
The delete archive command deletes archived files from IBM Spectrum Protect server storage. Your
administrator must give you the authority to delete archived files.

Advanced archive tasks

Access permissions, symbolic links, and hard links are advanced functions to consider when you archive
data.

Access permissions
When you archive a file, the client saves standard UNIX access permissions that are assigned to the file.
Depending on your operating system, it also saves extended permissions. For example, for files on an AIX
workstation, the client saves access control lists.
If you are a user, and you archive a file to which you have read access, you own the archived copy of the
file. You are the only user who can retrieve the archived file unless you grant access to another user.

Archive and retrieve symbolic links

The backup-archive client archives and retrieves symbolic links differently than it does regular files and
directories.
The way that the client archives and retrieves symbolic links depends on options settings, whether the
target directory is accessible, and the way you specify objects.
A UNIX symbolic link is a file that contains a pointer to another file or directory. The object the symbolic
link points to is called the target object.
A symbolic link can be backed up as path information to a target directory, or it can be backed up as a
directory. If the symbolic link is backed up as a directory, the files and folders in the target directory can
also be backed up.
What you restore depends on how the symbolic link was backed up, the scope of the restore, the setting
of the followsymbolic option, and whether the target directory is accessible at the time of restore.
For more information on how symbolic links are handled during archive, see the archsymlinkasfile
option.
Note: Symbolic link processing as described here does not apply to Mac OS X. Symbolic links are always
archived as files and are never followed.
The following table shows symbolic link archive and retrieve functions and the action taken:

Table 49. Symbolic link management table for archive and retrieve
Function Action taken
Archive of a file link. Archives the file to which the symbolic link points.
Archive of a directory link. Archives the directory and its contents.
Archive of a file with subdir=yes. Archives the file, directory path and all like-named
files in the subtree.
Archive of a directory with subdir=yes. Archives the directory, its contents, and contents of
subdirectories.
Archive of a symbolic link that points to a file or Archives the symbolic link.
directory that does not exist.

246 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 49. Symbolic link management table for archive and retrieve (continued)
Function Action taken
Retrieve a symbolic link that points to file; the file Replaces the file if replace=y is set.
and link exist.
Retrieve a symbolic link that points to file; the Retrieves the file replacing the file name with the
symbolic link no longer exists. symbolic link name and places it in the directory
where the symbolic link resided.
Retrieve a symbolic link that points to a directory; A directory is created in the directory where the
the symbolic link and directory no longer exist. symbolic link resides, and all files and
subdirectories are restored to that directory. The
symbolic link name is used as the new directory
name.
Retrieve a symbolic link that points to a directory; The directory is not retrieved as long as the
the symbolic link and directory still exist. symbolic link exists.

Related reference
“Archsymlinkasfile” on page 308
The archsymlinkasfile option specifies whether the backup-archive client follows a symbolic link and
archives the file or directory to which it points, or archives the symbolic link only. Use this option with the
archive command.

Hard links
When you archive files that are hard-linked, the backup-archive client archives each instance of the linked
file.
For example, if you archive two files that are hard-linked, the client archives the file data twice.
When you retrieve hard-linked files, the client reestablishes the links. For example, if you had a hard-
linked pair of files, and only one of the hard-linked files is on your workstation, when you retrieve both
files, they are hard-linked. The only exception to this procedure occurs if you archive two files that are
hard-linked and then break the connection between them on your workstation. If you retrieve the two
files from the server, the client respects the current file system and does not retrieve the hard link.
Tip: If you do not archive and retrieve all files that are hard-linked at the same time, problems can occur.
To ensure that hard-linked files remain synchronized, archive all hard links at the same time and retrieve
those same files together.

Retrieve archives
Retrieve a file when you want to return an archive copy from the server to your workstation.
Many of the advanced considerations for retrieving files are the same as for restoring files.
Important: When you retrieve a file without any specifications, and more than one version of the archive
copy exists on the server, the client retrieves all of the copies. 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
“Restore or retrieve files to another workstation” on page 238
From a different workstation, you can restore or retrieve files you have already backed up from your own
workstation. You must know the IBM Spectrum Protect password assigned to your node.
Related tasks
“Authorizing another user to restore or retrieve your files” on page 236

Chapter 6. Archive and retrieve your data (UNIX and Linux) 247
 You can authorize another user on the same workstation or a different workstation to restore backup
versions or retrieve archive copies of your files.
“Restoring or retrieving files from another client node” on page 237
After users grant you access to their files on the server, you can restore or retrieve those files to your local
system.

Retrieving data with the GUI

You can retrieve an archived file with the GUI.

Procedure
1. Click Retrieve from the client Java 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 that 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 next to 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. Enter the appropriate information in the
Retrieve Destination window.
11. Click Retrieve. The Task List window displays the retrieve processing status.

Retrieve data examples by using the command line

You can retrieve a single file, a group of files, or all the files in a directory or subdirectory.
When you retrieve a file, a copy of that file is sent from the IBM Spectrum Protect server. The archived file
remains in storage.
Use the retrieve command to retrieve files from storage to your workstation. The following table shows
examples of using the retrieve command.

Table 50. Command line examples of retrieving archives

Task Command Considerations
Retrieve the /home/jones/ dsmc retrieve /home/jones/ If you do not specify a destination,
h1.doc file to its original directory. h1.doc the files are retrieved to their
original location.
Retrieve the /home/jones/ dsmc retrieve /home/jones/ None.
h1.doc file with a new name and h1.doc /home/smith/h2.doc
directory.
Retrieve all files from the /home/ dsmc retrieve "/home/jones/ None.
jones directory that end with the *.bak" /home/smith/
characters .bak to the /home/
smith directory.
Retrieve the /home/jones/ dsmc retrieve /home/jones/ If you do not specify a description
ch1.doc file and assign a ch1.doc - with the retrieve command, the
description. description="Chapter 1, default is Retrieve Date:x,
first version" where x is the current system date.

248 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 50. Command line examples of retrieving archives (continued)
Task Command Considerations
Use the pick option to display a list dsmc retrieve "/home/ None.
of archives from which you can jones/*" -pick
select files to retrieve.
Retrieve a list of files that are dsmc retrieve -filelist=/ None.
specified in the home/dir2/retrievelist.txt
retrievelist.txt file to their
original directory.

Related reference
“Retrieve” on page 693
The retrieve command obtains copies of archived files from the IBM Spectrum Protect server. You can
retrieve specific files or entire directories.
“Description” on page 341
The description option assigns or specifies a description for files when performing archive, delete
archive, retrieve, query archive, or query backupset.
“Filelist” on page 387
Use the filelist option to process a list of files.
“Pick” on page 451
The pick option creates a list of backup versions or archive copies that match the file specification you
enter.

Archive management classes

The backup-archive client checks the include options in your include-exclude options list to determine
which management class to assign to your archived files.
If you do not assign a management class to a file with the include option, the client assigns the default
management class to the file. The client can archive only a file if the selected management class contains
an archive copy group.
You can override the default management class by using the archmc option, or by clicking Options in the
Archive window in the GUI, clicking Override include/exclude list, and then selecting the management
class.
You can also add include-exclude statements in the backup-archive client Java GUI or web client
directory tree. Then, you can use the Utilities Preview Include-Exclude function to preview the include-
exclude list before you send data to the server.
Related concepts
“Assign a management class to files” on page 271
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.
“Display information about management classes and copy groups” on page 267
You can display policy information with the command-line interface or with a graphical user interface.
Related reference
“Preview Archive” on page 635
The preview archive command simulates an archive command without sending data to the server.
“Preview Backup” on page 636
The preview backup command simulates a backup command without sending data to the server.

Chapter 6. Archive and retrieve your data (UNIX and Linux) 249
250 IBM Spectrum Protect UNIX and Linux 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:
• A schedule definition must exist for a specific policy domain.
• A schedule association must exist for the required node, which belongs to that policy domain.
• 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, image backup (does not apply to Mac OS X),
image restore (does not apply to Mac OS X), command, and macro. The scheduled action that is most
frequently used is incremental with the objects parameter left undefined. With this setting, the backup-
archive client performs a domain incremental backup of all file systems 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:

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

© Copyright IBM Corp. 1993, 2019 251

 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=’"/home/proj1/Some file.doc"’
objects=’"/home/proj1/Some file.doc" "/home/Another file.txt" /home/noblanks.txt’
objects=’"/home/My Directory With Blank Spaces/"’
objects=’"/Users/user1/Documents/Some file.doc"’
objects=’"/Users/user1/Documents/Some file.doc"
"/Users/user5/Documents/Another file.txt" /Users/user3/Documents/noblanks.txt’
objects=’"/Users/user1/My Directory With Blank Spaces/"’

This syntax ensures that a file specification containing a space, such as /home/proj1/Some file.doc,
is treated as a single file name, and not as two separate files (/home/proj1/Some, and file.doc).
The following examples show how to delimit schedule options parameters when file specifications
contain space characters:

options='-preschedulecmd="/home/me/my files/bin/myscript"
-postschedulecmd="/home/me/my files/bin/mypostscript" -quiet'
options='-presched="/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 135
You must follow certain rules when you specify an input string that has blanks or quotation marks.

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.
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.

252 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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 Server defined Server global override

managedservices X
maxcmdretries X SET MAXCMDRETRIES
command
maxschedsessions X
postschedulecmd, X
postnschedulecmd
preschedulecmd, X
prenschedulecmd
queryschedperiod X SET
QUERYSCHEDPERIOD
command
randomize X
retryperiod X SET RETRYPERIOD
command
schedcmddisabled X
schedlogname X
schedlogretention X
schedmode X SET SCHEDMODES
command
sessioninitiation X X UPDATE NODE command
tcpclientaddress X X
(also defined on server
when
sessioninit=servero
nly as
part of the node
definition)

tcpclientport X X
(also defined on server
when
sessioninit=servero
nly as
part of the node
definition)

Chapter 7. IBM Spectrum Protect scheduler overview 253

 Client defined options are defined in the dsm.sys or dsm.opt file, depending on the option and platform.
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

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.
• 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.
• 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

254 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 command might exit with return code 3, if
widget 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 exits with return code 0 if the command
was successful; otherwise it exits with a nonzero return code. The logic for a script running widget might
look like this example:

run 'widget'
if lastcc == 3
exit 0
else
exit 1

Related reference
“Postschedulecmd/Postnschedulecmd” on page 453
The postschedulecmd/postnschedulecmd option specifies a command that the client program
processes after it runs a schedule.
“Preschedulecmd/Prenschedulecmd” on page 456
The preschedulecmd option specifies a command that the client program processes before it runs a
schedule.

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
• Defined using the managedservices schedule option and started with client acceptor daemon
services (dsmcad).
• The client acceptor daemon starts and stops the scheduler process as needed for each scheduled
action.
• Requires fewer system resources when idle.
• 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.
• Cannot be used with SESSIONINITiation=SERVEROnly backups.
IBM Spectrum Protect traditional scheduler services
• Started with command dsmc sched command.
• Remains active, even after scheduled backup is complete.
• Requires higher use of system resources when idle.

Chapter 7. IBM Spectrum Protect scheduler overview 255

 • 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.
When you are running a client acceptor-managed schedule, set the client acceptor process to start
automatically at startup time; not the scheduler process. For the traditional method, set the scheduler
process to start automatically at startup time.
You can configure the client acceptor to run as a background system task that starts automatically when
your system is started. To configure the client acceptor to manage scheduled backups, you use the
managedservices option to specify whether the client acceptor manages only the scheduler, only the
web client, or both the scheduler and web client. The method for setting up the client acceptor as a
system task varies for each platform.
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 testing purposes, you can always start the scheduler in the
foreground by running dsmc sched from a command prompt (without a managedservices stanza set).
To start the scheduler automatically at startup time, use either the client acceptor-managed method or
the traditional method.
Client acceptor-managed method
1. In your dsm.sys file, set the managedservices option to schedule or schedule webclient.
2. Start the client acceptor.
a. On AIXand Solaris clients, add the following entry into the system startup file (/etc/inittab
for most platforms):

tsm::once:/usr/bin/dsmcad > /dev/null 2>&1 # TSM Client

Acceptor Daemon

b. On Linux clients, the installation program creates a startup script for the client acceptor
(dsmcad) in /etc/init.d. The client acceptor (dsmcad) must be started before it can manage
scheduler tasks, or manage the web client. As root, use the following command to start, stop,
or restart the client acceptor, or check its status:
service dsmcad start

stop

restart

status

To enable the client acceptor to start automatically after a system restart, add the service as
follows, at a shell prompt:

256 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 # chkconfig --add dsmcad

If the Linux operating system runs the systemd initialization service, complete the following
steps to start the dsmcad and to run it at system start time:
1) Copy the provided systemd unit file /opt/tivoli/tsm/client/ba/bin/
dsmcad.service to the /etc/systemd/system/ directory.
2) Run the following command to refresh the systemd unit list:

systemctl daemon-reload

3) Run the following command to start the client acceptor at system start time:

systemctl enable dsmcad.service

4) Run the following command to start the client acceptor:

systemctl start dsmcad.service

c. On Mac OS X, the client acceptor must be installed as a Startup Item. A system administrator
must use the IBM Spectrum Protect Tools for Administrators to install and start the client
acceptor. To start, stop, or restart the client acceptor, use the following command:
sudo /sbin/SystemStarter start dsmcad

stop

restart

3. In your dsm.sys file, set the passwordaccess option to generate.

4. Run a command like dsmc query sess to store the node password.
Traditional method:
1. Set the managedservices option.
• On AIX, Linux, and Solaris clients, either remove the option entirely (it defaults to webclient) or
set it to webclient.
• On Mac OS X clients, set the managedservices option to either webclient or none. Do not set
the option to schedule.
2. On AIX, Linux, and Solaris, add the following entry into the system startup file, for example, /etc/
inittab, where it is supported:

tsmsched::once:/usr/bin/dsmc sched > /dev/null 2>&1 # TSM scheduler

3. In your dsm.sys file, set the passwordaccess option to generate.

4. Run a command like dsmc query sess to store the node password.
5. To start the client scheduler on your client node and connect to the server schedule, enter the
following command:

dsmc schedule

If the current directory is not in your PATH environment variable, enter the following command:

./dsmc schedule

When you start the client scheduler, it runs continuously until you close the window, end the
process, or log off your system.
To run the schedule command in the background and to keep the client scheduler running, even
if you log off your system, enter the following command:

nohup dsmc schedule 2> /dev/null &

Chapter 7. IBM Spectrum Protect scheduler overview 257

 Related reference
“Cadlistenonport” on page 320
The cadlistenonport option specifies whether to open a listening port for the client acceptor.

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 51 on page 258 displays sample classic query schedule output.

Table 51. Sample classic query schedule output

Schedule Name: DAILY_INC

Description: Daily System-wide backup
Schedule Style: Classic
Action: Incremental
Options: QUIET
Objects:
Priority: 1
Next Execution: 30 minutes
Duration: 4 Hours
Period: 1 Day
Day of Week: Any
Month:
Day of Month:
Week of Month:
Expire: Never

Schedule Name: WEEKLY_INC

Description: Weekly backup for project files
Schedule Style: Classic
Action: Incremental
Options: QUIET
Objects: /proj
Priority: 1
Next Execution: 60 minutes
Duration: 8 Hours
Period: 7 Days
Day of Week: Friday
Month:
Day of Month:
Week of Month:
Expire: Never

The schedule name, WEEKLY_INC, starts a weekly incremental backup in the /proj file system.
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 52 on page 259
displays sample enhanced query schedule output.

258 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 52. 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 in the background, output from scheduled commands is directed
to the dsmsched.log file in the current directory, or to the path and file name that you specified. The
dsmsched.log cannot be a symbolic link.
Note: On Mac OS X, by default the log can be found in one of these locations:

~/Library/Logs/tivoli/tsm
/Library/Logs/tivoli/tsm

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 260

Chapter 7. IBM Spectrum Protect scheduler overview 259

 You can modify scheduling options in the client options file or the graphical user interface (GUI).

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 292
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.

Scheduler options for commands

The scheduler executes commands under a user ID of 0 (root); however, some commands might need to
be executed under a user ID other than 0.
In this case, your IBM Spectrum Protect administrator can define schedules for commands that are
executed under a user ID different from the scheduler user ID using the schedcmduser server option.
The schedcmduser option specifies the name of a valid user on the system where a scheduled command
is executed. This option can only be defined by the IBM Spectrum Protect server administrator. If this
option is specified, the command is executed with the authorization of the specified user. Otherwise, it is
executed with the scheduler authorization.

SCHEDCMDUser user_name

user_name
Specifies the name of a valid user on the system where a scheduled command is executed.
Note: The schedcmduser option does not affect the user ID used for the pre-schedule and post-
schedule commands. Pre-schedule and post-schedule always run as root (user ID 0).

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 479

260 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 The schedcmddisabled option specifies whether to disable the scheduling of commands by the server
action=command option on the define schedule server command.
“Schedrestretrdisabled” on page 486
The schedrestretrdisabled option specifies whether to disable the execution of restore or retrieve
schedule operations.
“Srvprepostscheddisabled” on page 507
The srvprepostscheddisabled option specifies whether to prevent the pre-schedule and post-
schedule commands specified by the IBM Spectrum Protect administrator from executing on the client
system, when performing scheduled operations.
“Srvprepostsnapdisabled” on page 508
The srvprepostsnapdisabled option specifies whether to prevent the pre-snapshot and post-
snapshot commands specified by the IBM Spectrum Protect administrator from executing on the client
system, when performing scheduled image snapshot backup operations.

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 file systems on your client system must be backed up daily, and that one file
system 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.
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:
• Define a unique node name for each process
• Specify unique schedule and error logs for each process
• When running in prompted mode, you must use the tcpclientport option to specify a unique port for
each process.
The advantages of using multiple schedule processes:
• You can run more than one scheduled backup at the same time.
• 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:
• A unique file space for each node name on the IBM Spectrum Protect server is created.
• When restoring the data, you must use the same node name associated with the backup.
Multiple schedule processes can run on UNIX and Linux platforms with either the client acceptor
daemon-managed method, or the traditional method of running the scheduler. In either case, there are
certain setup requirements:
• Each process must run using a different node name.
• You must create multiple stanzas in the dsm.sys file for each scheduler process. In each stanza, you
must define a unique node name, along with unique values for the options errorlogname and

Chapter 7. IBM Spectrum Protect scheduler overview 261

 schedlogname. You might also choose to define customized domain, include, and exclude
statements for each stanza.
• In your dsm.sys file, set the passwordaccess option to generate in each stanza. The password must
be generated for each node name that is running a scheduler process, by running a command such as
dsmc query sess.
• If running with the schedmode option set to prompt, you should set a unique tcpclientport value for
each stanza.
You must start each dsmc sched command or instance with the -servername option to reference its
unique stanza name in dsm.sys. For dsmcad, it is necessary to define the environment variable
DSM_CONFIG for each instance of dsmcad to reference its unique option file.
The following is an example configuration of two schedule processes managed by the client acceptor
daemon in the dsm.sys file. Note that you must use full paths for the log file names to avoid the files being
written in the root directory):

servername tsm1_sched1
nodename aixsvt01_sched1
tcpserv firebat
tcpclientport 1507
passwordaccess generate
domain /svt1
schedmode prompted
schedlogname /tsm/dsmsched1.log
errorlogname /tsm/dsmerror1.log
managedservices schedule

servername tsm1_sched2
nodename aixsvt01_sched2
tcpserv firebat
tcpclientport 1508
passwordaccess generate
domain /svt1
schedmode prompted
schedlogname /tsm/dsmsched2.log
errorlogname /tsm/dsmerror2.log
managedservices schedule

Contents of /test/dsm.opt1:

servername tsm1_sched1

Contents of /test/dsm.opt2:

servername tsm1_sched2

Open two shell command windows:

• In shell command window 1, enter:

export DSM_CONFIG=/test/dsm.opt1
sudo dsmcad

• In shell command window 2, enter:

export DSM_CONFIG=/test/dsm.opt2
sudo dsmcad

Note: You should enter these commands into a shell script if you intend to have the dsmcad processes
started directly from /etc/inittab so that the proper DSM_CONFIG variable can be set prior to launching
dsmcad.

262 IBM Spectrum Protect UNIX and Linux 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.
• If the highest severity message is informational (ANSnnnnI), then the return code is 0.
• If the highest severity message is a warning (ANSnnnnW), then the return code is 8.
• 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 53 on page 263 describes the return codes and their meanings.

Table 53. 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.
• The file satisfies an entry in an exclude list. Excluded files generate log entries only
during selective backups.
• The file was in use by another application and could not be accessed by the client.
• The file changed during the operation to an extent prohibited by the copy serialization
attribute. See “Copy serialization attribute” on page 269.

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 file system or file specification from being
processed yields return code 12.

© Copyright IBM Corp. 1993, 2019 263

 Table 53. 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 "/home/devel/*" -subdir=yes

incremental "/home/devel/TestDriver/*" -subdir=yes
archive "/home/plan/proj1/*" -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.
Related concepts
“Scheduler options for commands” on page 260
The scheduler executes commands under a user ID of 0 (root); however, some commands might need to
be executed under a user ID other than 0.

264 IBM Spectrum Protect UNIX and Linux 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:
• Whether a file is eligible for backup or archive services.
• How many backup versions to keep.
• How long to keep inactive backup versions and archive copies.
• Where to place the copies in storage.
• 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.
If you have the IBM Spectrum Protect for Space Management client installed, your administrator also
defines rules that determine whether files are eligible for migration from your local file systems to
storage.
This topic explains:
• Policy criteria (policy domains, policy sets, copy groups, and management classes).
• How to display policies.
• 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:
• A department, such as Accounting.
• A physical location, such as a particular building or floor.
• 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, 2019 265

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:
• System data that is critical for the business.
• Application data that changes frequently.
• Report data that Management reviews monthly.
• Legal information that must be retained indefinitely, requiring a large amount of disk space.
Note: If you have the IBM Spectrum Protect for Space Management installed, it can also contain specific
requirements for migrating files to storage.
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:
• If your data is not associated with a management class, IBM Spectrum Protect uses the default
management class in the active policy set.
• 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.
• 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:
• How many days must elapse before a file is backed up again.
• 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:
• On which media type the server stores backup versions of your files and directories.
• How many backup versions the server keeps of your files and directories.
• How long the server keeps backup versions of your files and directories.
• How long the server keeps inactive backup versions.
• How long the last remaining inactive version of a file is kept.
An archive copy group contains attributes that control:
• Whether a file is archived if it is in use

266 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • On which media type the server stores archived copies of your files
• How long the server keeps archived copies of your files
Related concepts
“Select a management class for files” on page 270
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.
“Retention grace period” on page 273
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.

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 54 on page 267 shows the default values for the backup and archive copy groups in the standard
management class.

Table 54. 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

Chapter 9. Storage management policies 267

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.

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.

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.

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.

268 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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:
• 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.
• 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.
• Dynamic. A file or directory is backed up or archived on the first attempt regardless of whether it
changes during a backup or archive.
• 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 reference
“Snapshotproviderimage” on page 504
Use the snapshotproviderimage option to enable snapshot-based image backup, and to specify a
snapshot provider.

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:
• The date or time of the last modification is different.
• The size is different.

Chapter 9. Storage management policies 269

 • If only the metadata changes (such as access permissions), the client might back up only the
metadata.
• The owner is different.
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 306
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.

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 80
Data deduplication is a method of reducing storage needs by eliminating redundant data.
Related reference
“Deduplication” on page 338
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.
“Enablededupcache” on page 365
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.
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.

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:
• 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.
• Does the management class contain an archive copy group?

270 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 You cannot archive a file associated with a management class that does not contain an archive copy
group.
• 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.
• 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.
• Does the backup copy group specify an adequate number of backup versions to keep, along with an
adequate length of time to keep them?
• Does the archive copy group specify an adequate length of time to keep archived copies of files?
Related concepts
“Copy serialization attribute” on page 269
The copy serialization attribute determines whether a file can be in use during a backup or archive,
and what to do if it is.

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 /home/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:

include /.../* managall

The following examples show how to assign a management class to files:

exclude /.../*.sno
include /home/winter/.../*.ice mcweekly
include /home/winter/december/*.ice mcdaily
include /home/winter/january/*.ice mcmonthly
include /home/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.

Chapter 9. Storage management policies 271

 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

When you archive a file using the graphical user interface, you can select a different management class to
override the management class assigned to the file.
Related reference
“Dirmc” on page 345
The dirmc option specifies the management class you want to use for directories.
“Include options” on page 403
The include options specify objects that you want to include for backup and archive services.

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 /home/jones/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.
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:
• GUI or web client: Select View Policy Information from the Utilities menu.

272 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • 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.
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.
• 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.
• 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.
• 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:

Chapter 9. Storage management policies 273

 • You change the management class for a file, but neither the default management class nor the new
management class contain a backup copy group.
• 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 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 703

274 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Using the set event command, you can specify the circumstances for when archived data is deleted.

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.
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.

Chapter 9. Storage management policies 275

276 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Chapter 10. 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 297
You can override some of the options in your client options file (dsm.opt) file by entering them with
appropriate backup-archive client commands.
Related reference
“Reading syntax diagrams” on page xxii
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.

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 system-options file (dsm.sys), client user-options file
(dsm.opt), or on the command line.
You can set the following types of options:
• Communication options
• Server and node options
• Backup and archive processing options
• Restore and retrieve processing options
• Scheduling options
• Format options
• Command processing options
• Authorization options
• Error processing options
• Transaction processing option
• Web client options
• 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.
Related concepts
“Entering options with a command” on page 298
You must follow the general rules for entering options with a command.
Related tasks
“Creating and modifying the client system-options file” on page 54

© Copyright IBM Corp. 1993, 2019 277

 The client system-options file is an editable file that identifies the server and communication method, and
provides the configuration for backup, archiving, hierarchical storage management, and scheduling.

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.
For UNIX and Linux use one of the following communication protocols:
• TCP/IP
• Shared memory (AIX, Linux)
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 323
The commmethod option specifies the communication method you use to provide connectivity for client-
server communication.

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 55. TCP/IP options

Option Description
httpport “Httpport” on page Specifies a TCP/IP port address for the web client.
397
lanfreetcpport Specifies the TCP/IP port number where the IBM Spectrum Protect
“Lanfreetcpport” on page 425 storage agent is listening.
lanfreetcpserveraddress Specifies the TCP/IP address for the IBM Spectrum Protect storage
“Lanfreetcpserveraddress” on agent.
page 427
tcpbuffsize “Tcpbuffsize” on Specifies the size, in kilobytes, of the internal TCP/IP communication
page 522 buffer.
tcpnodelay “Tcpnodelay” on Specifies whether the server or client disables the delay of sending
page 525 successive small packets on the network. This option is for all UNIX
clients.
tcpadminport “Tcpadminport” Specifies a separate TCP/IP port number on which the server is
on page 522 waiting for requests for administrative client sessions, allowing
secure administrative sessions within a private network.
tcpcadaddress Specifies a TCP/IP address for dsmcad.
“Tcpcadaddress” on page 523
tcpport “Tcpport” on page 526 Specifies the TCP/IP port address for an IBM Spectrum Protect
server.
tcpserveraddress Specifies the TCP/IP address for an IBM Spectrum Protect server.
“Tcpserveraddress” on page 526

278 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 55. TCP/IP options (continued)
Option Description
tcpwindowsize Specifies the size, in kilobytes, of the TCP/IP sliding window for your
“Tcpwindowsize” on page 527 client node.
webports “Webports” on page Enables the use of the web client outside a firewall by specifying the
582 TCP/IP port number used by the client acceptor daemon and the web
client agent service (web client agent service does not apply to Mac
OS X) for communications with the web GUI.

Related reference
“Nfstimeout” on page 441
The nfstimeout option specifies the number of seconds the client waits for a status system call on an
NFS file system before it times out.

Shared memory options

This topic provides information on the shared memory options that you can use.

Table 56. Shared memory communication options

Option Description
lanfreeshmport Specifies the unique number that is used by the client and the
“Lanfreeshmport” on page 425 storage agent to identify shared memory area used for
communications.
lanfreeshmport “Shmport” on Specifies the unique number that is used by the client and the server
page 492 to identify shared memory area used for communications.

Server options
Use the servername option in your dsm.sys file to begin a group of options (stanzas) used to connect to
the IBM Spectrum Protect server.
You can set up multiple groups of stanzas in the dsm.sys file to connect to different servers. Each
servername stanza must have listed below it all client option stanzas required to establish
communication with a server. The stanza list can also contain other options for backup-archive
operations.
If your client system-options file contains only one stanza - Your client node contacts the server you
specify in that stanza for all services.
If your client system-options file contains more than one stanza - You can specify a default server with the
defaultserver option. If you do not specify a default server, IBM Spectrum Protect contacts the server
you specify in the first stanza of your dsm.sys file.
Place the defaultserver option at the beginning of your dsm.sys file before any server stanzas. See
“Defaultserver” on page 339 for more information.
Use the servername option in the client user-options file (dsm.opt) or on the command line to specify a
server to contact for backup-archive services. This overrides the default server specified in your
(dsm.sys) file.
Note: You cannot override the migration server specified in the client system-options file.
Table 57 on page 280 shows a sample dsm.sys file.

Chapter 10. Processing options 279

 Table 57. Sample client system-options file
Sample dsm.sys file

DEFAULTServer server2

SErvername server1
NODename node1
COMMMethod TCPip
TCPPort 1500
TCPServeraddress node.domain.company.com
PASSWORDAccess generate
GRoups system adsm
USERs ashton stewart kaitlin
INCLExcl /adm/adsm/backup1.excl

SErvername server2
COMMMethod SHAREdmem
shmport 1520
PASSWORDAccess prompt
GRoups system adsm
USERs danielle derek brant
INCLExcl /adm/adsm/backup2.excl

Backup and archive processing options

You can specify client options to control some aspects of backup and archive processing.

Table 58. Backup and archive processing options

Option Description
Use the afmskipuncachedfiles option to
afmskipuncachedfiles
specify whether uncached and dirty files in
“Afmskipuncachedfiles” on page 307
General Parallel File System (GPFS™) Active
File Management file sets are processed for
backup, archive, and migration operations.
Use the archmc option with the archive
archmc
command to specify the available
“Archmc” on page 308
management class for your policy domain to
which you want to bind your archived files.
Specifies whether you want the client to
archsymlinkasfile
follow a symbolic link and archive the file or
“Archsymlinkasfile” on page 308
directory to which it points, or archive the
symbolic link only.
Use the asnodename option to allow agent
asnodename
nodes to back up or restore data on behalf of
“Asnodename” on page 309
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.

280 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 58. Backup and archive processing options (continued)
Option Description
Use this option with the domain option to
automount
specify all automounted file systems that the
“Automount” on page 316
client tries to mount at the following points in
time:
• When the backup-archive client starts
• When the backup is started
• When the backup-archive client reaches an
automounted file system during backup

Specifies whether to rename an existing file

autofsrename
space on a Unicode-enabled server so a
“Autofsrename” on page 315
Unicode-enabled file space can be created
for the current operation.
Specifies the number of times the client
changingretries
attempts to back up or archive a file that is in
“Changingretries” on page 321
use.
The compressalways option specifies
compressalways
whether to continue compressing an object if
“Compressalways” on page 325
it grows during compression. Use this option
with the compression option.
The compression option compresses files
compression
before you send them to the server.
“Compression” on page 326
Compressing your files reduces data storage
for backup versions and archive copies of
your files.
The createnewbase option creates a base
createnewbase
snapshot and uses it as a source to run a full
“Createnewbase” on page 329
incremental. Setting this option ensures the
backup of any files that might have been
skipped during the snapshot difference
incremental.
Specifies whether to eliminate redundant
deduplication
data on the client side when the client
“Deduplication” on page 338
transfers data to theIBM Spectrum Protect
server during backup or archive processing.
Specifies the location where the client-side
dedupcachepath
data deduplication cache database is
“Dedupcachepath” on page 337
created, if the enablededupcache=yes
option is set during backup or archive
processing.
Determines the maximum size of the data
dedupcachesize
deduplication cache file.
“Dedupcachesize” on page 338

Specifies whether you want to enable client-

enablededupcache
side data deduplication cache, so that the
“Enablededupcache” on page 365
backup-archive client gets the changed data
from the cache.

Chapter 10. Processing options 281

 Table 58. Backup and archive processing options (continued)
Option Description

deletefiles Use the deletefiles option with the

“Deletefiles” on page 340 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.

The description option assigns or

description
specifies a description for files when the
“Description” on page 341
client performs archive, delete, retrieve,
query archive, or query backupset
operations.
Use the detail option to list management
detail
class, file space, backup, and archive
“Detail” on page 342
information, depending on the command with
which it is used.
Use the diffsnapshot option to determine
diffsnapshot
whether the client creates a differential
“Diffsnapshot” on page 343
snapshot.
Specifies the management class to use for
dirmc
directories. If you do not specify this option,
“Dirmc” on page 345
the client uses the management class in the
active policy set of your policy domain with
the longest retention period.
Backs up, restores, archives, retrieves, or
dirsonly
queries directories only.
“Dirsonly” on page 346

Specifies the location where the disk cache

diskcachelocation
database is created if the option
“Diskcachelocation” on page 348
memoryefficient=diskcachemethod
option is set during an incremental backup.
Specifies the file systems to include in your
domain
default client domain for an incremental
“Domain” on page 349
backup.
Specifies the mounted file systems and raw
domain.image
logical volumes that you want to include in
“Domain.image” on page 353
your client domain for an image backup. This
option is for AIX, Linux x86_64, Linux on
POWER, and Solaris only.
Specifies the volumes to include in your
domain.nas
default domain for NAS image backups.
“Domain.nas” on page 354

Specifies the virtual machines to include in

domain.vmfull
full image backups of VMware virtual
“Domain.vmfull” on page 355
machines.

282 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 58. Backup and archive processing options (continued)
Option Description
Specifies whether files encrypted by an AIX
efsdecrypt
Encrypted File System (EFS) are read in
“Efsdecrypt” on page 363
encrypted or decrypted format.
Allows the client to connect to a data
enablearchiveretentionprotection
retention server.
“Enablearchiveretentionprotection” on page 363

Specifies whether to enable an available

enablelanfree
LAN-free path to a storage area network
“Enablelanfree” on page 367
(SAN) attached storage device.
“Exclude options” on page 374 Use these options to exclude a file or group of
files from backup services and space
exclude management services (if the HSM client is
exclude.backup installed). The exclude.backup option
exclude.file excludes only files from normal backup, but
exclude.file.backup not from HSM.

Select AES-256 or AES-128 bit data

encryptiontype
encryption. AES 256-bit data encryption
“Encryptiontype” on page 368
provides the highest level of data encryption.
Specifies whether to save the encryption key
encryptkey
password locally when the client performs a
“Encryptkey” on page 369
backup-archive operation or whether to
prompt for the encryption key password.
Excludes a file or a group of files that match
exclude.archive
the pattern from archive services only.
“Exclude options” on page 374

Excludes a file or a group of files that are

exclude.attribute.symlink
symbolic links or aliases (aliases apply to
“Exclude options” on page 374
Mac OS X) from backup processing only.
Excludes files from compression processing if
exclude.compression
you set the compression option to yes. This
“Exclude options” on page 374
option applies to backups and archives.
Excludes a directory, its files, and all its
exclude.dir
subdirectories and their files from backup
“Exclude options” on page 374
processing.
Excludes specified files from encryption
exclude.encrypt
processing.
“Exclude options” on page 374

Excludes file spaces that match a pattern.

exclude.fs
This option is valid for all UNIX clients.
“Exclude options” on page 374

Excludes file systems on the NAS file server

exclude.fs.nas
from an image backup when used with the
“Exclude options” on page 374
backup nas command. This option is for
AIX and Solaris clients only.

Chapter 10. Processing options 283

 Table 58. Backup and archive processing options (continued)
Option Description
Excludes mounted file systems and raw
exclude.image
logical volumes that match the specified
“Exclude options” on page 374
pattern from full image backup operations.
This option is valid only for AIX, Solaris, and
all Linux clients.
Specifies the branch ID of the remote
fbbranch
FastBack server to back up or archive.
“Fbbranch” on page 381

Specifies the name of one or more FastBack

fbclientname
clients to back up from the backup proxy.
“Fbclientname” on page 382

Specifies the name of one or more Tivoli

fbpolicyname
Storage Manager FastBack policies that you
“Fbpolicyname” on page 383
want to back up from the backup proxy.
Specifies the location of the Tivoli Storage
fbreposlocation
Manager FastBack repository for the IBM
“Fbreposlocation” on page 384
Spectrum Protect client proxy to connect to
issue MOUNT DUMP, MOUNT ADD, and MOUNT
DEL commands.
Specifies host name of the FastBack server
fbserver
workstation or the FastBack Disaster
“Fbserver” on page 385
Recovery Hub workstation that owns the
repository that is specified by the
fbreposlocation option.
Specifies the name of one or more Tivoli
fbvolumename
Storage Manager FastBack volumes to back
“Fbvolumename” on page 386
up from the backup proxy.
Specifies a list of files to be processed for the
filelist
command. The client opens the designated
“Filelist” on page 387
file list and processes the files that are listed
within according to the command.
Backs up, restores, retrieves, or queries files
filesonly
only.
“Filesonly” on page 390

Use this option with the backup group

groupname
command to specify the fully qualified name
“Groupname” on page 396
of the group leader for a group.
Specifies an object type for a client-side data
ieobjtype
deduplication operation. This option is used
“Ieobjtype” on page 399
with the include.dedup and
exclude.dedup options.
Specifies the minimum size of empty regions
imagegapsize
on a volume that you want to skip during
“Imagegapsize” on page 400
image backup. This option is valid for AIX
JFS2 clients.

284 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 58. Backup and archive processing options (continued)
Option Description
Specifies the path and file name of an
inclexcl
include-exclude options file.
“Inclexcl” on page 402

“Include options” on page 403 Use these options to include files or assign
management classes for backup processing.
include
include.backup
include.file

Includes files or assigns management

include.archive
classes for archive processing.
“Include options” on page 403

Includes a file or a group of files that are

include.attribute.symlink
symbolic links or aliases (aliases apply to
“Include options” on page 403
Mac OS X) within broad group of excluded
files for backup processing only.
Includes files for compression processing if
include.compression
you set the compression option to yes. This
“Include options” on page 403
option applies to backups and archives.
Includes the specified files for encryption
include.encrypt
processing. By default, the client does not
“Include options” on page 403
perform encryption processing.
Use the include.fs option to control how
include.fs
the client processes your file space for
“Include options” on page 403
incremental backup.
Use the include.fs.nas option to bind a
include.fs.nas
management class to Network Attached
“Include options” on page 403
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 dsm.sys file. For more information, see
“Toc” on page 531. This option is valid for
AIX and Solaris clients only.
Specifies a file system or logical volume to be
include.image
included for image backup processing. This
“Include options” on page 403
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 .This option is valid for AIX,
Solaris, and all Linux clients.
Use with the incremental command to
incrbydate
request an incremental backup by date.
“Incrbydate” on page 420

Chapter 10. Processing options 285

 Table 58. Backup and archive processing options (continued)
Option Description
Use with the restore image command to
incremental
ensure that any changes that were made to
“Incremental” on page 421
the base image are also applied to the
restored image. This option is valid for AIX,
Solaris, and all Linux clients.
Specifies a memory-saving backup algorithm
memoryefficientbackup
for incremental backups when used with the
“Memoryefficientbackup” on page 434
incremental command.
Use the mode option with these commands,
mode
as follows:
“Mode” on page 435
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 selective
or incremental backup of VMware
systems.

Specifies whether you want to monitor an

monitor
image backup of file systems that belong to a
“Monitor” on page 438
Network Attached Storage (NAS) file server.
Suppresses the confirmation prompt that is
noprompt
presented by the delete group, delete
“Noprompt” on page 443
archive, expire, and set event
commands.
Suppresses the confirmation prompt that is
noprompt
presented by the delete group, delete
“Noprompt” on page 443
archive, expire, restore image, and
set event commands.
Use this option with the incremental
nojournal
command to specify that you want to perform
“Nojournal” on page 443
the traditional full incremental backup,
instead of the default journal-based backup.
Specifies the client user-options file that you
optfile
want to use when you start a backup-archive
“Optfile” on page 447
client session.

286 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 58. Backup and archive processing options (continued)
Option Description
During a snapshot-based backup, this option
postsnapshotcmd
allows you to manually open an application
“Postsnapshotcmd” on page 455
after the snapshot is created. This option is
valid only for AIX JFS2 or Linux LVM
snapshot-based operations.
Use this option during a backup or archive
preservelastaccessdate
operation to specify whether to reset the last
“Preservelastaccessdate” on page 457
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.
During a snapshot-based backup operation,
presnapshotcmd
this option allows you to manually quiesce an
“Presnapshotcmd” on page 461
application before the snapshot is created.
This option is valid only for AIX JFS2 or Linux
LVM snapshot-based operations.
Specifies that the client removes the 20-
removeoperandlimit
operand limit. If you specify the
“Removeoperandlimit” on page 466
removeoperandlimit option with the
incremental, selective, archive, or
backup image command, the 20-operand
limit is not enforced and is restricted only by
available resources or other operating
system limits.
Specifies whether to skip ACL processing
skipacl
completely.
“Skipacl” on page 493

Specifies whether to perform checksum and

skipaclupdatecheck
size comparisons before and after backup
“Skipaclupdatecheck” on page 494
and during incremental processing.
Specifies an incremental backup of the files
snapdiff
reported as changed by NetApp, instead of
“Snapdiff” on page 494
scanning the volume and looking for files that
have changed. Use this option with a NAS full
volume incremental backup.
Linux and AIX only: Use this option to specify
snapshotcachesize
an appropriate snapshot size so that all
“Snapshotcachesize” on page 502
original data blocks can be stored during file
modification and deletion. A snapshot size of
100 percent ensures a valid snapshot. The
default value is 100 percent.

Chapter 10. Processing options 287

 Table 58. Backup and archive processing options (continued)
Option Description
Use the snapshotproviderfs option to
snapshotproviderfs
enable snapshot-based file backup and
“Snapshotproviderfs” on page 503
archive operations, and to specify a snapshot
provider. You must be a root user to perform
a snapshot-based file backup or archive
operation. If you are not a root user, the
operation fails with an error message.
Use the snapshotproviderimage option
snapshotproviderimage
to enable snapshot-based image backup, and
“Snapshotproviderimage” on page 504
to specify a snapshot provider. You must be a
root user to perform a snapshot-based image
backup operation. If you are not a root user,
the operation fails with an error message.
Use the snapshotroot option with the
snapshotroot
incremental, selective, or archive
“Snapshotroot” on page 504
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. This option is valid for all
UNIX and Linux clients.
Specifies whether to include subdirectories
subdir
of a named directory.
“Subdir” on page 515

Specifies whether you want the client to wait

tapeprompt
for a tape mount if it is required for a backup,
“Tapeprompt” on page 520
archive, restore, or retrieve process, or to be
prompted for a choice.
Use the toc option with the backup nas
toc
command or the include.fs.nas option to
“Toc” on page 531
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.
Use the type option with the query node
type
command to specify the type of node to
“Type” on page 534
query.
Use the v2archive option with the
v2archive
archive command to archive only files to
“V2archive” on page 537
the server. The client does not process
directories that exist in the path of the source
file specification.

288 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 58. Backup and archive processing options (continued)
Option Description
Use this option with the backup group
virtualfsname
command to specify the name of the
“Virtualfsname” on page 539
container for the group on which you want to
(does not apply to Mac OS X)
perform the operation.
Defines a virtual mount point for a file system
virtualmountpoint
if you want to consider files for backup that
“Virtualmountpoint” on page 539
begin with a specific directory within that file
system.
Used with the backup VM, restore VM, or
vmchost
query VM commands to specify the host
“Vmchost” on page 545
name of the VMware VirtualCenter or ESX
server where the commands are directed.
Used with the backup VM, restore VM, or
vmcpw
query VM commands to specify the
“Vmcpw” on page 546
password of the VirtualCenter or ESX user
that is specified with the vmcuser option.
Used with the backup VM, restore VM, or
vmcuser
query VM commands to specify the user
“Vmcuser” on page 548
name for the VMware VirtualCenter or ESX
server where the commands are directed.
Used with the backup VM command to
vmmaxvirtualdisks
specify the maximum size of the VMware
“Vmmaxvirtualdisks” on page 563
virtual machine disks (VMDKs) to include in a
backup operation.
Used with the backup VM command to
vmskipmaxvirtualdisks
specify how the backup operation processes
“Vmskipmaxvirtualdisks” on page 570
VMware virtual machine disks (VMDKs) that
exceed the maximum disk size. In V7.1.3 and
earlier, the vmskipmaxvirtualdisks
option was named vmskipmaxvmdks.

Restore and retrieve processing options

You can use client options to control some aspects of restore and retrieve processing.
Table 59 on page 289 lists the restore and retrieve processing options that are available.

Table 59. Restore and retrieve processing options

Option Description
dirsonly “Dirsonly” on page 346 Qualifies the operation (backup, archive, restore, retrieve)
to process directories alone.
disablenqr “Disablenqr” on page 347 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 387 Specifies a file that contains a list of files to be processed
by the specified command.

Chapter 10. Processing options 289

 Table 59. Restore and retrieve processing options (continued)
Option Description
filesonly “Filesonly” on page 390 Qualifies the operation (backup, archive, restore, retrieve)
to process files alone.
followsymbolic “Followsymbolic” on Specifies whether you want to restore files to symbolic
page 391 links or use a symbolic link as a virtual mount point.
fromdate “Fromdate” on page 393 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 394 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.
fromowner “Fromowner” on page 395 Displays file spaces for an alternative owner. Also specifies
an alternative owner from which to restore or retrieve files.
fromtime “Fromtime” on page 395 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 399 Replaces an existing file with the latest backup version
only if the backup version is newer than the existing file.
imagetofile “Imagetofile” on page 401 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. This option is valid for AIX, Linux, and Solaris
clients.
inactive “Inactive” on page 401 Displays a list of active and inactive files when used with
the pick option.
latest “Latest” on page 427 Restores the most recent backup version of a file whether
it is active or inactive.
localbackupset “Localbackupset” on Specifies whether the backup-archive client GUI bypasses
page 428 initial logon with the server to restore a local backup set on
a stand-alone workstation.
makesparsefile “Makesparsefile” on Use the makesparsefile option with the restore or
page 429 retrieve commands to specify how sparse files are re-
created.
(does not apply to Mac OS X)

monitor “Monitor” on page 438 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 443 suppresses the confirmation prompt that is presented by
the delete group, delete archive, expire, and set
event commands.

290 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 59. Restore and retrieve processing options (continued)
Option Description
noprompt “Noprompt” on page 443 suppresses the confirmation prompt that is presented by
the delete group, delete archive, expire,
restore image, and set event commands.
optfile “Optfile” on page 447 Specifies the client user-options file that you want to use
when you start a backup-archive client session.
pick “Pick” on page 451 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 452 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 453 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 Specifies how much of the source path to reproduce as
458 part of the target directory path when you restore or
retrieve files to a new location.
replace “Replace” on page 466 Specifies whether to overwrite an existing file, or to prompt
you for your selection when you restore or retrieve files.
showmembers “Showmembers” on page Displays all members of a group.
493 (does not apply to Mac OS X)
subdir “Subdir” on page 515 Specifies whether you want to include subdirectories of a
named directory.
tapeprompt “Tapeprompt” on page 520 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.0387
todate “Todate” on page 532 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 532 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 534 Use the type option with the query node command to
specify the type of node to query.
verifyimage “Verifyimage” on page 539 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.

Chapter 10. Processing options 291

 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 IBM Spectrum Protect HSM for Windows .
• Checkreparsecontent
• Restorecheckstubaccess
• Restoremigstate
• 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 IBM Spectrum Protect for Space Management .
• Restoremigstate
• Skipmigrated

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 60 on page 292 lists the scheduling options that are available.

Table 60. Scheduling options

Option Description
cadlistenonport “Cadlistenonport” on page Specifies whether to open listening ports for the
320 client acceptor when the client acceptor is used to
manage schedules in polling mode.
managedservices “Managedservices” on page Specifies whether the client acceptor manages the
430 web client, the scheduler, or both.
maxcmdretries “Maxcmdretries” on page 431 Specifies the maximum number of times the client
scheduler attempts to process a scheduled
command that fails.
postschedulecmd/postnschedulecmd Specifies a command to process after running a
“Postschedulecmd/Postnschedulecmd” on page schedule.
453
preschedulecmd/prenschedulecmd Specifies a command to process before running a
“Preschedulecmd/Prenschedulecmd” on page 456 schedule.
queryschedperiod “Queryschedperiod” on page Specifies the number of hours the client scheduler
462 waits between attempts to contact the server for
scheduled work.
retryperiod “Retryperiod” on page 477 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.
schedcmddisabled “Schedcmddisabled” on Specifies whether to disable the scheduling of
page 479 generic commands specified by your IBM Spectrum
Protect administrator.

292 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 60. Scheduling options (continued)
Option Description
schedcmduser (server defined only) “Scheduler The scheduler executes commands under a uid of
options for commands” on page 260 0, however, there might be some users who have a
different user ID. In this case, your IBM Spectrum
Protect administrator can define schedules and
allow these schedules to be executed under a uid
other than 0, using this option. The IBM Spectrum
Protect Client API does not support this option.
schedlogmax “Schedlogmax” on page 481 Specifies the maximum size of the scheduler log
and web client log, in megabytes.
schedlogname “Schedlogname” on page 482 Specifies the path and file name where you want to
store schedule log information.
schedlogretention “Schedlogretention” on Specifies the number of days to keep log file
page 483 entries in the schedule log and the web client log,
and whether to save pruned entries.
schedmode “Schedmode” on page 485 Specifies which schedule mode to use, polling or
prompted.
schedrestretrdisabled Specifies whether to prevent the IBM Spectrum
“Schedrestretrdisabled” on page 486 Protect Server administrator from executing
restore or retrieve schedule operations.
sessioninitiation “Sessioninitiation” on page Use the sessioninitiation option to control
490 whether the server or client initiates sessions
through a firewall. The default is that the client can
initiate sessions.
srvprepostscheddisabled Specifies whether to prevent the IBM Spectrum
“Srvprepostscheddisabled” on page 507 Protect Server administrator from executing pre-
schedule and post-schedule commands when
performing scheduled operations.
srvprepostsnapdisabled Specifies whether to prevent the IBM Spectrum
“Srvprepostsnapdisabled” on page 508 Protect Server administrator from executing pre-
snapshot and post-snapshot commands when
performing scheduled image snapshot backup
operations.
tcpclientaddress “Tcpclientaddress” on page Specifies a TCP/IP address if your client node has
524 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 485) for details.
tcpclientport “Tcpclientport” on page 524 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 485)
for details.

Chapter 10. Processing options 293

Format and language options
Format and language options allow you to select different formats for date, time and numbers for
different languages.
Format options allow you to select different formats for date, time, and numbers.

Table 61. Format and language options

Option Description
dateformat “Dateformat” on Specifies the format for displaying dates.
page 334
numberformat “Numberformat” Specifies the format for displaying numbers.
on page 445
timeformat “Timeformat” on Specifies the format for displaying time.
page 528

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.

Table 62. Command processing options

Option Description
quiet “Quiet” on page 464 Limits the number of messages that are displayed on your screen
during processing. This option can be overridden by the server.
scrolllines “Scrolllines” on Specifies the number of lines of information that are displayed on
page 487 your screen at one time. Use this option only when scrollprompt
is set to yes.
scrollprompt “Scrollprompt” on Specifies whether you want the backup-archive client to stop and
page 488 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 Specifies whether to display the IBM Spectrum Protect server name
and host server name in the title of the administrative client
“Setwindowtitle” on page 491 command window.

verbose “Verbose” on page 538 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 63 on page 295 lists the authorization options that are available.

294 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 63. Authorization options
Option Description

autodeploy“Autodeploy” on page Specifies whether you want to enable or disable an automatic

314 deployment of the client if a restart is required.

groups “Groups (deprecated)” on Specifies the groups on your workstation that you want to
page 396 authorize to request IBM Spectrum Protect services from the
server.
password “Password” on page 447 Specifies the IBM Spectrum Protect password.
passwordaccess Specifies whether you want to use a generated password or be
“Passwordaccess” on page 449 prompted for a password each time you start the client.

passworddir “Passworddir” on Specifies the directory in which you want to store the
page 450 automatically generated password for your client node. The
encryption key and password are encrypted and stored in the
TSM.sth file.
revokeremoteaccess Restricts an administrator with client access privileges from
“Revokeremoteaccess” on page 478 accessing your workstation through the web client.
users “Users (deprecated)” on Authorizes specific users on your workstation to request services
page 537 from a server.

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 64 on page 295 lists the error processing options that are available.

Table 64. Error processing options

Option Description
errorlogmax “Errorlogmax” on Specifies the maximum size of the error log, in megabytes.
page 371
errorlogname “Errorlogname” Specifies the fully qualified path and file name of the file where you
on page 372 want to store information about errors that occur during processing.
errorlogretention Specifies how many days to maintain error log entries before
“Errorlogretention” on page 373 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 65 on page 296 lists the transaction processing options that are available.

Chapter 10. Processing options 295

 Table 65. Transaction processing options
Option Description
collocatebyfilespec Specifies that you want the backup-archive client to use only one
“Collocatebyfilespec” on page server session to send objects generated from one file specification.
322 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 Specifies the maximum number of minutes you want the client to try
“Commrestartduration” on page to reconnect to the IBM Spectrum Protect server after a
324 communication error occurs.
commrestartinterval Specifies the number of seconds you want the client to wait between
“Commrestartinterval” on page attempts to reconnect to the IBM Spectrum Protect server after a
325 communication error occurs.
diskbuffsize “Diskbuffsize” Specifies the maximum disk I/O buffer size (in kilobytes) that the
on page 347 client can use when reading files.
largecommbuffers This option has been replaced by the diskbuffsize option. At this
“Diskbuffsize” on page 347 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.

nfstimeout “Nfstimeout” on Specifies the number of seconds the server waits for a status system
page 441 call on an NFS file system before it times out.
resourceutilization Use the resourceutilization option in your dsm.sys file to
“Resourceutilization” on page regulate the level of resources the IBM Spectrum Protect server and
475 client can use during processing.
txnbytelimit “Txnbytelimit” Specifies the number of kilobytes the client program buffers before it
on page 533 sends a transaction to the server.

Web client options

Several backup-archive client options are used to configure the IBM Spectrum Protect web client.
Table 66 on page 296 lists the web client options that are available.

Table 66. Web client options

Option Description
httpport “Httpport” on page 397 Specifies a TCP/IP port address for the web client.
managedservices Specifies whether the client acceptor daemon manages the web
“Managedservices” on page 430 client, the scheduler, or both.
revokeremoteaccess Restricts administrator access on a client workstation through
“Revokeremoteaccess” on page 478 the web client.

296 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 66. Web client options (continued)
Option Description
webports “Webports” on page 582 Enables the use of the web client outside a firewall by specifying
the TCP/IP port number used by the client acceptor daemon 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 67 on page 297 lists the diagnostics options that are available.

Table 67. Diagnostics options

Option Description
console “Console” on page 328 Use the console option with the query systeminfo
command to output system information to the console.
filename “Filename” on page 389 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 658
Use the query systeminfo command to gather information and output this information to a file or the
console.

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.
You can override some of the options in your dsm.sys file or client user-options file (dsm.opt) 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.
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 68 on page 299.

Chapter 10. Processing options 297

Entering options with a command
You must follow the general rules for entering options with a command.
• 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="year end 1999" /home/

• 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 (").
• 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.
• Enter options before or after command parameters. For example, you can enter the option before or
after a file specification:

dsmc selective -subdir=yes "/home/devel/proj1/*"

dsmc selective "/home/devel/proj1/*" -subdir=yes

• When you enter several options on a command, separate them with a blank space.
• Enclose the value in quotation marks (" ") if the option value that you enter contains a blank space. For
example:

dsmc archive -description="Project A" "/home/devel/proj1/*"

• 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.
• On AIX, Solaris, Linux on z, and Mac: The maximum number of characters for a file name is 255. The
maximum combined length of the file name and path name is 1024 characters. The Unicode
representation of a character can occupy several bytes, so the maximum number of characters that a
file name might contain can vary.
• On Linux: The maximum length for a file name is 255 bytes. The maximum combined length of both the
file name and path name is 4096 bytes. This length matches the PATH_MAX that is supported by the
operating system. The Unicode representation of a character can occupy several bytes, so the
maximum number of characters that comprises a path and file name can vary. The actual limitation is
the number of bytes in the path and file components, which might or might not correspond to an equal
number of characters.
On Linux: For archive or retrieve operations, the maximum length that you can specify for a path and file
name (combined) remains at 1024 bytes.
• For Mac OS X, the maximum length of a file name is limited to 504 bytes (not characters). The Unicode
representation of a character can occupy several bytes, so the maximum number of characters that a
file name contains can vary.
Table 68 on page 299 lists client command options that you can enter only on the command line with
specific commands.

298 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 68. Client command options
Command option Description Commands
archmc “Archmc” on Use the archmc option with the archive command to archive
page 308 specify the available management class for your policy
domain to which you want to bind your archived files.
class “Class” on page Specifies whether to display a list of NAS objects or query backup
321 client objects when you use the following commands. delete filespace
query filespace

console “Console” on Use the console option with the query systeminfo query systeminfo
page 328 command to output system information to the console.
deletefiles Deletes the local copy of files from your workstation archive
“Deletefiles” on page 340 after they are archived on the server.
deletefiles Deletes the local copy of files from your workstation archive
“Deletefiles” on page 340 after they are archived on the server. Can also be used restore image
with the restore image command and the
incremental option to delete files from the restored
image that are deleted from the file space after the
image is created.
description Assigns or specifies a description for files when archive
“Description” on page archive, delete, retrieve, or query archive operations delete archive
341 are performed. query archive
query backupset
retrieve

detail “Detail” on page Displays management class, file space, backup, and delete filespace
342 archive information, depending on the command with query archive
which it is used. query backup
query filespace
query mgmtclass

dirsonly “Dirsonly” on Backs up, restores, archives, retrieves, or queries archive

page 346 directories only. incremental
query archive
query backup
restore
restore backupset
retrieve
selective

dynamicimage Performs a dynamic image backup. backup image

“Dynamicimage” on page
362

Chapter 10. Processing options 299

Table 68. Client command options (continued)
Command option Description Commands
filelist “Filelist” on Specifies a list of files to be processed for the archive
page 387 command. The backup-archive client opens the backup group
designated file list and processes the files that are delete archive
listed within according to the command. delete backup
expire
incremental
query archive
query backup
restore
retrieve
selective

filename “Filename” on Use the filename option with the query query systeminfo
page 389 systeminfo command to specify a file name in which
to store the system information.
filesonly “Filesonly” Backs up, restores, retrieves, or queries files only. archive
on page 390 incremental
query archive
query backup
restore
restore backupset
retrieve
selective

fromdate “Fromdate” on Use the fromdate option with the fromtime option to delete backup
page 393 specify a date and time from which you want to search query archive
for backups or archives during a restore, retrieve, or query backup
query operation. restore
restore group
retrieve

fromnode “Fromnode” Permits one node to perform commands for another query archive
on page 394 node. A user on another node must use the set query backup
access command to permit you to query, restore, or query filespace
retrieve files or images for the other node. query group
query image
query mgmtclass
restore
restore group
restore image
retrieve

fromowner Displays file spaces for another owner. Also specifies query archive
“Fromowner” on page another owner from which to restore or retrieve files. query backup
395 query group
query image
restore
restore group
restore image
retrieve

300 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 68. Client command options (continued)
Command option Description Commands
fromtime “Fromtime” on Specifies a beginning time on the specified date. Use query archive
page 395 with the fromdate option. This option is ignored if the query backup
fromdate option is absent. restore
restore group
retrieve

groupname Specifies the fully qualified name for a group. backup group
“Groupname” on page
396
ifnewer “Ifnewer” on Replaces existing files with the latest backup version restore
page 399 only if the backup version is newer than the existing restore backupset
version. restore group
retrieve

imagetofile Use the imagetofile option with the restore restore image
“Imagetofile” on page image command to specify that you want to restore
401 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.
This option is valid for AIX, Linux, and Oracle Solaris
clients.

inactive “Inactive” on Displays a list of active and inactive files when used delete group
page 401 with the pick option. query backup
query group
query image
query nas
restore
restore group
restore image
restore nas

incrbydate Requests an incremental backup by date. incremental

“Incrbydate” on page 420
incremental Applies changes to the base image by using restore image
“Incremental” on page information from incremental backups that are made
421 after the original image backup.
This option is valid only for AIX, Linux x86_64, Linux on
POWER, and Oracle Solaris clients.

latest “Latest” on page Restores the most recent backup version of a file restore
427 whether it is active or inactive. restore group

Chapter 10. Processing options 301

Table 68. Client command options (continued)
Command option Description Commands
mode “Mode” on page Use the mode option with these commands, as follows: backup group
435 backup image backup nas
To specify whether to perform a selective or backup image
incremental image backup of client file systems. 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 Specifies whether you want to monitor an image backup nas
page 438 backup or restore of one or more file systems that restore nas
belong to a network-attached storage (NAS) file server.
Specifies whether you want to monitor a restore of one
or more file systems that belong to a network-attached
storage (NAS) file server.

nojournal “Nojournal” Use this option with the incremental command to incremental
on page 443 specify that you want to perform the traditional full
incremental backup, instead of the default journal-
based backup.
noprompt “Noprompt” Suppresses the confirmation prompt that is presented delete archive
on page 443 by the delete group, delete archive, expire, delete backup
and set event commands. delete group
expire

noprompt “Noprompt” Suppresses the confirmation prompt that is presented delete archive
on page 443 by the delete group, delete archive, expire, delete backup
restore image, and set event commands. delete group
expire
restore image

optfile “Optfile” on Specifies the client user-options file that you want to dsmc
page 447 use when you start a backup-archive client session.
pick “Pick” on page 451 Creates a list of backup versions, images, or archive delete archive
copies that match the file specification you enter. From delete group
the list, you can select the versions to process. Include expire
the inactive option to view both active and inactive query nas
objects. restore
restore group
restore image
restore nas
retrieve

302 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 68. Client command options (continued)
Command option Description Commands
pitdate “Pitdate” on Use the pitdate option with the pittime option to query backup
page 452 establish a point in time for which you want to display query group
or restore the latest version of your backups. query image
query nas
restore
restore group
restore image
restore nas

pittime “Pittime” on Use the pittime option with the pitdate option to query backup
page 453 establish a point in time for which you want to display query image
or restore the latest version of your backups. query nas
restore
restore image
restore nas

preservepath Specifies how much of the source path to reproduce as restore

“Preservepath” on page part of the target directory path when you restore or restore backupset
458 retrieve files to a new location. restore group
retrieve

removeoperandlimit Specifies that IBM Spectrum Protect removes the 20- incremental
“Removeoperandlimit” on operand limit. If you specify the selective
page 466 removeoperandlimit option with the archive
incremental, selective, archive, or backup backup image
image command, the 20-operand limit is not enforced
and is restricted only by available resources or other
operating system limits.
showmembers Displays all members of a group. query group
“Showmembers” on page restore group
493
todate “Todate” on page Use the todate option with the totime option to query archive
532 specify an ending date and time to which you want to query backup
search for backups or archives during a restore, restore
retrieve, or query operation. restore group
retrieve

totime “Totime” on Use the totime option with the todate option to query archive
page 532 specify an ending date and time to which you want to query backup
search for backups or archives during a restore, restore
retrieve, or query operation. restore group
retrieve

type “Type” on page 534 Use the type option with the query node command query node
to specify the type of node to query.
v2archive “V2archive” Use the v2archive option with the archive archive
on page 537 command to archive only files to the server. The client
will not process directories that exist in the path of the
source file specification.

Chapter 10. Processing options 303

Table 68. Client command options (continued)
Command option Description Commands
verifyimage Use the verifyimage option with the restore restore image
“Verifyimage” on page image command to specify that you want to enable
539 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 AIX, Linux, and Oracle Solaris
clients.

virtualfsname Specifies the name of the virtual file space for the backup group
“Virtualfsname” on page group on which you want to run the operation.
539

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 69 on page 304 lists the options that are valid only on the initial command line.

Table 69. Options that are valid on the initial command line only
Options valid on the initial command line

commmethod preschedulecmd/prenschedulecmd (can be

deduplication included in the schedule definition)
diskbuffsize queryschedperiod
editor resourceutilization
enablededupcache retryperiod
enablelanfree schedlogmax
errorlogmax schedlogname
errorlogname schedlogretention
errorlogretention schedmode
lanfreecommmethod servername
lanfreeshmport sessioninitiation
lanfreetcpport setwindowtitle
maxcmdretries tcpbuffsize
nfstimeout tcpcadaddress
nodename tcpclientaddress
optfile tcpclientport
password tcpwindowsize
postschedulecmd/postnschedulecmd (can txnbytelimit
be included in the schedule definition) virtualnodename

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 70 on page 305 lists the options that can be set by the server.

304 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 70. Options that can be set by the IBM Spectrum Protect server
Options that can be set by the IBM Spectrum
Protect server

• “Afmskipuncachedfiles” on page 307 • “Queryschedperiod” on page 462

• “Archsymlinkasfile” on page 308 • “Quiet” on page 464
• “Changingretries” on page 321 • “Resourceutilization” on page 475
• “Collocatebyfilespec” on page 322 • “Retryperiod” on page 477
• “Compressalways” on page 325 • “Schedmode” on page 485
• “Compression” on page 326 • “Scrolllines” on page 487
• “Deduplication” on page 338 • “Scrollprompt” on page 488
• “Dirmc” on page 345 • “Snapshotcachesize” on page 502
• “Disablenqr” on page 347 • “Snapshotproviderfs” on page 503
• “Diskcachelocation” on page 348 • “Snapshotproviderimage” on page 504
• “Domain” on page 349 • “Stagingdirectory” on page 514
• “Domain.image” on page 353 • “Subdir” on page 515
• “Domain.nas” on page 354 • “Tapeprompt” on page 520
• “Encryptiontype” on page 368 • “Txnbytelimit” on page 533
• “Encryptkey” on page 369 • “Verbose” on page 538
• “Exclude options” on page 374 • “Vmchost” on page 545
• “Inclexcl” on page 402 • “Vmcuser” on page 548
• “Include options” on page 403 • “Vmprocessvmwithindependent” on page 568
• maxcandprocs • “Vmprocessvmwithprdm” on page 569
• maxmigrators
• “Memoryefficientbackup” on page 434
• “Nfstimeout” on page 441
• “Postschedulecmd/Postnschedulecmd” on page
453
• “Postsnapshotcmd” on page 455
• “Preschedulecmd/Prenschedulecmd” on page
456
• “Preservelastaccessdate” on page 457
• “Presnapshotcmd” on page 461

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

Chapter 10. Processing options 305

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:
• A description
• A syntax diagram
• Detailed descriptions of the parameters
• Examples of using the option in the client options file (if applicable)
• 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.
Note:
1. Do not enclose an option value with single or quotation marks, unless the value is a file specification
that contains spaces or wildcard characters. For example, the following option is not valid:

passwordaccess "generate"

2. All options in the dsm.sys file, except for the defaultserver option, must be placed within a server
stanza. A server stanza is a collection of options statements in dsm.sys that begins with a
SERVERName option and ends either at the next SERVERName option or the end of the file.

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:
• Backups consume more server storage and database resources.
• Backups consume more network bandwidth.
• 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:
• Full or partial progressive incremental backups of file systems or disk drives.
• 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.
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.

306 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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.

Syntax
ABSolute

Parameters
There are no parameters for this option.

Examples
Command line:

dsmc incr -absolute "/Users/sparky/source/*.c"

Afmskipuncachedfiles
The afmskipuncachedfiles option specifies whether uncached and dirty files in General Parallel File
System (GPFS) Active File Management file sets are processed for backup, archive, and migration
operations.
GPFS Active File Management and uncached and dirty file states are explained in IBM Spectrum Scale
product information .
Running HSM on GPFS file systems that use Active File Management file sets is explained in Guidance for
integrating IBM Spectrum Scale AFM with IBM Spectrum Protect .
If you back up, archive, or migrate files from a file system that contains Active File Management file sets,
set afmskipuncachedfiles=yes.
Restriction: If Active File Management is running in Local Update (LU) mode, the
afmskipuncachedfiles option in the cache file set must be set to No.

Supported Clients
This option is valid for backup-archive clients that run on AIX and Linux systems.

Options File
Place this option in the dsm.sys file before any server stanzas.

Syntax
NO
AFMSKIPUNCACHEDFILES
YES

Parameters
NO
The Active File Management file state is ignored during backup, archive, and migration operations.
Migration operations on uncached or dirty files fail and yield error message ANS9525E. Backup and
archive operations on uncached files require Active File Management fetch operations. The fetch
operations can cause significant network traffic between the Active File Management home and
cache. This parameter is the default.

Chapter 10. Processing options 307

 YES
Uncached or dirty files in Active File Management file sets are skipped during backup, archive, and
migration processing.

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.
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 UNIX and Linux 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 /Users/van/Documents/budget.jan

dsmc archive –archmc=ret2yrs /home/plan/proj1/budget.jan

Archsymlinkasfile
The archsymlinkasfile option specifies whether the backup-archive client follows a symbolic link and
archives the file or directory to which it points, or archives the symbolic link only. Use this option with the
archive command.

Supported Clients
This option is valid for all UNIX clients except Mac OS X. The server can also define this option.

Options File
Place this option in the client user options file (dsm.opt).

Syntax
Yes
ARCHSYMLinkasfile
No

308 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Parameters
Yes
Specifies that the client follows a symbolic link and archives the associated file or directory. This is the
default.
No
Specifies that the client archives the symbolic link and not the associated file or directory.

Examples
Options file:
archsymlinkasfile no
Command line:
-archsyml=no

Asnodename
Use the asnodename option to allow agent nodes to back up or restore data on behalf of another node
(the target node). This enables concurrent operations from multiple nodes to store data to the same
target node and file space in parallel.
Your client node must be granted access to the target node by the IBM Spectrum Protect server
administrative client grant proxynode command, and you must be a root user to use the asnodename
option.
When the IBM Spectrum Protect administrator grants a node proxy authority, and you use the
asnodename option to become that node, you can query and restore all files as if you had root authority.
An agent node is a client node that has been granted authority to perform client operations on behalf of a
target node.
A target node is a client node that grants authority to one or more agent nodes to perform client
operations on its behalf.
A proxy operation uses the settings for the target node (such as maxnummp and deduplication) and
schedules that are defined on the server. The IBM Spectrum Protect server node settings and schedules
for the agent node are ignored.
For example, you can use the following command to back up shared data for file space stored under the
node name MyCluster:

/cluster1/mydata

dsmc incremental /Users -asnodenodename=MyCluster

You can also use the asnodename option to restore data under another node name on the server. You
can only restore the data that you own.
The asnodename option differs from the nodename option as follows:
• When using the nodename option, you must enter the password for the node name you specify.
• When using the asnodename option, you must enter the password for your client agent node to access
the data stored for the client target node.
Restriction: You cannot use the asnodename option with -fromnode and you cannot perform NAS
backup using asnodename. Also, asnodename can be used for clustered systems, although no specific
cluster software is supported.
Limitation: When you use the asnodename option, for example in an IBM Spectrum Scale cluster
environment, the backup-archive client GUI displays the message "No backups found. Create backups
before using this UI." You must first configure a specific server stanza to be used by the dsmcad
command, for the backup-archive client GUI to use directly with the asnodename option.

Chapter 10. Processing options 309

 Supported Clients
This option is valid for all UNIX and Linux clients.

Options File
Place this option in the dsm.sys file within a server stanza. 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 mycluster
Command line:
-asnodename=mycluster
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.
The following considerations apply to proxy operations.
• 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.
• The agent node authenticates to the IBM Spectrum Protect server by using the agent node's password.
• In order to run proxy operations, the agent node and target node must not be locked on the server.
• 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.

310 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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 Command:

sel /home/spike/test/*
04/21/07 15:25:05 ANS1651I Backed Up:
/home/spike/test/file.txt
04/21/07 15:25:05 ANS1652I Archived:
/home/spike/test/file.txt
04/21/07 15:25:05 ANS1653I Updated:
/home/spike/test/file.txt
04/21/07 15:25:05 ANS1654E Failed:
/home/spike/test/file.txt
04/21/07 15:25:05 ANS1655I Restored:
/home/spike/test/file.txt
04/21/07 15:25:05 ANS1656I Retrieved:
/home/spike/test/file.txt
04/21/07 15:25:05 ANS1657I Expired:
/home/spike/test/file.txt
04/21/07 15:25:05 ANS1658I Deleted:
/home/spike/test/file.txt
04/21/07 15:25:05 ANS1659I Skipped:
/home/spike/test/file.txt

The following messages can be 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):

04/21/07 15:25:05 ANS1660I Excluded:

/home/spike/test/file.txt
04/21/07 15:25:05 ANS1661I Unchanged:
/home/spike/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.
The Mac OS X backup-archive client creates the audit log as a Unicode (UTF-16) 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 supported with backup commands that interact with file-level objects
such as backup groups.

Chapter 10. Processing options 311

 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.
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 client system-options file (dsm.sys) within a server stanza.

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.
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.

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 client system-options file (dsm.sys) within a server stanza.

312 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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.

Examples
Run an incremental backup with audit logging enabled.
Sample output
The following is a sample execution and output file:

> dsmc inc /SMSVT/mfs1 -auditlogging=full

-auditlogname=/home/cliv3/audit.log
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: NAXOS_CLUSTER

Session established with server
ODINHSMSERV: AIX-RS/6000
Server Version 8, Release 1, Level 0.0
Server date/time: 11/16/2016 12:05:35
Last access: 11/15/2016 12:01:57

Incremental backup of volume '/SMSVT/mfs1'

Directory--> 4,096 /SMSVT
/mfs1/ [Sent]
Normal File--> 32,768 /SMSVT
/mfs1/test0 [Sent]
Normal File--> 32,768 /SMSVT
/mfs1/test1 [Sent]
Normal File--> 32,768 /SMSVT
/mfs1/test2 [Sent]
Normal File--> 32,768 /SMSVT
/mfs1/test3 [Sent]
Normal File--> 32,768 /SMSVT
/mfs1/test4 [Sent]
Normal File--> 32,768 /SMSVT
/mfs1/test5 [Sent]
Normal File--> 32,768 /SMSVT
/mfs1/test6 [Sent]
Normal File--> 32,768 /SMSVT
/mfs1/test7 [Sent]
Normal File--> 32,768 /SMSVT
/mfs1/test8 [Sent]
Normal File--> 32,768 /SMSVT
/mfs1/test9 [Sent]
Successful incremental backup of '/SMSVT/mfs1'

Total number of objects inspected: 11

Total number of objects backed up: 11
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: 320.31 KB
Data transfer time: 0.01 sec
Network data transfer rate: 17,141.84 KB/sec
Aggregate data transfer rate: 297.43 KB/sec
Objects compressed by: 0%
Elapsed processing time: 00:00:01

Chapter 10. Processing options 313

 The following are the audit log contents:

07/03/07 12:05:14 ANS1650I Command:

inc /SMSVT/mfs1
07/03/07 12:05:15 ANS1651I Backed Up:
/SMSVT/mfs1/
07/03/07 12:05:15 ANS1651I Backed Up:
/SMSVT/mfs1/test0
07/03/07 12:05:15 ANS1651I Backed Up:
/SMSVT/mfs1/test1
07/03/07 12:05:15 ANS1651I Backed Up:
/SMSVT/mfs1/test2
07/03/07 12:05:15 ANS1651I Backed Up:
/SMSVT/mfs1/test3
07/03/07 12:05:15 ANS1651I Backed Up:
/SMSVT/mfs1/test4
07/03/07 12:05:15 ANS1651I Backed Up:
/SMSVT/mfs1/test5
07/03/07 12:05:15 ANS1651I Backed Up:
/SMSVT/mfs1/test6
07/03/07 12:05:15 ANS1651I Backed Up:
/SMSVT/mfs1/test7
07/03/07 12:05:15 ANS1651I Backed Up:
/SMSVT/mfs1/test8
07/03/07 12:05:15 ANS1651I Backed Up:
/SMSVT/mfs1/test9

Related information
For more information about the audit logging facility refer to “Auditlogging” on page 311.

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 AIX, Linux, Mac, and Solaris 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

Parameters
Yes
Specifies that the client is automatically deployed from the server. Yes is the default.
No
Specifies that the client is not automatically deployed from the server.

Examples
Options file:
autodeploy no
Command line:
Does not apply.

314 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 2
The IBM Spectrum Protect server administrator can automatically deploy a backup-archive client to
update workstations where the backup-archive client is already installed.

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
Jaguar to Jaguar_OLD. If the new file space name is too long, the suffix replaces the last characters of
the file space name. For example, the mylongfilesystemname file space name is renamed to:

mylongfilesystem_OLD

If the new file space name already exists on the server, the server renames the new file space
Jaguar_OLDx, where x is a unique number.
The server creates new Unicode-enabled file spaces that contain only the data specified in the current
operation. For example, assume that Jaguar is the name of your startup disk and you archive all of
the .log files in the /Users/user5/Documents directory. Before the archive takes place, the server
renames the file space to Jaguar_OLD. The archive places the data specified in the current operation
into the Unicode-enabled file space named Jaguar. The new Unicode-enabled file space now contains
only the /Users/user5/logs directory and the *.log files specified in the operation. The server stores
all subsequent full and partial incremental, selective backup, and archive data in the new Unicode-
enabled file spaces.
For example, assume that Jaguar is the name of your startup disk and you archive all of the .log files in
the /Users/user5/Documents directory. Before the archive takes place, the server renames the file
space to Jaguar_OLD. The archive places the data specified in the current operation into the Unicode-
enabled file space named Jaguar. The new Unicode-enabled file space now contains only the /Users/
user5/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.
The server can define the autofsrename option and override the autofsrename setting on the client.

Supported Clients
This option is valid for Mac OS X only. 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.

Chapter 10. Processing options 315

 Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. 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

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:
• This option applies only when the server sets the autofsrename option to client.
• 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.
• 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.
• 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.
• 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

Automount
The automount option adds an automounted file system into the domain by mounting it. Use this option
with the domain option.
Use this option to specify all automounted file systems that the backup-archive client tries to mount at
the following points in time:
• When the client starts
• When the backup is started
• When the the client has reached an automounted file system during backup

316 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Mount the file system before the client does a backup of that file system. If the file system is always
mounted before the backup is done, it is unnecessary to explicitly specify an automounted file system in
the automount option. However, add this file system in the automount option to ensure that the file
system has been mounted at all the points in time mentioned previously. The automounted file systems
are remounted if they have gone offline in the meantime during a backup.

Supported Clients
This option is valid for all UNIX platforms except Mac OS X. The IBM Spectrum Protect API does not
support this option.

Options File
Place this option in the client user options file (dsm.opt).

Syntax

AUTOMount filespacename

Parameters
filespacename
Specifies one or more fully qualified automounted file systems that are mounted and added into the
domain.

Examples
Options file:
automount /home/Fred /home/Sam
Command line:
Does not apply.
Related information
See “Domain” on page 349 for more information about working with automounted file systems and the
domain option.

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 Linux x86_64 clients.

Options File
None. You can specify this option only on the command line or on the scheduler.

Syntax
BACKMc= management_class_name

Chapter 10. Processing options 317

 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:
• query backup
• query filespace
• query image
• 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 UNIX and Linux 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.

Examples
Command line:

dsmc query backup /Volumes/bkSets/file.1

-backupsetname=YEAR_END_ACCOUNTING.12345678

dsmc query backup /usr/projects -subdir=yes

-backupsetname=YEAR_END_ACCOUNTING.12345678

dsmc restore image /home/proj

-backupsetname=ACCOUNTING_2007.12345678

318 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 dsmc query image -backupsetname=WEEKLY_BSET.21435678

Related information
“Restore data from a backup set” on page 216

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 x86_64 Linux 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
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.?"

Chapter 10. Processing options 319

 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 system-options file (dsm.sys) within a server stanza.

Syntax
Yes
CADLISTENONPort
No

Parameters
Yes
Specifies that the client acceptor opens a listening port. This parameter is the default.
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.

320 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Related reference
“Managedservices” on page 430
The managedservices option specifies whether the IBM Spectrum Protect client acceptor service
manages the scheduler, the web client, or both.
“Schedmode” on page 485
The schedmode option specifies whether you want to use the polling mode (your client node
periodically queries the server for scheduled work), or the prompted mode (the server contacts your
client node when it is time to start a scheduled operation).

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.

Supported Clients
This option is valid for all UNIX and Linux 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 system-options file (dsm.sys) within a server stanza. You can set this option
on the Backup tab, Number of retries if file is in use field of the Preferences editor.

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

Chapter 10. Processing options 321

 Supported Clients
This option is valid only for AIX, Linux, and Oracle Solaris 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

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:
• 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 UNIX and Linux clients. The server can also define this option.

Options File
Place this option in the client user-options file (dsm.opt).

Syntax
No
COLlocatebyfilespec
Yes

322 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 system-options file (dsm.sys) within a server stanza. You can set this option
on the Communication tab of the Preferences editor.

Syntax
TCPip
COMMMethod
SHAREdmem

V6TCPIP

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.
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.
This option is valid for AIX, Linux, and Oracle Solaris clients.

Chapter 10. Processing options 323

 When specifying this communication method on AIX, the client can be logged in as root or non-root,
as long as the server is running as root. If the server is not running as root, the user ID running the
client must match the user ID running the server.
Important: When using commmethod sharedmem on Linux, you might receive error message:
ANR8294W Shared Memory Session unable to initialize on the server or storage agent
console. By default, Linux is not set up with sufficient system resources to create the message
queues. You must increase the kernel parameter, MSGMNI, to 128 (the default is 16). You can modify
this parameter by performing the following command:

echo 128 > /proc/sys/kernel/msgmni

To enable this parameter to remain persistent after rebooting the system, you can instead add the
following line to the file /etc/sysctl.conf, then reboot the system:

kernel.msgmni=128

To view the current ipc settings, run this command:

ipcs -l

Now look at the max queues system wide value. The default is 16.

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.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the Communication tab, Common Options section of the Preferences editor.

324 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 system-options file (dsm.sys) within a server stanza. 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 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.

Chapter 10. Processing options 325

 Supported Clients
This option is valid for all clients. The server can also define this option.

Options File
Place this option in the client user-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.

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.sys 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:
• Use the exclude.compression option in your client system-options file (dsm.sys) to exclude specific
files or groups of files from compression processing.
• Use the include.compression option in your client system-options file (dsm.sys) 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.

326 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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:
• Client-deduplicated data is sent to traditional (non-container) storage pools on the server.
• 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.)
• 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 dsm.sys file within a server stanza. 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.

Chapter 10. Processing options 327

 Related reference
“Deduplication” on page 338
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.
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.
“Include options” on page 403
The include options specify objects that you want to include for backup and archive services.

Console
Use the console option with the query systeminfo command to output information to the console.
• DSMOPTFILE - The contents of the dsm.opt file.
• DSMSYSFILE - The contents of the dsm.sys file.
• ENV - Environment variables.
• ERRORLOG - The IBM Spectrum Protect error log file.
• FILE - Attributes for the file name that you specify.
• INCLEXCL - Compiles a list of include-exclude in the order in which they are processed during backup
and archive operations.
• OPTIONS - Compiled options.
• OSINFO - Name and version of the client operating system (includes ULIMIT information for UNIX and
Linux).
• POLICY - Policy set dump.
• SCHEDLOG - The contents of the IBM Spectrum Protect schedule log (usually dsmsched.log).
• CLUSTER - AIX 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.

Syntax
CONsole

Parameters
There are no parameters for this option.

Examples
Command line:
query systeminfo dsmoptfile errorlog -console
Related information
“Filename” on page 389

328 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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 494 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:
• Linux x86_64 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 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.

Chapter 10. Processing options 329

 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
Related tasks
“Configuring NetApp and IBM Spectrum Protect for snapshot difference incremental backups” on page
104
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.
Related reference
“Snapdiff” on page 494
Using the snapdiff (snapshot difference) option with the incremental command streamlines the
incremental backup process. The command runs an incremental backup of the files that were reported as
changed by NetApp instead of scanning all of the volume for changed files.

Csv
The csv option enables the client to use a comma-separated values (csv) file to define and apply different
restore settings across a series of virtual machine restore operations.
In the specified .csv file, you can define column headings with settings that override equivalent client
options. Column names are case-sensitive.
Using a CSV column overrides the equivalent command line option. The equivalent option is ignored if
used with the restore vm -csv command:
• "New Virtual Machine Name" overrides the -vmname option on restore.
• "New Datastore" overrides the -datastore option on restore.
• "New Datacenter" overrides the -datacenter option on restore.
• "New Host" overrides the -host option on restore.
• "PITDATE" overrides the -pitdate option on restore.
• "PITTIME" overrides the -pittime option on restore.

Supported clients
This option can be used with supported x86_64 Linux clients.

330 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Options file
This option is valid in the client system options file (dsm.sys), or on the command line for Restore VM.
It can also be included on the server in a client options set. It cannot be set in the Preferences Editor.

Syntax
Csv csvfilespec

Parameters
csvfilespec
Using a CSV column overrides the equivalent command line option. Any equivalent option is ignored if
it is used with the restore vm -csv command.
For example, if you specify the command restore vm "restore_vm_list.csv" -csv -
datacenter="Mambo 5", and the "New Datacenter" column is already specified in the CSV file, the
-datacenter option is ignored.
The following list shows the CSV columns that override the equivalent client options:

Table 71. Column heading names

Heading Description Usage
Virtual Machine Name The name of the virtual No wildcard characters are allowed.
machine to be restored. Case-sensitive. This column is
mandatory.
New Virtual Machine Name The name of the virtual This column uses the same syntax as
machine that is restored. the -vmname option. Optional. You can
leave this column blank if you want to
reuse the existing name.
New Datastore The new datastore to which This column uses the same syntax as
the virtual hard disks are the -datastore option. Optional. You
restored. can leave this column blank if you want
to reuse the existing datastore.
New Datacenter The new datacenter with Uses the same syntax as the -
which the virtual machine datacenter option. Optional. You can
should be associated. leave this column blank if you want to
reuse the existing datacenter.
New Host The new host to which the This column uses the same syntax as
virtual machine will be the -host option. Optional. You can
restored. leave this column blank if you want to
reuse the existing host.

Chapter 10. Processing options 331

 Table 71. Column heading names (continued)
Heading Description Usage
PITDATE The point-in-time date from This column uses the same syntax as
which the backup is the -pitdate option. Optional. You can
specified. leave this column blank to indicate the
active backup should be restored. This
column is required if PITTIME is
specified in the CSV file. PITDATE
dates should use the format set by the
DATEFORMAT option. The default
varies by locale in Windows. The
default is DATEFORMAT 1 in Linux.
PITTIME The point-in-time time of day This column uses the same syntax as
from which the backup is the -pittime option. Optional. You can
specified. leave this column blank to indicate you
want to use the active backup or if only
the PITDATE is specified. PITTIME
times should use the format set by
TIMEFORMAT option. The default
varies by locale in Windows. The
default is TIMEFORMAT 1 in Linux.

The asterisk, *, denotes reuse of the original VM name as part of a wild-card construct for the name of a
restored VM.
The following command line conventions are also observed:
• <date> is replaced by the date of the restore.
• <time> is replaced by the time of the restore.
• <timestamp> is replaced by a combination of <date> and <time> outputs.
Elements can be placed in quotes: for example, VMs with commas and quotes in their names.

"Poem Repository ""A-F"" 20th Century"

Here, double quotes are used to express a quote (") character.

Examples
The following example shows how a CSV file looks when opened in a spreadsheet view:

Virtual Machine Name New Virtual Machine Name New Host New Datastore New Datacenter NOTES1 NOTES2
PITDATE PITTIME
VM1 *-DR_restore esx4.ibm.com DS_8 DC_RecoverSite1 group1
VM2 *-DR_restore esx4.ibm.com DS_8 DC_RecoverSite1 group1
VM3 *-DR_restore esx4.ibm.com DS_8 DC_RecoverSite1 group1
VM4 *-DR_restore esx5.ibm.com DS_10 DC_RecoverSite1 group2
VM5 *-DR_restore esx5.ibm.com DS_10 DC_RecoverSite1 group2

The following examples show comma-separated text files that were exported from CSV files.
Example 1:

Virtual Machine Name,New Virtual Machine Name,New Host,New Datastore,New

Datacenter,NOTES1,NOTES2,PITDATE,PITTIME
VM1,*-DR_restore,esx4.ibm.com,DS_8,DC_RecoverSite1,group1
VM2,*-DR_restore,esx4.ibm.com,DS_8,DC_RecoverSite1,group1
VM3,*-DR_restore,esx4.ibm.com,DS_8,DC_RecoverSite1,group1
VM4,*-DR_restore,esx5.ibm.com,DS_10,DC_RecoverSite1,group2
VM5,*-DR_restore,esx5.ibm.com,DS_10,DC_RecoverSite1,group2

332 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Example 2:

Virtual Machine Name,New Virtual Machine Name,New Host,New Datastore,New

Datacenter,NOTES1,NOTES2,PITDATE,PITTIME
Tiny Linux VM,Tiny Linux VM -restore,,,,,,,
lucasTestVM10,* -restore,,,,,,10/03/2017,10:35 AM
big-cet-4TB,,devesx06.storage.tucson.ibm.com,,,,10/05/2017,,

Related reference
“Restore VM” on page 681
Use the restore vm command to restore a virtual machine (VM) that was previously backed up.

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

Chapter 10. Processing options 333

Dateformat
The dateformat option specifies the format you want to use to display or enter dates.
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.
• delete archive
• delete backup
• expire
• query archive
• query backup
• query filespace
• query image
• restore
• restore image
• restore nas
• retrieve
• 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 user-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

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:

334 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 0
Use the locale-specified date format (does not apply to Mac OS X).
For AIX and Solaris: This is the default if the locale-specified date format consists of digits and
separator characters.
1
MM/DD/YYYY
For AIX and Solaris: This is the default if the locale-specified date format consists of anything but
digits and separator characters.
This is the default for the following available translations:
• US English
• Chinese (Traditional)
• Korean
2
DD-MM-YYYY
This is the default for the following available translations:
• Brazilian Portuguese
• Italian
3
YYYY-MM-DD
This is the default for the following available translations:
• Japanese
• Chinese (Simplified)
• Polish
4
DD.MM.YYYY
This is the default for the following available translations:
• German
• French
• Spanish
• Czech
• Russian
5
YYYY.MM.DD
This is the default for the following available translations:
• Hungarian
6
YYYY/MM/DD
7
DD/MM/YYYY

Examples
Options file:
dateformat 3

Chapter 10. Processing options 335

 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 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.

Configuring date and time formats in the system locale configuration file
You can specify date and time formats by configuring them in your system’s locale file. If you specify time
and date formats in the locale file, they must be defined by using a subset of number-producing format
specifiers that are supported by the C language strftime() function. You can use the following
specifiers to set date and time formats in configuration settings for your locale.
Date specifiers
• %Y - the year, in four digits. For example, 2011.
• %y - the year, last two digits only. For example, 11 not 2011.
• %m - the month, as a decimal number (1-12).
• %d - the day of the month (1-31).
In the date specifiers, you can specify only one year specifier. Do not specify both %Y and %y. The E
modifier (a capital E) can precede the date specifiers to produce the locale's alternative form for the
year, month, or day. If no alternative form exists, the E modifier is ignored. Separate the specifiers
with a single 7-bit ASCII character. Commonly used separators include colons (:), commas (,), periods
(.), hyphens (-), or forward slash (/) characters. Do not use multibyte characters as separators.
Time specifiers
• %H - the hour, in 24-hour form (00-23).
• %I - the hour, in 12-hour form (00-12).
• %M - minutes after the hour (00-59).
• %S - seconds after the minute (00-59)
• %p - adds the AM (before noon) or PM (after noon) indicator.
In the time specifiers, you can specify only one hour specifier. Do not specify both %I and %H.
The O modifier (a capital O) can precede the time specifiers to produce the locale's alternative form
for the hour, minutes, or seconds. The O modifier cannot precede the %p specifier. Separate the
specifiers with a single 7-bit ASCII character. Commonly used separators include colons (:), commas
(,), or periods (.). Do not use multibyte characters as separators. Do not specify a separator between
the %p specifier and the separator that precedes or follows it.
Time format examples, configured in the locale settings
To set a particular time format, edit the configuration file for your locale and modify the t_fmt line to
support your needs. Whatever time format you select applies both to output and to input. After the
locale configuration file has been edited, the localedef command must be run to create the final
locale file.

336 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 72. Sample time format settings in the locale configuration (t_fmt line)
Example Result
"%H:%M:%S" Displays time in the form hh:mm:ss with hh ranging
from 0 through 23.
"%H,%M,%S" Displays time in the form hh,mm,ss with hh ranging from
0 through 23.
"%I,%M,13p" Displays time in the form hh,mm,ssA/P with hh ranging
from 1 through 12 and A/P is the local abbreviation for
ante-meridian (AM in English) or post-meridian (PM in
English).

Date format examples, configured in the locale settings

To set a particular date format, edit the configuration file and modify the d_fmt line as needed to
support your needs. Whatever date format you select applies both to output and to input.

Table 73. Sample date format settings in the locale configuration (d_fmt line)
Example Result
"%m/%d/%y" Displays the date in the form MM/DD/YY.
"%d.%m.%Y" Displays the date in the form DD.MM.YYYY.

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 system-options file (dsm.sys). You can set this option on the Deduplication
Cache Location field 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.

Examples
Options file:
dedupcachepath /volumes/temp
Command line:
Does not apply.

Chapter 10. Processing options 337

 Related reference
“Enablededupcache” on page 365
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.

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.

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 system-options file (dsm.sys). 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 the 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” on page 338
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.

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:
• Client-side data deduplication for the node is enabled on the server.
• 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".
• A file can be excluded from client-side data deduplication processing (by default all files are included).

338 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • 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.
• The file size must be larger than 2 KB.

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 system-options file (dsm.sys) within a server stanza. 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 the 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 403
The include options specify objects that you want to include for backup and archive services.
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.

Defaultserver
Use the defaultserver option to specify the name of the IBM Spectrum Protect server to contact for
backup-archive services if more than one server is defined in the dsm.sys file.
By default, the backup-archive contacts the server defined by the first stanza in the dsm.sys file. This
option is only used if the servername option is not specified in the client user-options file (dsm.opt).
If you have the HSM client installed on your workstation, and you do not specify a migration server with
the migrateserver option, use this option to specify the server to which you want to migrate files. For
more information, see the IBM Spectrum Protect for Space Management product documentation on IBM
Knowledge Center at http://www.ibm.com/support/knowledgecenter/SSERBH/welcome.

Chapter 10. Processing options 339

 Supported Clients
This option is valid for all UNIX clients.

Options File
Place this option at the beginning of the dsm.sys file before any server stanzas.

Syntax
DEFAULTServer servername

Parameters
servername
Specifies the name of the default server to which you back up or archive files. The server to which files
are migrated from your local file systems can also be specified with this option.

Examples
Options file:
defaults server_a
Command line:
Does not apply.

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.

Syntax
DELetefiles

Parameters
There are no parameters for this option.

Examples
Command line:

dsmc archive "/Users/dgordon/Documents/*.c" –deletefiles

dsmc archive "/home/foo/*.c" –deletefiles

dsmc restore image /local/data -incremental -deletefiles

340 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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" /home/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:
• archive
• delete archive
• query archive
• query backupset
• 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 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" "/Users/van/Documents/*.x"

dsmc archive –description="Project X" "/home/allproj/.*"

You can then use the description to retrieve all of the files.

Chapter 10. Processing options 341

 Examples
Command line:

dsmc archive "/Users/van/Documents/*.prj" -des="2003 Budget for Proj 1"

dsmc archive "/home/foo/*.prj" –des="2003 Budget for Proj 1"

dsmc query backupset –loc=server –descr="My Laptop"

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
GUI.
Use the detail option with the query backup and query archive commands to display these
attributes of the file that you specify:
• Last modification date
• Last access date
• Compression
• Encryption type
• Client-side data deduplication
• Whether the HSM client migrated or premigrated the file
Use the detail with the query vm command to display the following statistics:
• The average number of IBM Spectrum Protect objects that are needed to describe a single megablock,
across all megablocks in a backup.
• The average number of IBM Spectrum Protect objects that are needed to describe a single megablock,
for all megablocks in a filespace.
• 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.
• 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.
• 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:
• delete filespace
• incremental
• query archive
• query backup
• query filespace

342 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • query inclexcl
• query mgmtclass
• 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 vm -detail

Diffsnapshot
The diffsnapshot option controls whether the backup-archive client creates the differential snapshot
when it runs a snapshot difference incremental backup.
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 with this or any other method.
Snapshots that are created by methods outside of IBM Spectrum Protect are never deleted by the client.

Supported Clients
This option is valid for Linux x86_64 clients.

Syntax
create
DIFFSNAPSHOT
latest

Chapter 10. Processing options 343

 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 snapshot difference incremental backup of an NFS mounted file system /vol/vol1 hosted
on the file server homestore.example.com, where /net/home1 is the mount point of /vol/vol1.
incremental -snapdiff -diffsnapshot=latest /net/home1
The -diffsnapshot option value of latest means that the operation uses the latest snapshot (the
active snapshot).
Related concepts
“Snapshot differential backup with an HTTPS connection” on page 163
You can use a secure HTTPS connection for the backup-archive client to communicate with a NetApp filer
during a snapshot differential backup.
Related tasks
“Configuring NetApp and IBM Spectrum Protect for snapshot difference incremental backups” on page
104
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.
Related reference
“Snapdiff” on page 494
Using the snapdiff (snapshot difference) option with the incremental command streamlines the
incremental backup process. The command runs an incremental backup of the files that were reported as
changed by NetApp instead of scanning all of the volume for changed files.
“Snapdiffhttps” on page 501
Specify the snapdiffhttps option to use a secure HTTPS connection for communicating with a NetApp
filer during a snapshot differential backup.
“Createnewbase” on page 329
The createnewbase option creates a base snapshot and uses it as a source to run a full incremental
backup.

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 x86_64 Linux clients.

Options File
This option can be specified in the client options file or on the command line.

344 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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
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.

Chapter 10. Processing options 345

 Options File
Place this option in the dsm.sys file within a server stanza. 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.
Related information
If you want to back up specific files to a management class see “Assign a management class to files” on
page 271 for more information.

Dirsonly
The dirsonly option processes directories only. The client does not process files.
Use the dirsonly option with the following commands:
• archive
• incremental
• query archive
• query backup
• restore
• restore backupset
• retrieve
• 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.

346 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Examples
Command line:
dsmc query backup -dirsonly "/Users/*"
Command line:
dsmc query backup -dirsonly "*"

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.

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, or HSM 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.

Chapter 10. Processing options 347

 Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax
DISKBuffsize size

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. For AIX: If enablelanfree no is set, the
default setting for diskbuffsize is 256.

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. For UNIX and Linux, estimate 1 byte per character in the path
name. For Mac OS X, estimate 4 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 200 MB for UNIX and Linux, and 800 MB for Mac OS X clients. 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.
A second disk cache file is created for the list of migrated files when backing up an HSM managed file
system. The combined disk cache files, created by disk cache incremental backups and HSM managed file
system backups, can require above 400 MB of disk space for each million files being backed up. The disk
cache file can become very large. Large file support must be enabled on the file system that is being used
for the disk cache file.

348 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Supported Clients
This option is valid for all clients. The server can also define this option.

Options File
Place this option in the dsm.sys file within a server stanza.

Syntax
DISKCACHELocation path

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.

Examples
Options file:

diskcachelocation /home
diskcachelocation /Volumes/hfs2

Command line:
Does not apply.
See “Include options” on page 403 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 file
systems to process during an incremental backup:
• When you run an incremental backup by using the incremental command, and you do not specify
which file systems to process.
• When your IBM Spectrum Protect administrator defines a schedule to run an incremental backup for
you, but does not specify which file systems to process.
• When you select the Backup Domain action from the backup-archive client GUI
• When you run an incremental backup by using the incremental command, and you do not specify
which drives to process.
• When your IBM Spectrum Protect administrator defines a schedule to run an incremental backup for
you, but does not specify which drives to process.
• When you select the Backup Domain action from the backup-archive client GUI
You can define the domain option in the following locations:
• In an options file.
• On the command line, when entered with a client command.
• In a client option set, which is defined on the server with the define clientopt command.
• 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

Chapter 10. Processing options 349

 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-.
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 /fs1:

domain all-local -/fs1

Example 2: This example uses multiple domain statements to back up all local file systems except for /
fs1:

domain all-local domain -/fs1

Example 3: This example excludes /fs1 during a backup operation. If no other domain statement is
used, the result is an empty domain. Nothing is backed up.

domain -/fs1

If you start the incremental command with a file specification, the client ignores any domain definitions
and backs up only the file specification.
You can include a virtual mount point in your client domain.
Important: If you are running GPFS for AIX or GPFS for Linux x86_64 in a multinode cluster, and all
nodes share a mounted GPFS file system, the client processes this file system as a local file system. The
client backs up the file system on each node during an incremental backup. To avoid this situation, you
can do one of the following tasks:
• Explicitly configure the domain statement in the client user options file (dsm.opt) to list the file systems
you want that node to back up.
• Set the exclude.fs option in the client system-options file to exclude the GPFS file system from
backup services.

Automounted file systems

When you perform a backup with the domain option set to all-local, files that are handled by
automounter and loopback file systems are not backed up.
If you back up a file system with the domain option set to all-local, any subdirectories that are mount
points for an automounted file system (AutoFS) are excluded from a backup operation. Any files that exist
on the server for the automounted subdirectory are expired.
When you perform a backup with the domain option set to all-lofs, all explicit loopback file systems
(LOFS) are backed up and all automounted file systems are excluded. For loop devices and local file
systems that are handled by automounter, set the domain option to all-auto-lofs.
Use the automount option with the domain parameters, all-auto-nfs, and all-auto-lofs to
specify one or more automounted file systems to be mounted and added into the domain. If you specify
the automount option, automounted file systems are remounted if they go offline during the execution of
the incremental command.
Virtual mount points cannot be used with automounted file systems.
Important: On some Linux distributions, automounted file system mount points or maps of file system
type (AutoFS) might not be listed in the current mount table. As a result, the automounted files systems,
which are unmounted during backup or archive processing, might be incorrectly processed and stored as

350 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
part of a wrong domain (for example, as part of domain all-local, all-nfs, or all-lofs, depending
on the actual file system type). Therefore, in such Linux distribution environments, you must specify the
appropriate automount option setting to correctly process your domain option setting at all points in
time.
For Mac OS X, automounted file systems are not supported. If an automounted file system is part of a
domain statement, the backup fails and no files in the automounted file system are processed. Back up
and restore the automounted file system from the host system. Do not back up or restore the
automounted file system over a network connection.

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 or dsm.sys. In the dsm.sys file, you must place this option
within a server stanza. You can set this option on the Backup tab, Domain for Backup section of the
Preferences editor.

Syntax

all-local
DOMain
domain

-domain

all-lofs

all-nfs

all-auto-nfs

all-auto-lofs

Parameters
all-local
Backs up all local file systems except LOFS file systems and LOFS through automounter. This
parameter is the default. The /tmp directory is not included.
domain
Defines the file systems to include in your default client domain.
When you use domain with the incremental command, it processes these file systems in addition
to those file systems you specify in your default client domain.
-domain
Defines the file systems to exclude in your default client domain.
all-lofs
Backs up all loopback file systems, except those file systems that are handled by automounter. This
parameter is not supported on Mac OS X.
Note: On Linux, you must configure an appropriate /etc/fstab entry to include a bind mount into
the all-lofs domain.
all-nfs
Backs up all network file systems, except those file systems that are handled by automounter. This
parameter is not supported on Mac OS X.

Chapter 10. Processing options 351

 all-auto-nfs
Backs up all network file systems (but not local file systems) which are handled by automounter. This
parameter is not supported on Mac OS X.
all-auto-lofs
Backs up all loop devices and local file systems that are handled through automounter. This
parameter is not supported on Mac OS X.
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.

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 all-local
domain all-local -/Volumes/volume2
domain all-local '-/Volumes/Macintosh HD'

domain /tst /datasave /joe

"domain all-local"
domain ALL-LOCAL -/home
domain ALL-NFS -/mount/nfs1

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="/ /Volumes/volume2"
-domain="all-local -/Volumes/volume2"

-domain="/fs1 /fs2"
-domain=/tmp
-domain="ALL-LOCAL -/home"

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 file system.
This 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.

352 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 74. 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 FS3 FS1 FS2 FS3
domain=FS2
domain FS1 incremental domain FS3 FS1 FS3
incremental - FS2
domain=FS2
incremental - domain FS3 FS2 FS3
domain=FS2
incremental domain FS3 FS3
incremental all-local
domain all-local incremental domain FS3 all-local + FS3
incremental all-local, but not FS1
domain all-local
domain -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 - FS1
domain=all-local
incremental FS1 domain all-local FS1
domain -FS1 incremental FS1 FS1

Related information
For information about defining a virtual mount point, see “Virtualmountpoint” on page 539.
For information about specifying one or more automounted file systems to be mounted and added into
the domain, see “Automount” on page 316.

Domain.image
The domain.image option specifies what you want to include in your client domain for an image backup.
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 AIX, Linux x86_64, Linux on POWER, and Solaris. The server can also define this
option. The IBM Spectrum Protect API does not support this option.
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.

Chapter 10. Processing options 353

 Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. 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 /fs1 /fs2
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.sys), 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 the volumes that you specify on the command line to the
volumes defined in your dsm.sys file. For example, if you enter domain.nas nas1/vol/vol0
nas1/vol/vol1 in your dsm.sys 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.sys file, all-nas takes precedence.

Supported Clients
This option is only valid for AIX and Solaris clients. The server can also define this option.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax

all-nas
DOMAIN.Nas
domain

354 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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.

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:
• Use the VM= option and specify the name of a virtual machine.
• Provide a comma-separated list of virtual machine names.
• Use wildcard syntax to process virtual machines that match the name pattern.
• 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.

Chapter 10. Processing options 355

 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 x86_64 Linux 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

;

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). The names are case-sensitive.

356 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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:
• Exclude all files that have "test" in the host name: -vm=*test*
• 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

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"

Chapter 10. Processing options 357

 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:

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

358 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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.
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 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

Chapter 10. Processing options 359

 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.

domain.vmfull vmdatacenter=dc1

360 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Related reference
“Supported data protection tags” on page 713
IBM Spectrum Protect data protection tags can be assigned to VMware inventory objects to control how
virtual machine backups are managed.
“Exclude.vmdisk” on page 378
The EXCLUDE.VMDISK option excludes a virtual machine disk from backup operations.
“Include.vmdisk” on page 411
The INCLUDE.VMDISK option includes a virtual machine (VM) disk in backup operations. If you do not
specify one or more disk labels, all disks in the VM are backed up.

Dontload
x86_64 Linux clients can use the dontload option to suppress specific plug-in libraries from being
loaded when the backup-archive client is started.
The TIVsm_BAhdw.x86_64 package provided in Linux x86_64 distributions contains software that is
required to support snapshot incremental backups for NetAPP and N-Series file servers. When this
package is installed on a Linux x86_64 system that is used to perform data mover operations for a virtual
machine, the files in this package cause all VMware backup operations to fail. When these failures occur,
the following message is displayed:
ANS8811E
VMware operations cannot be run when the hardware plug-in product TIVsm-BAhdw
is installed and loaded. Either uninstall the hardware product TIVsm-BAhdw, or
set the option DONTLOAD PIHDW in the options file to prevent the hardware plug-
in from being loaded.
Use this option to prevent the plug-in library from being loaded into RAM when the client is started.
Alternatively, you can uninstall the TIVsm_BAhdw package if it is not needed for snapshot operations.

Supported Clients
This option is only valid for Linux x86_64 clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax
DONTLoad PIHDW

Parameters
PIHDW
Specifies that the hardware plug-in (TIVsm-BAhdw) is not loaded into RAM when the client is started.
Use this option on backup-archive clients that have the hardware plug-in installed, to prevent the
plug-in from causing failures when performing backup-archive operations on VMware virtual
machines. There is no default for the dontload option.
To determine whether the plug-in is installed, enter the following command and examine the output.

rpm -q -a | grep TIV

If the output contains a package starting with "TIVsm-BAhdw" (followed by a version string), the
hardware plug-in package is installed.

Chapter 10. Processing options 361

 Examples
Options file:

DONTLoad PIHDW

Command line:
Does not apply. Do not use this option on the command line.
Related reference
“Backup VM” on page 608
“Restore VM” on page 681
Use the restore vm command to restore a virtual machine (VM) that was previously backed up.

Dynamicimage
Use the dynamicimage option with the backup image command or the include.image option to
specify that you want to perform a dynamic image backup.

Supported Clients
This option is valid for AIX, Solaris, and all Linux clients. The IBM Spectrum Protect API does not support
this option.

Options File
Place the include.image statement containing the dynamicimage value in the server stanza in your
system-options file, dsm.sys. You can also set this option using the Preferences editor.

Syntax
DYNAMICImage value

Parameters
value
Specifies one of the following values:
yes
Use this option only if the volume cannot be unmounted and remounted as read-only. The client
backs up the volume as is without remounting it as read-only. Corruption of the backup can occur if
applications write to the volume while the backup is in progress. In this case, run fsck after a restore
and manually mount the file system in order to regain access to the volume. This option is valid for
AIX, Solaris, and all Linux clients.
Note: This option is not allowed for AIX JFS2 file systems.
no
Use this option if you do not want to perform a dynamic image backup. This is the default. The default
behavior depends on the platform and file system type. For platforms and file systems that support
snapshot, namely AIX JFS2 file systems and LINUX LVM file systems, the default is snapshot-based
image backup. For all other UNIX platforms and file systems, the default is static image backup.

Examples
Options file:
include.image /kalafs1 dynamicimage=yes
Command line on backup image:
dynamicimage=yes

362 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Efsdecrypt
The efsdecrypt option allows you to control whether or not files encrypted by an AIX Encrypted File
System (EFS) are read in encrypted or decrypted format.
The efsdecrypt option default is no, which is to back up the encrypted or raw data. If you specify yes,
the files are backed up as clear text, which means that they are backed up as normal files, as if the files
existed in unencrypted form on the file system.
Important: Whenever you run a backup that includes any files encrypted on an EFS, you must ensure that
you use the correct specification of the efsdecrypt option. If the efsdecrypt option value changes
between two incremental backups, all encrypted files on EFS file systems are backed up again, even if
they have not changed since the last backup. For example, if you are running an incremental backup of
encrypted files that were previously backed up as "raw," then ensure that efsdecrypt is specified as no.
If you change efsdecrypt to yes, all the files are backed up again in clear text even if they are
unchanged, so ensure that you use this option carefully.
Note: This is a global option that is applied to the complete backup. Two separate invocations of the
client are required to back up some encrypted files as raw data and others as clear text.

Supported Clients
This option is valid for AIX clients.

Options File
Place this option in the dsm.sys file or the client user-options file (dsm.opt). In the dsm.sys file, you must
place this option within a server stanza.

Syntax
No
EFSDecrypt
Yes

Parameters
No
Encrypted files are read in encrypted or raw data format, and IBM Spectrum Protect encryption and
compression is forced off. This is the default.
Yes
Encrypted files are read in decrypted or clear text format.

Examples
Options file:
EFSDecrypt yes
Command line:
-EFSDecrypt=no

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.

Chapter 10. Processing options 363

 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.
• incremental
• backup (all subcommands)
• selective
• restore (all subcommands except restore backupset -location=file or -location=tape)
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.

Options File
This option is valid only in the dsm.sys file within a server stanza 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.

364 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
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 system-options file (dsm.sys) within a server stanza. 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

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 338
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.
“Dedupcachepath” on page 337

Chapter 10. Processing options 365

 Use the dedupcachepath option to specify the location where the client-side data deduplication cache
database is created.
“Dedupcachesize” on page 338
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.

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:
• 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.
• The total activity time of each thread.
• The command that was issued and the options that were used.
• 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 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:
• Scheduled file-level backup operations with the backup-archive client
• IBM Spectrum Protect for Virtual Environments: Data Protection for VMware backups
• IBM Spectrum Protect for Virtual Environments: Data Protection for Microsoft Hyper-V backups
• IBM Spectrum Protect for Databases: Data Protection for Microsoft SQL Server backups
• 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 system-options file (dsm.sys) within a server stanza.

366 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 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 /home/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
The instrlogmax option specifies the maximum size of the instrumentation log (dsminstr.log), in
MB. Performance data for the client is collected in the dsminstr.log file during backup or restore
processing when the enableinstrumentation option is set to yes.
Instrlogname
The instrlogname option specifies the path and file name where you want to store performance
information that the backup-archive client collects.

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.
Notes:

Chapter 10. Processing options 367

 • If you place the enablelanfree option in the client options 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.
• To restore backup sets in a SAN environment, see “Restore Backupset” on page 668 for more
information.
• 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.
• Client encryption with the include.encrypt option is no longer supported for LAN-free backup and
archive operations to the IBM Spectrum Protect server V8.1.1 and later levels, or V7.1.8 and later V7
levels. LAN-free restore and retrieve operations of encrypted backup versions and archive copies
continue to be supported. If you need to encrypt data by using the include.encrypt option, in which
data is encrypted before it is sent to the server, use LAN-based backup or archive operations.

Supported Clients
This option is valid for AIX, Linux x86_64, Linux on Power Systems, Linux on z Systems, and Solaris
clients.

Options File
Place this option in the dsm.sys file within a server stanza. You can also set this option by selecting the
Enable Lanfree check box on the General tab in the Preferences editor.

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 423.

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

368 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 system-options file (dsm.sys) within a server stanza. You can also set this
option on the Authorization tab of the Preferences editor. The server can override this.

Syntax
AES128
ENCRYPTIONType
AES256

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
sent to the server. There are three options for managing the key used to encrypt the files (prompt, save,
and generate). All three options can be used with either the backup-archive client or the IBM Spectrum
Protect API.
The encryption key password is case-sensitive and can be up to 64 characters in length.
The following characters can be included in the encryption key password:
A-Z
Any letter, A through Z, uppercase or lowercase. You cannot specify national language characters.
0-9
Any number, 0 through 9
+
Plus
.
Period
_
Underscore

Chapter 10. Processing options 369

 -
Hyphen
&
Ampersand
Note:
1. The API has an alternate way of specifying encryptkey=generate; the previous
enableclientencryptkey=yes option can also be specified to request generate encryption
processing.
2. The enableclientencryptkey=yes API option is still supported, so it is possible when using the
API to specify two conflicting options. For example, enableclientencryptkey=yes and
encryptkey=prompt or encryptkey=save.
3. When conflicting values are specified, the API returns an error message.
Attention: When using the prompt option, your encryption key is not saved in the IBM Spectrum
Protect password file on UNIX. If you forget the key, your data cannot be recovered.

Supported Clients
This option is valid for all clients. The server can also define this option.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the Authorization tab, Encryption Key Password section of the Preferences editor.

Syntax
save
ENCRYPTKey
prompt

generate

Parameters
save
The encryption key password is saved in the backup-archive client password file. A prompt is issued
for an initial encryption key password, and after the initial prompt, the saved encryption key password
in the password file is used for the backups and archives of files matching the include.encrypt
specification. The key is retrieved from the password file on restore and retrieve operations.
The password can be up to 64 bytes in length.
When the save option is specified for an API application, the initial key password must be provided
by the application using the API in the dsmInitEx function call. The API itself does not issue a
prompt to the user but relies on the application to prompt the user as necessary.
This parameter is the default.
Note: The following restrictions apply:
• This option can only be used when passwordaccess generate is also specified.
• The root user or an authorized user must specify the initial encryption key password.
prompt
The management of the encryption key password is provided by the user. The user is prompted for
the encryption key password when the client begins a backup or archive. A prompt for the same
password is issued when restoring or retrieving the encrypted file.
This password can be up to 64 bytes in length.

370 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 When the prompt option is specified for an API application, the key password must be provided by
the application using the API in the dsmInitEx function call. The API itself does not issue a prompt
to the user but relies on the application to prompt the user as necessary.
generate
An encryption key password is dynamically generated when the client begins a backup or archive.
This generated key password is used for the backups of files matching the include.encrypt
specification. The generated key password, in an encrypted form, is kept on the IBM Spectrum
Protect server. The key password is returned to the client to enable the file to be decrypted on restore
and retrieve operations.

Examples
Options file:
encryptkey prompt
Command line:
Does not apply.

Errorlogmax
The errorlogmax option specifies the maximum size of the error log, in megabytes. The default name
for the error log is dsmerror.log.
Log wrapping is controlled by the errorlogmax option. If errorlogmax is set to zero (0), the size of the
log is unlimited; logged entries never "wrap" and begin overwriting earlier logged entries. If
errorlogmax is not set to zero, the newest log entries overwrite the oldest log entries after the log file
reaches its maximum size.
Log pruning is controlled by the errorlogretention option. Pruned logs do not wrap. Instead, log
entries that are older than the number of days specified by the errorlogretention option are removed
from the log file.
If you change from log wrapping (errorlogmax option) to log pruning (errorlogretention option), all
existing log entries are retained and the log is pruned using the new errorlogretention criteria.
Pruned log entries are saved in a file called dsmerlog.pru.
If you change from using log pruning (errorlogretention option) to using log wrapping (errlogmax
option), all records in the existing log are copied to the dsmerlog.pru log file, the existing log is
emptied, and logging begins using the new log wrapping criteria.
If you simply change the value of the errorlogmax option, the existing log is extended or shortened to
accommodate the new size. If the value is reduced, the oldest entries are deleted to reduce the file to the
new size.
If neither errologmax nor errorlogretention is specified, the error log can grow without any limit on
its size. You must manually manage the log contents to prevent the log from depleting disk resources.
When the log has been created with neither option specified, if you later issue a command and specify the
errorlogretention option, the log is pruned using the retention value specified. When the log has
been created with neither option specified, if you later issue a command and specify the errorlogmax
option, the existing log is treated as if it was a pruned log. That is, the content of the dsmerror.log file
is copied to a file called dsmerlog.pru and new log entries are created in dsmerror.log and the log is
wrapped when it reaches its maximum size.
Note: If you specify a non-zero value for errorlogmax (which enables log wrapping), you cannot use the
errorlogretention option to create pruned logs. Logs can be pruned or wrapped, but not both.
Logs created with the errorlogmax option contain a log header record that contains information similar
to this example record:

LOGHEADERREC 661 104857600 IBM Spectrum Protect 8.1.0 Fri Dec 9 06:46:53 2011

Note that the dates and time stamps in the LOGHEADERREC text are not translated or formatted using the
settings specified on the dateformat or timeformat options.

Chapter 10. Processing options 371

 Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.
You can also set this option on the Client preferences tab in the GUI, by selecting Enable error log file
wrapping and by specifying a non-zero maximum size for the log file. To prevent log file wrapping, set
the maximum size to zero. When the maximum wrapping is set to zero, clearing or setting the Enable
error log file wrapping option has no effect; log wrapping does not occur if the maximum size is set to
zero.

Syntax
ERRORLOGMAX size

Parameters
size
Specifies the maximum size, in megabytes, for the log file. The range of values is 0 to 2047; the
default is 0, which disables log file wrapping and allows the log file to grow indefinitely.

Examples
Options file:
errorlogmax 2000
Command line:
-errorlogmax=2000
This option is valid only on the initial command line. It is not valid in interactive mode.

Errorlogname
This option specifies the fully qualified path and file name of the file that contains the error messages.
The value for this option overrides the DSM_LOG environment variable. The dsmwebcl.log and
dsmsched.log files are created in the same directory as the error log file you specify with the
errorlogname option.
For Mac OS X, the default location is one of the following:

~/Library/Logs/tivoli/tsm/
/Library/Logs/tivoli/tsm/

The dsmerror.log cannot be a symbolic link.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the General tab, Select Error Log button of the Preferences editor.

Syntax
ERRORLOGName filespec

372 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Parameters
filespec
The fully qualified path and file name in which to store error log information. If any part of the path
you specify does not exist, the client attempts to create it.
The dsmerror.log file cannot be a symbolic link.

Examples
Options file:
errorlogname /tmp/tsmerror.log
Command line:
-errorlogname=/tmp/tsmerror.log
This option is valid only on the initial command line. It is not valid in interactive mode.

Errorlogretention
The errorlogretention option specifies how many days to maintain error log entries before pruning,
and whether to save the pruned entries in other files.
The error log is pruned when the first error is written to the log after a client session is started. If the only
session you run is the client scheduler, and you run it twenty-four hours a day, the error log might not be
pruned according to your expectations. Stop the session and start it again to allow the scheduler to prune
the error log.
If you change from log pruning (errorlogretention option) to log wrapping (errorlogmax option), all
records in the existing log are copied to the dsmerlog.pru log file, the existing log is emptied, and
logging begins using the new log wrapping criteria.
If you change from log wrapping (errorlogmax option) to log pruning (errorlogretention option), all
existing log entries are retained and the log is pruned using the new errorlogretention criteria.
Pruned log entries are saved in a file called dsmerlog.pru.
If neither errologmax nor errorlogretention is specified, the error log can grow without any limit on
its size. You must manually manage the log contents to prevent the log from depleting disk resources.
When the log has been created with neither option specified, if you later issue a command and specify the
errorlogretention option, the log is pruned using the retention value specified. When the log has
been created with neither option specified, if you later issue a command and specify the errorlogmax
option, the existing log is treated as if it was a pruned log. That is, the content of the dsmerror.log file
is copied to a file called dsmerlog.pru and new log entries are created in dsmerror.log and the log is
wrapped when it reaches its maximum size.
Note: If you specify errorlogretention option to create pruned logs, you cannot specify the
errorlogmax option. Logs can be pruned or wrapped, but not both.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.
You can also set this option on the Client preferences tab in the GUI, by selecting Prune old entries and
by specifying a value for Prune entries older than. Selecting the Save pruned entries option saves the
pruned log entries in the dsmerlog.pru log file.

Chapter 10. Processing options 373

 Syntax
N D
ERRORLOGRetention
days S

Parameters
N or days
Specifies how long to wait before pruning the error log.
N
Do not prune the error log. This permits the error log to grow indefinitely. This is the default.
days
The number of days to keep log file entries before pruning the log. The range of values is zero
through 9999.
D or S
Specifies whether to save the pruned entries. Enter a space or comma to separate this parameter
from the previous one.
D
Discard the error log entries when you prune the log. This is the default.
S
Save the error log entries when you prune the log.
The pruned entries are copied from the error log to the dsmerlog.pru file located in the same
directory as the dsmerror.log file.

Examples
Options file:
Prune log entries from the dsmerror.log file that are older than 365 days and save the pruned
entries in dsmerlog.pru.
errorlogretention 365 S
Command line:
-errorlogr=365,S
Options file:
Prune log entries from the dsmerror.log file that are older than 365 days and do not save the
pruned entries.
errorlogretention 365 D
This option is valid only on the initial command line. It is not valid in interactive mode.

Exclude options
Use the exclude options to exclude objects from backup, image, or archive services.
For example, you might want to exclude this type of information:
• All temporary files
• Any local caches of network files
• All files that contain compiled object code that you can easily reproduce using other methods
• Your operating system files
You can exclude specific files from encryption processing during a backup.
Note:

374 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
1. With the exception of exclude.fs, when you exclude a file that was previously included, existing
backup versions become inactive during the next incremental backup.
2. The server can define exclude options with the inclexcl option.
Exclude any system files or images that could corrupt the operating system when recovered. Also exclude
the directory containing the IBM Spectrum Protect client files.
Use wildcard characters to exclude a broad range of files.
To exclude an entire directory called /any/test, enter the following:

exclude.dir /any/test

To exclude subdirectories that begin with test under the /any directory, enter the following:

exclude.dir /any/test*

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set these
options on the Include-Exclude tab, Define Include-Exclude Options section of the Preferences editor.

Syntax
options pattern

exclude, exclude.backup, exclude.file, exclude.file.backup

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.archive
Excludes a file or a group of files that match the pattern from archive services only.
exclude.attribute.symlink
Excludes a file or a group of files that are symbolic links or aliases (aliases apply to Mac OS X) from
backup processing only.
Note: For Mac OS X aliases are excluded.
exclude.compression
Excludes files from compression processing if the compression option is set to yes. This option
applies to backups and archives.
exclude.dedup
Excludes files from client-side data deduplication. To control a client-side data deduplication
operation, specify ieobjtype as the value of the exclude.dedup option.
Valid ieobjtype parameters are:
File
Image
The default is File.
exclude.dir
Excludes a directory, its files, and all its subdirectories and their files from backup processing. For
example, the statement exclude.dir /test/dan/data1 excludes the /test/dan/data1
directory, its files, and all its subdirectories and their files.

Chapter 10. Processing options 375

 If you exclude a directory that was previously included, the server expires existing backup versions of
the files and directories beneath it during the next incremental backup. Use this option to exclude a
portion of your data that has no underlying files to back up.
Note: Avoid performing a selective backup, or a partial incremental backup, of an individual file within
an excluded directory. The next time that you perform an incremental backup, any files backed up in
this manner is expired.
exclude.encrypt
Excludes the specified files from encryption processing. This option does not affect whether files are
excluded from backup or archive processing, only whether they are excluded from encryption
processing.
exclude.fs
Excludes file systems that match the specified pattern from backup, incremental image backup, and
archive operations. If files from the excluded file systems were ever backed up, then management
class rebinding and deleted file expiration does not occur. However, existing backup versions remain
on the server subject to associated management class settings. The files that were previously
archived from the excluded file system remain on the server as archive copies.
The exclude.fs option does NOT prevent the backup or archive of any virtual mount points that are
subdirectories of the excluded file system.
Use exclude.image to exclude file systems from full image backup operations.
exclude.fs.nas
Excludes file systems on the NAS file server from an image backup when used with the backup nas
command. The NAS node name must be prefixed to the file system name, for example:
netappsj1/vol/vol1. To apply the exclude to all NAS nodes, replace the NAS node name with a
wildcard, for example: */vol/vol1. The backup nas command ignores all other exclude
statements including exclude.fs and exclude.dir statements. This option is valid for AIX and
Solaris clients only.
exclude.image
Excludes mounted file systems and raw logical volumes that match the specified pattern from full
image backup operations. This option is valid for AIX, all Linux clients, and Solaris only. Use
exclude.fs to exclude file systems from incremental image backup operations.
Restriction: This option does not apply to Mac OS X.

Parameters
pattern
Specifies the file or group of files that you want to exclude.
Note: For NAS file systems: You must prefix the NAS node name to the file specification to specify the
file server to which the exclude statement applies. If you do not specify a NAS node name, the file
system identified refers to the NAS node name specified in the client system-options file (dsm.sys) or
on the command line.
If the pattern begins with a single or double quote or contains any embedded blanks or equal signs,
you must surround the value in either single (') or double (") quotation marks. The opening and closing
quotation marks must be the same type of quotation marks.
For the exclude.image option, the pattern is the name of a mounted file system or raw logical
volume.

Examples
Options file:

exclude /unix/
exclude /.../core
exclude /home/jones/proj1/*
exclude.archive /.../core

376 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 exclude.backup /home/jones/proj1/devplan/
exclude.dir /home/jones/tmp
exclude.backup /users/home1/file1
exclude.image /usr/*/*
exclude.encrypt /users/home2/file1
exclude.compression /home/gordon/proj1/*
exclude.fs.nas netappsj/vol/vol0
exclude.attribute.symlink /.../*
exclude.dedup /Users/Administrator/Documents/Important/.../*

Command line:
Does not apply.
Related information
See “System files to exclude” on page 116 for a list of files that you should always exclude.
“Inclexcl” on page 402
See “Include and exclude groups of files with wildcard characters” on page 117 for a list of wildcard
characters that you can use. Then, if necessary, use the include option to make exceptions.

Controlling symbolic link and alias processing

The backup-archive client treats symbolic links and aliases (aliases apply to Mac OS X only) as actual files
and backs them up. However, the file referenced by the symbolic link is not backed up. In some cases
symbolic links can be easily recreated and need not be backed up.
In addition, backing up these symbolic links can increase backup processing time and occupy a
substantial amount of space on the IBM Spectrum Protect server. You can use the
exclude.attribute.symlink option to exclude a file or a group of files that are symbolic links from
backup processing. If necessary, you can use the include.attribute.symlink option to include
symbolic links within broad group of excluded files for backup processing.
For example, to exclude all symbolic links from backup processing, except those that exist under the /
home/spike directory, enter these statements in your dsm.sys file:

exclude.attribute.symlink /.../*
include.attribute.symlink /home/spike/.../*

Related reference
“Include options” on page 403
The include options specify objects that you want to include for backup and archive services.

Controlling compression processing

This topic lists some items to consider if you want to exclude specific files or groups of files from
compression processing during a backup or archive operation.
• Remember that the backup-archive client compares the files it processes against the patterns specified
in the include-exclude statements, reading from the bottom to the top of the options file.
• You must set the compression option to yes to enable compression processing. If you do not specify
the compression option or you set the compression option to no, the client does not perform
compression processing.
If you set the compression option to yes and no exclude.compression statements exist, the client
considers all files for compression processing.
• The client processes exclude.fs, exclude.dir, and other include-exclude statements first. The
client then considers any exclude.compression statements. For example, consider the following
include-exclude list:

exclude /home/jones/proj1/*.*
exclude.compression /home/jones/proj1/file.txt
include /home/jones/proj1/file.txt

Chapter 10. Processing options 377

 The client examines the statements (reading from bottom to top) and determines that the /home/
jones/proj1/file.txt file is a candidate for backup, but is not a candidate for compression
processing.
• Include-exclude compression processing is valid only for backup and archive processing. The
exclude.compression option does not affect whether files are excluded from backup or archive
processing, only whether they are excluded from compression processing.
Related reference
“Compression” on page 326
The compression option compresses files before you send them to the server.

Processing NAS file systems

Use the exclude.fs.nas option to exclude file systems from NAS image backup processing.
Note: The exclude.fs.nas option does not apply to a snapshot difference incremental backup.
A NAS file system specification uses the following conventions:
• NAS nodes represent a unique node type. The NAS node name uniquely identifies a NAS file server and
its data to the backup-archive client. You can prefix the NAS node name to the file specification to
specify the file server to which the exclude statement applies. If you do not specify a NAS node name,
the file system identified applies to all NAS file servers.
• Regardless of the client platform, NAS file system specifications use the forward slash (/) separator, as
in this example: /vol/vol0.
For example, to exclude /vol/vol1 from backup services on all NAS nodes, specify the following
exclude statement:

exclude.fs.nas */vol/vol1

Virtual machine exclude options

Virtual machine include and exclude options influence the behavior of backup and restore operations for
virtual machines. These options are processed before any command-line options are processed, so that
options on the command line can override options specified on any of the virtual machine include options
or virtual machine exclude options. See the individual option descriptions for information about the
options.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.
Related reference
“Exclude.vmdisk” on page 378
The EXCLUDE.VMDISK option excludes a virtual machine disk from backup operations.

Exclude.vmdisk
The EXCLUDE.VMDISK option excludes a virtual machine disk from backup operations.
The EXCLUDE.VMDISK option specifies the label of a virtual machine's disk to be excluded from a
backup vm operation. If you exclude a disk on the backup vm command, the command-line parameters
override any EXCLUDE.VMDISK statements in the options file.
This option is available only if you are using the IBM Spectrum Protect for Virtual Environments licensed
product. For more information about this option, see the IBM Spectrum Protect for Virtual Environments
product documentation on IBM Knowledge Center at http://www.ibm.com/support/knowledgecenter/
SSERB6/welcome.

EXCLUDE.VMDISK for VMware virtual machines

Use the EXCLUDE.VMDISK option to exclude a VMware virtual machine from backup operations.

378 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Supported clients
This option can be used with supported x86_64 Linux clients.

Options file
Set this option in the client options file. Command line parameters override statements in the options file.

Syntax for VMware virtual machines

EXCLUDE.VMDISK vmname vmdk_label

Parameters
vmname
Specifies the name of the virtual machine that contains a disk that you want to exclude from a Backup
VM operation. The name is the virtual machine display name. You can specify only one virtual machine
name on each EXCLUDE.VMDISK statement. Specify additional EXCLUDE.VMDISK statements for
each virtual machine disk to exclude.
The virtual machine name can contain an asterisk (*), to match any character string, and question
mark (?) to match any one character. Surround the VM name with quotation marks (" ") if the VM name
contains space characters.
Tip: If the virtual machine name contains special characters, such as bracket characters ([) or (]), the
virtual machine name might not be correctly matched. If a virtual machine name uses special
characters in the name, you might need to use the question mark character (?) to match the special
characters in the VM name.
For example, to exclude Hard Disk 1 in the backup of a virtual machine named "Windows VM3
[2012R2]", use this syntax in the options file: EXCLUDE.VMDISK "Windows VM3 ?2012R2?"
"Hard Disk 1"
vmdk_label
Specifies the disk label of the disk that you want to exclude. Wildcard characters are not allowed. Use
the Backup VM command with the -preview option to determine the disk labels of disks in a given
virtual machine. See the "Backup VM" topic for the syntax.
Do not exclude disks on virtual machines that you are protecting with the INCLUDE.VMTSMVSS
option, if the disks contain application data.

Examples
Options file
Assume that a virtual machine named vm1 contains four disks, labeled Hard Disk 1, Hard Disk 2, Hard
Disk 3, and Hard Disk 4. To exclude disk 2 from Backup VM operations, specify the following
statement in the options file:

EXCLUDE.VMDISK "vm1" "Hard Disk 2"

Exclude disks 2 and 3 from Backup VM operations:

EXCLUDE.VMDISK "vm1" "Hard Disk 2"

EXCLUDE.VMDISK "vm1" "Hard Disk 3"

Command line
The command line examples show the use of the exclusion operator (-) before the vmdk= keyword, to
indicate that the disk is to be excluded.
Exclude a single disk:

dsmc backup vm "vm1:-vmdk=Hard Disk 1"

Exclude disk 2 and disk 3:

Chapter 10. Processing options 379

 dsmc backup vm "vm1:-vmdk=Hard Disk 2:-vmdk=Hard Disk 3"

Exclude disk 1 and disk 2 on vm1:

dsmc backup vm "vm1:-vmdk=Hard Disk 1:-vmdk=Hard Disk 2"

Related reference
“Backup VM” on page 608
“Restore VM” on page 681
Use the restore vm command to restore a virtual machine (VM) that was previously backed up.
“Domain.vmfull” on page 355
The domain.vmfull option specifies the virtual machines (VMs) to include in your full virtual machine
image backup operations.
“Include.vmdisk” on page 411
The INCLUDE.VMDISK option includes a virtual machine (VM) disk in backup operations. If you do not
specify one or more disk labels, all disks in the VM are backed up.
“INCLUDE.VMTSMVSS” on page 418
The INCLUDE.VMTSMVSS option notifies virtual machine applications that a backup is about to occur.
This option allows the application to truncate transaction logs and commit transactions so that the
application can resume from a consistent state when the backup completes. An optional parameter can
be specified to suppress truncation of the transaction logs.

Exclude.vmlocalsnapshot
This option excludes a VMware virtual machine from local backup operations.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.
You can use this option only for virtual machines that are stored in a virtual volume (VVOL) datastore.

Supported clients
This option can be used with supported Linux clients that are configured to back up VMware virtual
machines.

Options file
Set this option in the client options file.

Syntax
EXCLUDE.VMLOCALSNAPSHOT vmname

Parameters
vmname
Specifies the name of a virtual machine that you want to exclude from local backup operations. The
name is the virtual machine display name.
Only one virtual machine can be specified on each EXCLUDE.VMLOCALSNAPSHOT statement.
However, you can specify as many EXCLUDE.VMLOCALSNAPSHOT statements as needed to exclude
multiple virtual machines.
You can include wildcards in the virtual machine name. An asterisk (*) matches any character string. A
question mark (?) matches a single character. If the virtual machine name contains a space character,
enclose the name in double quotation marks (").
Tip: If the virtual machine name contains special characters, type the question mark wildcard in place
of the special characters when you specify the virtual machine name.

380 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Example
The following EXCLUDE.VMLOCALSNAPSHOT statement in the client options file excludes a virtual
machine that is named VM1 from local backup operations:

exclude.vmlocalsnapshot VM1

Related reference
“Backup VM” on page 608

Fbbranch
Use the fbbranch option with the backup fastback or archive fastback commands.
The fbbranch option specifies the branch ID of the remote FastBack server to back up or archive. The
fbbranch option is only required when the backup-archive client is installed on the FastBack Disaster
Recovery Hub or when a dedicated proxy is connecting to a replicated FastBack Disaster Recovery Hub
repository. Do not specify the fbbranch option when the backup-archive client is installed on the
FastBack server.

Supported Clients
This option is valid for Linux x86_64 clients.

Options File
None. You can specify this option only on the command line. The server can also define or override this
option.

Syntax
FBBranch= branch_ID

Parameters
branch_ID
Specifies the FastBack server branch ID. The value is part of the disaster recovery configuration of the
FastBack server.

Examples
Command line:
-FBBranch=oracle
On a backup-archive client that is installed on the FastBack Disaster Recovery Hub:

dsmc backup fastback -fbpolicyname=policy1 -fbserver=myFbServer

-fbbranch=oracle

Command line:
On a backup-archive client that is connecting to a repository on a remote FastBack Disaster Recovery
Hub:

dsmc backup fastback -fbpolicyname=policy1 -fbserver=server1

-Fbreposlocation=\\myDrHub.company.com\REP
-fbbranch=oracle

If the fbbranch option is specified on a backup-archive client workstation that is installed on the
FastBack server, the fbbranch option is ignored.

Chapter 10. Processing options 381

Fbclientname
Use the fbclientname option with the backup fastback or archive fastback commands.
The fbclientname option is the name of one or more comma-separated FastBack clients to back up or
archive from the backup proxy. The values for the fbclientname option are invalid if more than one
policy is specified in the fbpolicyname option.
You cannot include spaces in the fbclientname option values.
If you do not specify any values for the fbvolumename option, all the volumes from all the FastBack
clients in the policy that is specified are backed up. If you specify multiple FastBack clients in the
fbclientname option, you cannot specify values for the fbvolumename option.

Supported Clients
This option is valid for Linux x86_64 clients.

Options File
None. You can specify this option only on the command line.

Syntax
,

FBClientname client_name

Parameters
client_name
Specifies the name of one or more FastBack clients. You can specify up to 10 FastBack client names.
Important:
When specifying the archive fastback or backup fastback command:
1. At least one FBpolicyName is always required.
2. You can specify up to 10 values for FBPolicyName, if no values are specified for both FBClientName
and FBVolumeName.
3. When you specify a FBClientName value, there must be only one value for FBPolicyName.
4. You can specify up to 10 values for FBClientName if only one PolicyName is specified, and no values
for FBVolumeName are specified.
5. When you specify the FBVolumeName option, you can have only one FBPolicy, and only one
FBCLientName specified.
6. You can specify multiple FBVolumeNames if condition 5 is satisfied.
7. You must always specify the FBReposLocation option for Linux.

Examples
Command line:

dsmc backup fastback -fbpolicyname=Policy1

-fbclientname=fbclient1,fbclient2
-fbserver=myFbServer
-fbreposlocation=/mnt/FBLocation

Backs up all volumes for FastBack clients fbclient1 and fbclient2 that are found in policy Policy1.

382 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Fbpolicyname
Use the fbpolicyname option with the backup fastback or archive fastback commands.
The fbpolicyname option is the name of one or more comma-separated FastBack policies that you want
to back up or archive from the backup proxy. You must specify at least one policy name. Specify multiple
policy names using a comma-delimited list of policies. There is no default value.
If one or more FB policy names contain spaces, you must specify them within quotation marks. Here is an
example: "FB Policy NAME1, FBPolicy Name 2".
If you do not specify any values for the fbclientname and fbvolumename options, all the volumes from
all the FastBack clients in the policies that are specified are backed up. If you specify multiple policies in
the fbpolicyname option, you cannot specify values for the fbclientname and fbvolumename
options.
If a policy specification contains both Windows and Linux FastBack clients, only the Linux volumes will be
backed up or archived to the IBM Spectrum Protect server by the Linux backup-archive client.
At least one snapshot should exist in the FastBack repository for the FastBack policies being archived or
backed up prior to issuing the dsmc command

Supported Clients
This option is valid for Linux x86_64 clients.

Options File
None. You can specify this option only on the command line.

Syntax
,

FBPolicyname policy_name

Parameters
policy_name
Specifies the name of the FastBack policies. You can specify up to 10 FastBack policy names.
Important:
When specifying the archive fastback or backup fastback command:
1. At least one FBpolicyName is always required.
2. You can specify up to 10 values for FBPolicyName, if no values are specified for both FBClientName
and FBVolumeName.
3. When you specify a FBClientName value, there must be only one value for FBPolicyName.
4. You can specify up to 10 values for FBClientName if only one PolicyName is specified, and no values
for FBVolumeName are specified.
5. When you specify the FBVolumeName option, you can have only one FBPolicy, and only one
FBCLientName specified. You must specify exactly one FBClientName. It cannot be omitted.
6. You can specify multiple FBVolumeNames if condition 5 is satisfied.
7. You must always specify the FBReposLocation option for Linux.

Chapter 10. Processing options 383

 Examples
Command line:

dsmc backup fastback -fbpolicyname=Policy1,Policy2,Policy3

-fbserver=myFbServer
-fbreposlocation=\\myFbServer.company.com\REP

Backs up all volumes for all FastBack clients found in policies Policy1, Policy2 and Policy3.
To specify policies with spaces, enclose them in double quotation marks, for example:

-fbpolicyname="Policy 1,Policy2,Policy3"

Fbreposlocation
Use the fbreposlocation option with the backup fastback or archive fastback commands.
The fbreposlocation option specifies the location of the Tivoli Storage Manager FastBack repository
for the backup-archive client proxy to connect to issue Tivoli Storage Manager FastBack shell commands
necessary to mount appropriate snapshots.
This option is required on Linux systems. There is no default location.
It you specify the fbreposlocation option for a snapshot on the FastBack server, use the
server_name@WORKGROUP format.
There are two ways to specify the FastBack repository location on the FastBack Disaster Recovery Hub:
• Specify the complete repository location via the option -fbreposlocation=\\DR_Hub\rep_server.
When using this format, DR_Hub is the FastBack Disaster Recovery Hub machine name and
rep_server is the name of the replicated FastBack server repository on the DR Hub.
• Specify the repository location using a combination of the -fbreposlocation= and -fbbranch
options. When using this format, specify the DR Hub repository the location via the option -
fbreposlocation=DR_Hub@WORKGROUP, and specify the name of the replicated FastBack server
repository on the DR Hub using the -fbranch option.
If you use the format -fbr=\\<fbserver>\REP, specify two backslashes before <fbserver> and one
backslash before REP when using the backup-archive client in interactive mode. If you are using this
format as a Linux command dsmc backup fastback -fbr=\\\\<fbserver>\\REP, you must
specify four backslashes before <fbserver> and two backslashes before REP. This is because the Linux
shell interprets a backslash as an escape character; the first backslash is treated as an escape character
for the following backslash.

Supported Clients
This option is valid for Linux x86_64 clients.

Options File
None. You can specify this option only on the command line. The server can also define or override this
option.

Syntax
FBReposlocation repository_location

Parameters
repository_location
Specifies the Tivoli Storage Manager FastBack repository location.

384 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Examples
Command line:

dsmc backup fastback -fbpolicyname=Policy1

-fbclientname=fbclient1,fbclient2 -fbserver=myFbDrHub
-fbreposlocation=\\myFbDrHub\rep_myFbServer

Note: Because Linux is supported only as a dedicated proxy configuration, a repository location is
always required on Linux.
Command line:

dsmc backup fastback -fbpolicyname=Policy1

-fbclientname=fbclient1,fbclient2 -fbserver=myFbDrHub
-fbreposlocation=myFbDrHub -fbbranch=rep_myFbServer

Note: Because Linux is supported only as a dedicated proxy configuration, a repository location is
always required on Linux.

Fbserver
Use the fbserver option with the backup fastback or archive fastback commands.
The fbserver option specifies the short host name of the Tivoli Storage Manager FastBack server
workstation that owns the repository specified by the fbreposlocation option. For a DR Hub, the
fbserver option specifies the short name of the FastBack server workstation whose branch repository
the backup-archive client is connecting to.
The fbserver option is a key to retrieving the necessary user credentials required to connect to the
FastBack server repository or the DR Hub server repository for mount processing.

Supported Clients
This option is valid for Linux x86_64 clients.

Options File
None. You can specify this option only on the command line.

Syntax
-FBServer server_name

Parameters
server_name
Specifies the short hostname of the machine on which the FastBack server is installed.

Examples
Command line:
The backup-archive client is installed on a Linux proxy client machine. Use this command to archive
all FastBack volumes for all Linux FastBack clients that are defined for FastBack policy1:

dsmc archive fastback -fbpolicyname=Policy1

-fbserver=myfbserver
-fbreposlocation=myfbserver@WORKGROUP

The repository location is required. If you do not provide the repository location, the command will
fail.
The FastBack server name, -myfbserver, is the short host name of the FastBack server where the
repository is located.

Chapter 10. Processing options 385

 Command line:
The repository, rep_server1, is located on the FastBack Disaster Recovery Hub, myFbDrHub.

dsmc archive fastback -fbpolicyname="Policy 1"

-fbserver=myFbDrHub
-fbreposlocation=\\myFbDrHub\rep_server1

The FastBack server name, -myFbDrHub is the short host name of the FastBack Disaster Recovery
Hub server where the repository is located
The -fbreposlocation specifies the location of the repository. The repository location is required.
If you do not provide the repository location, the command fails.
-fbserver should point to the short host name of the FastBack DR hub in this case.
Command line:
Archive all volumes protected by FastBack policy named policy1 from the FastBack server named
basil:

dsmc archive fastback -Fbpolicyname=policy1

-FBServer=basil -ARCHMC="my_tsm_mgmt_class"
-fbreposlocation=basil@WORKGROUP

Fbvolumename
Use the fbvolumename option with the backup fastback or archive fastback commands.
The fbvolumename option is the name of one or more comma-separated Tivoli Storage Manager
FastBack volumes to back up or archive from the backup proxy. Values for the fbvolumename option are
not valid if more than one FastBack client is specified in the fbclientname option.
If you specify multiple FastBack clients in the fbclientname option, you cannot specify values for the
fbvolumename option.

Supported Clients
This option is valid for Linux x86_64 clients.

Options File
None. You can specify this option only on the command line.

Syntax
,

FBVolumename volume_name

Parameters
volume_name
Specifies the name of the Tivoli Storage Manager FastBack volumes. You can specify up to 10
FastBack volume names.
Important:
When specifying the archive fastback or backup fastback command:
1. At least one FBpolicyName is always required.
2. You can specify up to 10 values for FBPolicyName, if no values are specified for both FBClientName
and FBVolumeName.
3. When you specify a FBClientName value, there must be only one value for FBPolicyName.

386 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 4. You can specify up to 10 values for FBClientName if only one PolicyName is specified, and no values
for FBVolumeName are specified.
5. When you specify the FBVolumeName option, you can have only one FBPolicy, and only one
FBCLientName specified. You must specify exactly one FBClientName. It cannot be omitted.
6. You can specify multiple FBVolumeNames if condition 5 is satisfied.
7. You must specify the FBReposLocation option.

Examples
Command line:

dsmc backup fastback -fbpolicyname=Policy1 -fbclientname=client1

-fbvolumename=data1,data2 -fbserver=myFbDrHub
-fbreposlocation=\\myFbDrHub\rep_server1

Backs up volumes data1 and data2 from FastBack client client1 found in policy Policy1.

Filelist
Use the filelist option to process a list of files.
You can use the filelist option with the following commands:
• archive
• backup group
• delete archive
• delete backup
• expire
• incremental
• query archive
• query backup
• restore
• retrieve
• selective
The backup-archive client opens the file you specify with this option and processes the list of files within
according to the specific command. Except for the restore and retrieve commands, when you use the
filelist option, the client ignores all other file specifications on the command line.
The files (entries) listed in the filelist must adhere to the following rules:
• Each entry must be a fully-qualified or a relative path to a file or directory. Note that if you include a
directory in a filelist entry, the directory is backed up, but the contents of the directory are not.
• Each path must be specified on a single line. A line can contain only one path.
• Paths must not contain control characters, such as 0x18 (CTRL-X), 0x19 (CTRL-Y) and 0x0A (newline).
• By default, paths must not contain wildcard characters. Do not include asterisk (*) or question marks (?)
in a path.
This restriction can be overridden if you enable the option named wildcardsareliteral. For more
information about that option, see “Wildcardsareliteral” on page 583.
• The filelist can be an MBCS file or a Unicode file with all Unicode entries. For Mac OS X, the filelist can
be encoded in the current operating system language or UTF-16.
• If it is set, the client option called quotessareliteral allows quotation marks in a file specification
to be interpreted literally, as quotation marks and not as delimiters. For more information about that
option, see “Quotesareliteral” on page 465. If quotesareliteral and wildcardsareliteral are
not set, normal quotation mark and wildcard processing is used.

Chapter 10. Processing options 387

 • Quotation mark and wildcard processing works as described in the following list:
– If a path or file name contains a space, enclose the entire path in quotation marks (") or single
quotation marks ('). For example "C:\My Documents\spreadsheet.xls" or
'C:\My documents\spreadsheet.xls'.
– If a path contains one or more single quotation marks ('), enclose the entire entry in quotation marks
("). If a path contains one or more quotation marks, enclose the entire path in single quotation marks.
File list processing does not support paths that include a mix of quotation marks and single quotation
marks.
The following examples illustrate the correct and incorrect use of quotation marks and single
quotation marks in paths.
This path example contains a single quotation mark, so the path must be enclosed in quotation
marks:

"/home/gatzby/mydir/gatzby's_report.out"

This path example contains quotation marks, so it must be enclosed in single quotation marks:

'/home/gatzby/mydir/"top10".out'

This path example contains a space character, so it must be enclosed in either quotation marks or
single quotation marks:

"/home/gatzby/mydir/top 10.out"

or

'/home/gatzby/mydir/top 10.out'

This path example is not supported for filelist processing because it contains unmatched delimiters ("
and ’):

/home/gatzby/mydir/andy's_"top 10" report.out

These paths are not supported for filelist processing because they contain wildcard characters:

/home/gatzby*
/home/*/20??.txt

• Any IBM Spectrum Protect filelist entry that does not comply with these rules is ignored.
The following are examples of valid paths in a filelist:

/home/dir/file1
/usr/tivoli/file2
/usr/avi/dir1
/fs1/dir2/file3
"/fs2/Ha Ha Ha/file.txt"
"/fs3/file.txt"

To override standard processing of quotation marks and wildcard characters, see “Quotesareliteral” on
page 465 and “Wildcardsareliteral” on page 583.
You can use the filelist option during an open file support operation. In this case, the client processes
the entries in the filelist from the virtual volume instead of the real volume.
If an entry in the filelist indicates a directory, only that directory is processed and not the files within the
directory.
If the file name (the filelistspec) you specify with the filelist option does not exist, the command
fails. The client skips any entries in the filelist that are not valid files or directories. The client logs errors
and processing continues to the next entry.

388 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Use file specifications with the restore and retrieve commands to denote the destination for the
restored filelist entries. For example, in the following restore command, the file specification /user/
record/ represents the restore destination for all entries in the filelist.

restore -filelist=/home/dir/file3 /usr/record/

However, in the following selective command, the file specification /usr/record/ is ignored.

selective -filelist=/home/dir/file3 /usr/record/

If you specify a directory in a filelist for the delete archive or delete backup command, the
directory is not deleted. filelists that you use with the delete archive or delete backup command
should not include directories.
The entries in the list are processed in the order they appear in the filelist. For optimal processing
performance, pre-sort the filelist by file space name and path.
Note: The client might back up a directory twice if the following conditions exist:
• The filelist contains an entry for the directory
• The filelist contains one or more entries for files within that directory
• No backup of the directory exists
For example, your filelist includes the entries /home/dir/file1 and /home/dir. If the /dir directory
does not exist on the server, the /home/dir directory is sent to the server a second time.

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
FILEList = filelistspec

Parameters
filelistspec
Specifies the location and name of the file that contains the list of files to process with the command.
Note: When you specify the filelist option on the command line, the subdir option is ignored.

Examples
Command line:
sel -filelist=/home/avi/filelist.txt
Related reference
“Quotesareliteral” on page 465
The quotesareliteral option specifies whether single quotation marks (') or double quotation marks
(") are interpreted literally, when they are included in a file list specification on a filelist option.
“Wildcardsareliteral” on page 583
The wildcardsareliteral option specifies whether question marks (?) and asterisks (*) are
interpreted literally, when they are included in a file list specification on a filelist option.

Filename
Use the filename option with the query systeminfo command to specify a file name in which to store
information.
You can store information gathered from one or more of the following items:
• DSMOPTFILE - The contents of the dsm.opt file.

Chapter 10. Processing options 389

 • DSMSYSFILE - The contents of the dsm.sys file.
• ENV - Environment variables.
• ERRORLOG - The IBM Spectrum Protect error log file.
• FILE - Attributes for the file name that you specify.
• INCLEXCL - Compiles a list of include-exclude in the order in which they are processed during backup
and archive operations.
• OPTIONS - Compiled options.
• OSINFO - Name and version of the client operating system (includes ULIMIT information for UNIX and
Linux).
• POLICY - Policy set dump.
• SCHEDLOG - The contents of the schedule log (usually dsmsched.log.
• CLUSTER - AIX 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.

Syntax
FILEName = outputfilename

Parameters
outputfilename
Specifies a file name in which to store the information. If you do not specify a file name, by default the
information is stored in the dsminfo.txt file.

Examples
Command line:
query systeminfo dsmoptfile errorlog -filename=tsminfo.txt
Related information
“Console” on page 328

Filesonly
The filesonly option restricts backup, restore, retrieve, or query processing to files only.
You cannot restore or retrieve directories from the IBM Spectrum Protect server when using the
filesonly option with the restore or retrieve commands. However, directories with default
attributes are created, if required, as placeholders for files that you restore or retrieve.
You can also use the filesonly option with the following commands:
• archive
• incremental
• query archive
• query backup

390 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • restore
• restore backupset
• restore group
• retrieve
• selective

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
FILESOnly

Parameters
There are no parameters for this option.

Examples
Command line:
dsmc incremental -filesonly

Followsymbolic
During a backup operation, the followsymbolic option specifies whether you want to use a symbolic
link as a virtual mount point. During a restore or retrieve operation, the followsymbolic option
specifies how the backup-archive client restores a directory whose name matches a symbolic link on the
restore target file system.
For backup operations, the followsymbolic option can influence the virtualmountpoint option
setting. If you use the virtualmountpoint option to specify a symbolic link as a virtual mount point,
you must also set the followsymbolic option.
During restore and retrieve operations, followsymbolic can influence how the client handles a
symbolic link on the file system. Set followsymbolic only when the client attempts to restore a
directory whose name matches a symbolic link on the restore target file system.
If you specify followsymbolic=no (the default), the client does not restore the contents of the
directory, but returns this error message:

ANS4029E Error processing 'filespace name path-name file-name':

unable to build a directory path; a file exists with the same name
as a directory.

If you specify followsymbolic=yes, the client restores the contents of the directory to the target of the
symbolic link.
For example, assume the client backed up a file with this path: /fs1/dir1/subdir1/file1. Assume
also that a symbolic link /fs1/dir1, that exists on the restore target file system, links to the directory /
fs88/dir88/subdir88. Restore the file with the command:

restore /fs1/dir1/subdir1/file1

If you specify followsymbolic=no, the client does not restore the file, but returns the preceding error
message. If you specify followsymbolic=yes, the client restores file1 to the /fs88/dir88/
subdir88/subdir1/file1 directory.
If you restore a symbolic link (not a directory) whose name matches a symbolic link on the restore target
file system, the client restores the symbolic link.

Chapter 10. Processing options 391

 If a symbolic link is used as a virtual mount point, the path to the link target must be specified by using an
absolute file path.
Use this option with the restore and retrieve commands, or in the client user-options file (dsm.opt).

Supported Clients
This option is valid for all UNIX clients except Mac OS X.

Options File
Place this option in the client options file (dsm.opt).

Syntax
No
FOLlowsymbolic
Yes

Parameters
No
Do not back up a virtual mount point that is a symbolic link. Do not restore a directory if the restore
target file system contains a symbolic link with matching name. This is the default.
Yes
Restore the contents of a directory to the target of a symbolic link.

Examples
Options file:
followsymbolic Yes
Command line:
-fol=Yes
Related information
During archive, the“Archsymlinkasfile” on page 308 option determines how the client handles symbolic
links.
For operating systems other than Mac OS X, see “Back up symbolic links” on page 207 for more
information about how the backup-archive client handles symbolic links.

Forcefailover
The forcefailover option enables the client to immediately fail over to the secondary server.
You can use the forcefailover option to immediately connect to the secondary server, even if the
primary server is still online. For example, you can use this option to verify that the backup-archive client
is failing over to the expected secondary server.
Do not edit this option during normal operations.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client-system options file (dsm.sys).

392 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Syntax
No
FORCEFAILOVER
Yes

Parameters
Yes
Specifies that the client immediately connects to the secondary server.
No
Specifies that the client fails over to the secondary server during the next logon if the primary server is
unavailable. This value is the default.

Examples
Options file:
FORCEFAILOVER yes
Command line:
-FORCEFAILOVER=yes
Related concepts
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
Configuring the client for automated failover
You can manually configure the client to automatically fail over to the secondary server.

Fromdate
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.
Files that were backed up or archived before this date and time are not included, although older
directories might be included, if necessary, to restore or retrieve the files.
Use the fromdate option with the following commands:
• delete backup
• query archive
• query backup
• restore
• restore group
• retrieve

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
FROMDate = date

Chapter 10. Processing options 393

 Parameters
date
Specifies the date from which you want to search for backup copies or archived files. Enter the date in
the format you selected with the dateformat option.
When you include dateformat with a command, it must precede the fromdate, pitdate, and
todate options.

Examples
Command line:
dsmc query backup -fromdate=12/11/2003 "/Users/van/Documents/*"
Command line:
dsmc query backup -fromdate=12/11/2003 /home/dilbert/*

Fromnode
The fromnode option permits one node to perform commands for another node. A user on another node
must use the set access command to permit you to query, restore, or retrieve files for the other node.
Use the fromnode option with the following commands:
• query archive
• query backup
• query filespace
• query image
• query mgmtclass
• restore
• restore group
• restore image
• retrieve

Supported Clients
This option is valid for all clients.

Syntax
FROMNode = node

Parameters
node
Specifies the node name on a workstation or a file server whose backup copies or archived files you
want to access.

Examples
Command line:
dsmc query archive -fromnode=bob -subdir=yes "/Users/van/Documents/*"
Command line:
dsmc query archive -fromnode=bob -subdir=yes "/home/jones/*"

394 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Fromowner
The fromowner option specifies an alternate owner from which to restore backup versions or archived
files or images. The owner must give access to another to use the files or images.
For example, to restore files from the /home/devel/proja directory belonging to usermike on system
puma, and place the restored files in a directory you own named /home/id/proja, enter the following
command:

dsmc restore -fromowner=usermike -fromnode=puma /home/devel/proja/

/home/id/proja/

Note: Archiving image restores does not apply to Mac OS X operating systems.
Non-root users can specify fromowner=root to access files owned by the root user if the root user has
granted them access.
Note: If you specify the fromowner option without the fromnode option, the active user must be on the
same node as the fromowner user.
Use the fromowner option with the following commands:
• query archive
• query backup
• query group
• query image
• restore
• restore image
• restore group
• retrieve

Supported Clients
This option is valid for all UNIX and Linux clients.

Syntax
FROMOwner = owner

Parameters
owner
Name of an alternate owner.

Examples
Command line:
dsmc query archive "/home/id/proja/*" -fromowner=mark

Fromtime
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.
The backup-archive client ignores this option if you do not specify the fromdate option.
Use the fromtime option with the following commands:
• delete backup
• query archive
• query backup

Chapter 10. Processing options 395

 • restore
• restore group
• retrieve

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
FROMTime = time

Parameters
time
Specifies a beginning time on a specific date from which you want to search for backed up or archived
files. If you do not specify a time, the time defaults to 00:00:00. Specify the time in the format you
selected with the timeformat option.
When you include the timeformat option in a command, it must precede the fromtime, pittime,
and totime options.

Examples
Command line:
dsmc q b -timeformat=4 -fromt=11:59AM -fromd=06/30/2003 -tot=11:59PM -
tod=06/30/2003 /home/*

Groupname
Use the groupname option with the backup group command to specify the name for a group. You can
only perform operations on new groups or the current active version of the group.

Supported Clients
This option is valid for all UNIX and Linux clients except Mac OS X.

Syntax
GROUPName = name

Parameters
name
Specifies the name of the group which contains the files backed up using the filelist option.
Directory delimiters are not allowed in the group name since the group name is not a file specification,
but a name field.

Examples
Command line:

backup group -filelist=/home/dir1/filelist1 -groupname=group1

-virtualfsname=/virtfs -mode=full

Groups (deprecated)
This option is deprecated.

396 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Host
The host option specifies the target ESX server location where the new virtual machine is created during a
VMware restore operation.
Use this option on restore vm commands to specify the ESX host server to restore the data to.

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 the ESX server named vmesxbld1.

restore vm -host=vmesxbld1.us.acme.com

Httpport
The httpport option specifies a TCP/IP port address for the web client.

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 system-options file (dsm.sys) within a server stanza. You can set this option
on the Web Client tab, in the HTTP Port field of the Preferences editor.

Syntax
HTTPport port_address

Parameters
port_address
Specifies the TCP/IP port address that is used to communicate with the web client. The range of
values is 1000 through 32767; the default is 1581.

Examples
Options file:
httpport 1502
Command line:
Does not apply.

Hsmreparsetag
The hsmreparsetag option specifies a unique reparse tag that is created by an HSM product installed on
your system.
Many HSM products use reparse points to retrieve or recall migrated files. After a file is migrated, a small
stub file, with the same name as the original file, is left on the file system. The stub file is a reparse point
that triggers a recall of the original file when a user or application accesses the stub file. The reparse point
includes a unique identifier called a reparse tag to identify which HSM product migrated the file.
If the IBM Spectrum Protect backup-archive client does not recognize the reparse tag in a stub file, the
Backup-Archive Client causes the HSM product to recall the original file. You can prevent files from being
recalled if you specify the reparse tag with the hsmreparsetag option.
The backup-archive client recognizes the reparse tag of HSM products from the following companies:

Chapter 10. Processing options 397

 • International Business Machines Corp.
• Wisdata System Co. Ltd.
• BridgeHead Software Ltd.
• CommVault Systems, Inc.
• Data Storage Group, Inc.
• Enigma Data Solutions, Ltd.
• Enterprise Data Solutions, Inc.
• Global 360
• GRAU DATA AG
• Hermes Software GmbH
• Hewlett Packard Company
• International Communication Products Engineering GmbH
• KOM Networks
• Memory-Tech Corporation
• Moonwalk Universal
• Pointsoft Australia Pty. Ltd.
• Symantec Corporation
If the HSM product you use is not in the preceding list, use the hsmreparsetag option to specify the
reparse tag. Ask your HSM product vendor for the reparse tag used by the product.

Supported clients
This option is valid for all Windows clients.

Option file
Place this option in the client options file (dsm.opt).

Syntax
HSMREPARSETAG reparse_tag_value

Parameters
reparse_tag_value
A decimal (base 10) or hexadecimal (base 16) value that specifies the reparse tag.

Examples
Options file:
Specify an HSM reparse tag in decimal format:

hsmreparsetag 22

Specify an HSM reparse tag in hexadecimal format:

hsmreparsetag 0x16

Command line:
Does not apply.

398 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Ieobjtype
Use the ieobjtype option to specify an object type for a client-side data deduplication operation within
include-exclude statements.
The ieobjtype option is an additional parameter to the include.dedup or exclude.dedup options.

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 system-options file (dsm.sys). You can set this option on the Include/Exclude tab
of the Preferences editor. The option can be set in the client option set on the IBM Spectrum Protect
server.

Syntax
File

IEObjtype Image

Parameters
File
Specifies that you want to include files for, or exclude files from, client-side data deduplication
processing. File is the default.
Image
Specifies that you want to include images for, or exclude images from, client-side data deduplication
processing.

Examples
Options file:
exclude.dedup /home/*/* ieobjtype=image
Command line:
Does not apply.
Related reference
“Exclude options” on page 374
Use the exclude options to exclude objects from backup, image, or archive services.
“Include options” on page 403
The include options specify objects that you want to include for backup and archive services.

Ifnewer
The ifnewer option replaces an existing file with the latest backup version only if the backup version is
newer than the existing file.
Only active backups are considered unless you also use the inactive or latest options.
Note: Directory entries are replaced with the latest backup version, whether the backup version is older
or newer than the existing version.
Use the ifnewer option with the following commands:
• restore
• restore backupset
• restore group
• retrieve

Chapter 10. Processing options 399

 Note: This option is ignored if the replace option is set to No.

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
IFNewer

Parameters
There are no parameters for this option.

Examples
Command line:
dsmc restore "/Users/grover/Documents/*" -sub=y -rep=y -ifnewer
dsmc restore "/home/grover/*" -sub=y -rep=y -ifnewer

Imagegapsize
Use the imagegapsize option with the backup image command, in the options file, or with the
include.image option to specify the minimum size of empty regions on a volume that you want to skip
during image backup.
Use this option for LAN-based and LAN-free image backup.
For example, if you specify a gap size of 10, this means that an empty region on the disk that is larger than
10 KB in size is not backed up. Gaps that are exactly 10 KB are backed up. Empty regions that are exactly
10 KB and that are smaller than 10 KB is backed up, even though they do not contain data. However, an
empty region that is smaller than 10 KB is backed up, even though it does not contain data. A smaller
image gap size means less data needs to be transferred, but with potentially decreased throughput. A
larger image gap size results in more data being transferred, but with potentially better throughput.

Supported Clients
This option is valid for AIX, Linux, and JFS2 clients only. The IBM Spectrum Protect API does not support
this option.

Options File
Place this option in the server stanza of the client systems options file (dsm.sys), or in the
include.image statement in the dsm.sys file.

Syntax
IMAGEGapsize size

Parameters
size
Specifies the minimum size of empty regions in an AIX JFS2 file system that should be skipped during
an image backup. You can specify k (kilobytes) m (megabytes) or g (gigabytes) qualifiers with the
value. Without a qualifier, the value is interpreted in kilobytes. Valid values are 0 through
4294967295 KB. If you specify a value of 0, all blocks, including unused blocks at the end of the
volume, is backed up. If you specify any value other than 0, unused blocks at the end of the volume
are not backed up. For LAN-based and LAN-free image backup the default value is 32 KB. This option
is applicable to both static and snapshot-based image backup.

400 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Note: This option is valid for AIX JFS2 file systems. If you specify an imagegapsize that is greater
than 0 for a file system other than AIX JFS2, you get a warning message.

Examples
Options file:
Add the following to the server stanza in the dsm.sys file: imagegapsize 1m
Include-exclude list example: include.image /kalafs1 imagegapsize=-128k
Command line:
-imagegapsize=64k

Imagetofile
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 if bad sectors are present on the target volume, or if you
want to manipulate the image data. Later, you can use a data copy utility of your choice to transfer the
image from the file to a disk volume.
Linux supports mounting an image file as a logical volume, so you can get access to file data within the
image. The following are some examples:
• The file system /usr has been backed up by the backup-archive client. The following command
restores the file system image to the file /home/usr.img:

# dsmc restore image /usr /home/usr.img -imagetofile

• To mount the image file at the /mnt/usr directory, the following mount command can be executed:

# mount /home/usr.img /mnt/usr -o loop=/dev/loop0

Now the image contents are available from /mnt/usr as if a regular file system was mounted at that
directory.

Supported Clients
This option is valid only for AIX, Oracle Solaris, and all Linux clients. The IBM Spectrum Protect API does
not support this option.

Syntax
IMAGETOfile

Parameters
There are no parameters for this option.

Examples
Command line:
dsmc restore image /usr /home/usr.img -imagetofile

Inactive
Use the inactive option to display both active and inactive objects.
You can use the inactive option with the following commands:
• delete group
• query backup

Chapter 10. Processing options 401

 • query group
• query image
• query nas
• restore
• restore group
• restore image
• restore nas
Important: When using the inactive option during a restore operation, also use the pick or some other
filtering option because, unlike the latest option, all versions are restored in an indeterminate order.
This option is implicit when pitdate is used.

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
INActive

Parameters
There are no parameters for this option.

Examples
Command line:
dsmc restore "/Users/zoe/Documents/*" -inactive -pick
Command line:
dsmc restore "/home/zoe/*" -inactive -pick

Inclexcl
The inclexcl option specifies the path and file name of an include-exclude options file.
Multiple inclexcl statements are permitted. However, you must specify this option for each include-
exclude file.
Ensure that you store your include-exclude options file in a directory to which all users have read access,
such as /etc.
When processing occurs, the include-exclude statements within the include-exclude file are placed in the
list position occupied by the inclexcl option, in the same order, and processed accordingly.
If you have the HSM client installed on your workstation, you can use an include-exclude options file to
exclude files from backup and space management, from backup only or from space management only.

Supported Clients
This option is valid for all clients. The server can also define this option.

Options File
Place this option in the dsm.sys file within a server stanza. You can set this option on the Include-
Exclude tab of the Preferences editor.

Syntax
INCLExcl filespec

402 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Parameters
filespec
Specifies the path and file name of one include-exclude options file.

Examples
Options file:

INCLExcl /Users/user1/Documents/backup.excl

inclexcl /usr/dsm/backup.excl
inclexcl /etc/inclexcl.def

Command line:
Does not apply.
Related information
For more information about creating an include-exclude options file, see “Creating an include-exclude
list ” on page 112.

Considerations for Unicode-enabled clients

An include-exclude file can be in Unicode or non-Unicode format.
If the codeset used to create an include-exclude list file does not match the codeset used on the client
computer, characters in the file that cannot be mapped by the client’s codeset to a displayable character
cannot be processed when backups are performed.
Using Unicode encoding for files containing include-exclude lists eliminates the unmapped character
problem, so you no longer need to use wildcard characters as substitutes for the unrecognized
characters.
Mac users: Create an include-exclude file in Unicode format by performing the following steps:
1. Open TextEdit. Click Format > Make PlainText.
2. Enter your include and exclude statements.
3. Click File and then click Save As.
4. From PlainText Encoding, select Unicode (UTF-8) or Unicode (UTF-16), specify the file and target
directory, and then save the file. Do not add the .txt extension.
5. Place an inclexcl option specifying the include-exclude file you just created in your dsm.sys file.
6. Restart the backup-archive client.

Include options
The include options specify objects that you want to include for backup and archive services.
The include options specify any of the following:
• Objects within a broad group of excluded objects that you want to include for backup and archive
services.
• Objects within a broad group of excluded objects that you want to include for backup, archive, image,
and space management services.
• Files that are included for backup or archive processing that you want to include for encryption
processing.
• Files that are included for backup or archive processing that you also want to include for compression
processing.
• Objects to which you want to assign a specific management class.
• A management class to assign to all objects to which you do not explicitly assign a management class.
• File spaces to which you want to assign memory-efficient backup processing

Chapter 10. Processing options 403

 • File spaces where you want to use the diskcachelocation option to cause specific file systems to
use different, specific locations for their disk cache.
If you do not assign a specific management class to objects, the default management class in the active
policy set of your policy domain is used. Use the query mgmtclass command to display information
about the management classes available in your active policy set.
Remember: The backup-archive client compares the files it processes against the patterns specified in
the include-exclude statements, reading from the bottom to the top of the options file.
Note:
1. The exclude.fs and exclude.dir statements override all include statements that match the
pattern.
2. The server can also define these options with the inclexcl option.

Supported Clients
This option is valid for all clients. The server can also define include.fs.nas.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set these
options on the Include-Exclude tab in the Preferences editor.

Syntax
options pattern
optional_parameter

include, include.backup, include.file

Use these options to include files or assign management classes for backup processing.
The include option affects archive and backup processing. If you want to assign different
management classes for archive and backup processing, always specify include.archive and
include.backup with their own management classes. In this example, the archmc management
class is assigned when an archive operation is performed. The management class is assigned when an
archive operation is performed because include.backup is used only for backup processing, and
not for archive processing.

include.archive /home/test/* archmc

include.backup /home/test/*

include.archive
Includes files or assigns management classes for archive processing.
include.attribute.symlink
Includes a file or a group of files that are symbolic links or aliases, within a broad group of excluded
files for backup processing only.
Note: For Mac OS X, aliases are included.
include.compression
Includes files for compression processing if you set the compression option to yes. This option
applies to backups and archives.
include.dedup
Includes files for client-side data deduplication. To control a client-side data deduplication operation,
specify ieobjtype as the value of the include.dedup option. By default, all data deduplication-
eligible objects are included for client-side data deduplication.
Valid ieobjtype parameters are:
File

404 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Image
The default is File.
include.encrypt
Includes the specified files for encryption processing. By default, the client does not perform
encryption processing.
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 does not occur.
Restrictions:
• Encryption is not compatible with client-side deduplication. Files that are included for encryption
are not deduplicated by client-side deduplication.
• Client encryption with the include.encrypt option is no longer supported for LAN-free backup
and archive operations to the IBM Spectrum Protect server V8.1.1 and later levels, or V7.1.8 and
later V7 levels. LAN-free restore and retrieve operations of encrypted backup versions and archive
copies continue to be supported. If you need to encrypt data by using the include.encrypt
option, in which data is encrypted before it is sent to the server, use LAN-based backup or archive
operations.
• 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.
• Encryption is not compatible with the IBM Spectrum Protect for Virtual Environments Data
Protection for VMware Recovery Agent. If the client is configured for encryption, you can use the
client to restore backups that were created with the V7.1 client full or incremental backup modes
(MODE=Full and MODE=Incremental). However, you cannot use the Recover Agent to restore the
encrypted backups.
include.fs
For AIX JFS2 file systems: Use the snapshotcachesize option in the dsm.sys file or with the
include.fs option, to specify an appropriate snapshot size so that all old data blocks can be stored
while the snapshot-based file backup or archive occurs.
To control how the client processes your file space for incremental backup, you can specify these
additional options in your dsm.sys file, as values of the include.fs option: diskcachelocation
and memoryefficientbackup.
Each of the include.fs, memoryefficientbackup and diskcachelocation options must be on
the same line in the options file.

include.fs /home
memoryefficientbackup=diskcachemethod
diskcachelocation=/usr
include.fs /usr
memoryefficientbackup=diskcachemethod
diskcachelocation=/home
include.fs /Volumes/hfs3
memoryefficientbackup=diskcachemethod
diskcachelocation=/Volumes/hfs2
AIX JFS2 filesystems only: include.fs
/kalafs1 snapshotproviderfs=JFS2

If these options appear both in the options file and an include.fs option, the include.fs values
are used for the specified file space in place of any values in an option file or on the command line.
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 the client saves Table of Contents (TOC) information during a
NAS file system image backup, using the toc option with the include.fs.nas option in your
dsm.sys file. This option is only valid for AIX and Solaris clients.

Chapter 10. Processing options 405

 include.image
Includes a file space or logical volume, or assigns a management class when used with the backup
image command. The backup image command ignores all other include options.
For Linux x86_64 clients: Use the snapshotcachesize option in these situations:
• With the backup image command
• In the dsm.sys file
• With the include.image option
Using the snapshotcachesize option in these situations lets you specify an appropriate snapshot
size, so that all old data blocks can be stored while the image backup occurs.
A snapshot size of 100 percent ensures a valid snapshot.
For AIX JFS2 file systems: Use the snapshotcachesize option in these situations:
• With the backup image command
• In the dsm.sys file
• With the include.image option
Using the snapshotcachesize option in these situations lets you specify an appropriate snapshot
size, so that all old data blocks can be stored while the image backup occurs.
This option is valid for AIX, Linux, and Oracle Solaris clients.

Parameters
pattern
Specifies the objects to include for backup or archive processing or to assign a specific management
class.
Note: For NAS file systems: You must prefix the NAS 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 identified refers to the NAS node name specified in the client system-options file (dsm.sys) or
on the command line.
If the pattern begins with a single or double quotation mark, or contains any embedded blanks or
equal signs, you must surround the value in either single (') or double (") quotation marks. The
opening and closing quotation marks must be the same type of quotation marks.
For the include.image option, the pattern is the name of a mounted file system or raw logical
volume.

optional_parameter
management_class_name
Specifies the name of the management class to assign to the objects. If a management class is not
specified, the default management class is used. To associate a management class with a backup
group on an include statement, use the following syntax:

include virtual_filespace_name\group_name management_class_name

where:
virtual_filespace_name
Specifies the name of the IBM Spectrum Protect server virtual filespace that you associated with
the group, on the Backup Group command.
group_name
Is the name of the group that you created when you ran the Backup Group command.
management_class_name
Is the name of the management class to associate with the files in the group.

406 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 For example, a group named MyGroup is stored in a virtual file space called MyVirtualFileSpace.
To associate a management class, named TEST, with the group, use the following syntax:

include MyVirtualFileSpace/MyGroup TEST

Table 75. Other optional parameters

optional_parameter Use with option
ieobjtype include.dedup

“Ieobjtype” on page 399

memoryefficientbackup include.fs

“Memoryefficientbackup” on page 434

diskcachelocation include.fs

“Diskcachelocation” on page 348

dynamicimage include.image

“Dynamicimage” on page 362

postsnapshotcmd include.image

“Postsnapshotcmd” on page 455

presnapshotcmd include.image

“Presnapshotcmd” on page 461

snapshotcachesize include.image

“Snapshotcachesize” on page 502

snapshotproviderfs include.image

“Snapshotproviderfs” on page 503

snapshotproviderimage include.image
“Snapshotproviderimage” on page 504

Examples
Options file:

include /home/proj/text/devel.*
include /home/proj/text/* textfiles
include * managall
include /WAS_ND_NDNODE mgmtclass
include /WAS_APPNODE mgmtclass
include.image /home
include.archive /home/proj/text/
* myarchiveclass
include.backup /home/proj/text/
* mybackupclass
include.compression /home/proj/text/
devel.*
include.encrypt /home/proj/gordon/*
include.fs.nas netappsj/vol/vol0
homemgmtclass

Chapter 10. Processing options 407

 include.dedup /Users/Administrator/Documents/Important/.../*

AIX only:

include.image /home
MGMTCLASSNAME
snapshotproviderimage=JFS2
snapshotcachesize=40
include.image /home
snapshotproviderimage=NONE
include.fs /kalafs1
snapshotproviderfs=JFS2

LINUX only:

include.image /home
snapshotproviderimage=LINUX_LVM
include.image /myfs1 dynamicimage=yes
include.image /home MGMTCLASSNAME
snapshotproviderimage=NONE
include.image /myfs1 dynamicimage=yes
include.attribute.symlink /home/spike/.../*
include.fs /usr
memoryefficientbackup=diskcachemethod

Command line:
Does not apply.
Related reference
Snapshotcachesize
Use the snapshotcachesize option to specify an appropriate size to create the snapshot.
Toc
Use the toc option with the backup nas command or the include.fs.nas option to specify whether
the backup-archive client saves table of contents (TOC) information for each file system backup.
Related information
mmbackup command: IBM Spectrum Protect requirements
Guidance for integrating IBM Spectrum Scale AFM with IBM Spectrum Protect
Considerations for using IBM Spectrum Protect include and exclude options with IBM Spectrum Scale
mmbackup command

Controlling symbolic link and alias processing

IBM Spectrum Protect treats symbolic links and aliases (aliases apply to Mac OS X only) as actual files
and backs them up. However, the file referenced by the symbolic link is not backed up.
In some cases symbolic links and aliases can be easily recreated and need not be backed up. In addition,
backing up these symbolic links or aliases can increase backup processing time and occupy a substantial
amount of space on the IBM Spectrum Protect server.
You can use the exclude.attribute.symlink option to exclude a file or a group of files that are
symbolic links or aliases from backup processing. If necessary, you can use the
include.attribute.symlink option to include symbolic links or aliases within broad group of
excluded files for backup processing. For example, to exclude all symbolic links or aliases from backup
processing, except those that exist under the /home/spike directory, enter these statements in your
dsm.sys file:

exclude.attribute.symlink /.../*
include.attribute.symlink /home/spike/.../*

Related reference
“Exclude options” on page 374

408 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Use the exclude options to exclude objects from backup, image, or archive services.

Compression and encryption backup processing

Consider the following information if you want to include specific files or groups of files for compression
and encryption processing during a backup or archive operation.
• You must set the compression option to yes to enable compression processing. If you do not specify
the compression option or you set the compression option to no, the backup-archive client does not
perform compression processing.
• The client processes exclude.fs, exclude.dir, and other include-exclude statements first. The
client then considers any include.compression and include.encrypt statements. For example,
consider the following include-exclude list:

exclude /home/jones/proj1/file.txt
include.compression /home/jones/proj1/file.txt
include.encrypt /home/jones/proj1/file.txt

The client examines the exclude /home/jones/proj1/file.txt statement first and determines
that /home/jones/proj1/file.txt is excluded from backup processing and is, therefore, not a
candidate for compression and encryption processing.
• Include-exclude compression and encryption processing is valid for backup and archive processing
only.
• Client encryption with the include.encrypt option is no longer supported for LAN-free backup and
archive operations to the IBM Spectrum Protect server V8.1.1 and later levels, or V7.1.8 and later V7
levels. LAN-free restore and retrieve operations of encrypted backup versions and archive copies
continue to be supported. If you need to encrypt data by using the include.encrypt option, in which
data is encrypted before it is sent to the server, use LAN-based backup or archive operations.
Related reference
“Compression” on page 326
The compression option compresses files before you send them to the server.

Processing NAS file systems

Use the include.fs.nas option to bind a management class to NAS file systems and to control whether
Table of Contents information is saved for the file system backup.
A NAS file system specification uses the following conventions:
• NAS nodes represent a new node type. The NAS node name uniquely identifies a NAS file server and its
data to the backup-archive client. You can prefix the NAS 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.
• Regardless of the client operating system, NAS file system specifications use the forward slash (/)
separator, as in this example: /vol/vol0.
Use the following syntax:
pattern mgmtclassname toc=value

Where:
pattern
Specifies the objects to include for backup services, to assign a specific management class, or to
control TOC creation. You can use wildcards in the pattern.
mgmtclassname
Specifies the name of the management class to assign to the objects. If a management class is not
specified, the default management class is used.
toc=value
For more information, see “Toc” on page 531.

Chapter 10. Processing options 409

 Example 1: To assign a management class to the /vol/vol1 file system of a NAS node that is called
netappsj, specify the following include statement:

include.fs.nas netappsj/vol/vol1 nasMgmtClass toc=yes

Example 2: To assign the same management class to all paths that are subordinate to the /vol/ file
system on a NAS node called netappsj (for example, /vol/vol1, /vol/vol2, and /vol/vol3),
specify the following include statement:

include.fs.nas netappsj/vol/* nasMgmtClass toc=yes

Virtual machine include options

Virtual machine include and exclude options influence the behavior of backup and restore operations for
virtual machines. These options are processed before any command-line options are processed, so that
options on the command line can override options specified on any of the virtual machine include options
or virtual machine exclude options. See the individual option descriptions for information about the
options.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.
Related reference
“Include.vmdisk” on page 411
The INCLUDE.VMDISK option includes a virtual machine (VM) disk in backup operations. If you do not
specify one or more disk labels, all disks in the VM are backed up.
“INCLUDE.VMTSMVSS” on page 418
The INCLUDE.VMTSMVSS option notifies virtual machine applications that a backup is about to occur.
This option allows the application to truncate transaction logs and commit transactions so that the
application can resume from a consistent state when the backup completes. An optional parameter can
be specified to suppress truncation of the transaction logs.
“INCLUDE.VMSNAPSHOTATTEMPTS” on page 416
Use the INCLUDE.VMSNAPSHOTATTEMPTS option to determine the total number of snapshot attempts to
try for a virtual machine (VM) backup operation that fails due to snapshot failure.

Include.vm
For virtual machine operations, this option overrides the management class that is specified on the vmmc
option.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.
The management class specified on the vmmc option applies to all VMware backups.
You can use the include.vm option to override that management class, for one or more virtual
machines. The include.vm option does not override or affect the management class that is specified by
the vmctlmc option. The vmctlmc option binds backed-up virtual machine control files to a specific
management class.

Supported Clients
This option can be used with supported Linux clients that are configured to back up VMware virtual
machines.

Options File
Set this option in the client options file.

410 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Syntax
INCLUDE.VM vmname
mgmtclassname

Parameters
vmname
Required parameter. Specifies the name of a virtual machine that you want to bind to the specified
management class. The name is the virtual machine display name. Only one virtual machine can be
specified on each include.vm statement. However, you can specify as many include.vm
statements as needed to bind each virtual machine to a specific management class.
You can include wildcards in the virtual machine name. An asterisk (*) matches any character string. A
question mark (?) matches a single character. If the virtual machine name contains a space character,
enclose the name in double quotation marks (").
Tip: If the virtual machine name contains special characters, type the question mark wildcard in place
of the special characters when you specify the virtual machine name.
mgmtclassname
Optional parameter. Specifies the management class to use when the specified virtual machine is
backed up. If this parameter is not specified, the management class defaults to the global virtual
machine management class that is specified by the vmmc option.

Examples
Assume that the following management classes exist and are active on the IBM Spectrum Protect server:
• MCFORTESTVMS
• MCFORPRODVMS
• MCUNIQUEVM
Example 1
The following include.vm statement in the client options file binds all virtual machines that have
names that begin with VMTEST to the management class called MCFORTESTVMS:

include.vm vmtest* MCFORTESTVMS

Example 2
The following include.vm statement in the client options file binds a virtual machine that is named
WHOPPER VM1 [PRODUCTION] to the management class called MCFORPRODVMS:

include.vm "WHOPPER VM1 ?PRODUCTION?" MCFORPRODVMS

The virtual machine name must be enclosed in quotation marks because it contains space characters.
Also, the question mark wildcard is used to match the special characters in the virtual machine name.
Example 3
The following include.vm statement in the client options file binds a virtual machine that is named
VM1 to a management class that is named MCUNIQUEVM:

include.vm VM1 MCUNIQUEVM

Include.vmdisk
The INCLUDE.VMDISK option includes a virtual machine (VM) disk in backup operations. If you do not
specify one or more disk labels, all disks in the VM are backed up.
This option is available only if you are using the IBM Spectrum Protect for Virtual Environments licensed
product. For more information about this option, see the IBM Spectrum Protect for Virtual Environments
product documentation on IBM Knowledge Center at http://www.ibm.com/support/knowledgecenter/
SSERB6/welcome.

Chapter 10. Processing options 411

 The INCLUDE.VMDISK option specifies the label of a VM disk to be included in a backup vm operation. If
you include a disk on the backup vm command, the command-line parameters override any
INCLUDE.VMDISK statements in the options file.

INCLUDE.VMDISK for VMware virtual machines

Use the INCLUDE.VMDISK option to include a VMware virtual machine in backup operations.

Supported clients
This option can be used with supported x86_64 Linux clients.

Options file
Set this option in the client options file. Command line parameters override statements in the options file.

Syntax for VMware virtual machines

INCLUDE.VMDISK vmname vmdk_label

Parameters
vmname
Specifies the name of the virtual machine that contains a disk that you want to include in a Backup
VM operation. The name is the virtual machine display name. You can specify only one virtual machine
name on each INCLUDE.VMDISK statement. Specify additional INCLUDE.VMDISK statements for
each virtual machine disk to include.
The virtual machine name can contain an asterisk (*), to match any character string, and question
mark (?) to match any one character. Surround the VM name with quotation marks (" ") if the VM name
contains space characters.
Tip: If the virtual machine name contains special characters, such as bracket characters ([ or ]), the
virtual machine name might not be correctly matched. If a virtual machine name uses special
characters in the name, you might need to use the question mark character (?) to match the special
characters in the VM name
For example, to include Hard Disk 1 in the backup of a virtual machine named "Windows VM3
[2012R2]", use this syntax in the options file: INCLUDE.VMDISK "Windows VM3 ?2012R2?"
"Hard Disk 1"
vmdk_label
Specifies the disk label of the disk that you want to include. Wildcard characters are not allowed. Use
the Backup VM command with the -preview option to determine the disk labels of disks in a given
virtual machine. See "Backup VM" for the syntax.

Examples
Options file
Assume that a virtual machine named vm1 contains four disks, labeled Hard Disk 1, Hard Disk 2, Hard
Disk 3, and Hard Disk 4. To include only disk 2 in a Backup VM operations, specify the following in the
options file:

INCLUDE.VMDISK "vm1" "Hard Disk 2"

Include disks 2 and 3 in Backup VM operations:

INCLUDE.VMDISK "vm1" "Hard Disk 2"

INCLUDE.VMDISK "vm1" "Hard Disk 3"

Command line
Include a single disk when backing up vm1:

412 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 dsmc backup vm "vm1:vmdk=Hard Disk 1"

Include disk 2 and disk 3 on vm1:

dsmc backup vm "vm1:vmdk=Hard Disk 2:vmdk=Hard Disk 3"

Related reference
“Backup VM” on page 608
“Restore VM” on page 681
Use the restore vm command to restore a virtual machine (VM) that was previously backed up.
“Domain.vmfull” on page 355
The domain.vmfull option specifies the virtual machines (VMs) to include in your full virtual machine
image backup operations.
“Exclude.vmdisk” on page 378
The EXCLUDE.VMDISK option excludes a virtual machine disk from backup operations.

Include.vmlocalsnapshot
This option specifies the management class that is applied to local backups of a VMware virtual machine.
The management class defines the retention policies for the local backups.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.
You can use this option only for virtual machines that are stored in a virtual volume (VVOL) datastore.

Supported Clients
This option can be used with supported Linux clients that are configured to back up VMware virtual
machines.

Options File
Set this option in the client options file.

Syntax
INCLUDE.VMLOCALSNAPSHOT vmname
mgmtclassname

Parameters
vmname
Specifies the name of a virtual machine that you want to bind to the specified management class for
local backup operations. The name is the virtual machine display name.
Only one virtual machine can be specified on each INCLUDE.VMLOCALSNAPSHOT statement.
However, you can specify as many INCLUDE.VMLOCALSNAPSHOT statements as needed to bind each
VM to a specific management class.
You can include wildcards in the virtual machine name. An asterisk (*) matches any character string. A
question mark (?) matches a single character. If the virtual machine name contains a space character,
enclose the name in double quotation marks (").
Tip: If the virtual machine name contains special characters, type the question mark wildcard in place
of the special characters when you specify the virtual machine name.
mgmtclassname
Specifies the management class to use for local backups of the virtual machine. If this parameter is
not specified, the management class defaults to the global virtual machine management class that is
specified by the vmmc option.

Chapter 10. Processing options 413

 Examples
Assume that the following management classes exist and are active on the IBM Spectrum Protect server:
• MCFORTESTVMS
• MCFORPRODVMS
• MCUNIQUEVM
Example 1
The following INCLUDE.VMLOCALSNAPSHOT statement in the client options file binds all virtual
machines that have names that begin with VMTEST to the management class called MCFORTESTVMS:

include.vmlocalsnapshot vmtest* MCFORTESTVMS

Example 2
The following INCLUDE.VMLOCALSNAPSHOT statement in the client options file binds a virtual
machine that is named WHOPPER VM1 [PRODUCTION] to the management class called
MCFORPRODVMS:

include.vmlocalsnapshot "WHOPPER VM1 ?PRODUCTION?" MCFORPRODVMS

The virtual machine name must be enclosed in quotation marks because it contains space characters.
Also, the question mark wildcard is used to match the special characters in the virtual machine name.
Example 3
The following INCLUDE.VMLOCALSNAPSHOT statement in the client options file binds a virtual
machine that is named VM1 to a management class that is named MCUNIQUEVM:

include.vmlocalsnapshot VM1 MCUNIQUEVM

Related reference
“Backup VM” on page 608
“Vmmc” on page 564
Use the vmmc option to store virtual machine backups by using a management class other than the
default management class. For VMware VM backups, the vmmc option is valid only if the
vmbackuptype=fullvm option is set.

Include.vmresetcbt
Use the include.vmresetcbt to reset the change block tracking (CBT) mechanism for a virtual
machine (VM) or a group of VMs.
If you need to reset the change block tracking on a VM or set of VMs, use this option to manage which
VMs are reset so that all VMs are not reset at the same time. Managing which VM's change block tracking
is reset is important because resetting change block tracking for a VM forces a full backup of that VM.
While there can be different reasons for resetting change block tracking, one reason is if you suspect that
a snapshot existed at the time change block tracking was initially enabled for a VM. Enabling change block
tracking on Data Protection for VMware means to complete an incremental-forever backup operation.
Enabling change block tracking when a snapshot exists is a known issue with VMware change block
tracking. This known issue might cause incomplete or invalid change blocks information to be returned
during a backup operation. To resolve this issue, you must remove all existing snapshots for a VM, and
reset change block tracking for the VM before you run an incremental-forever backup operation.
Subsequent incremental backups will track the blocks that changed since the last backup operation.
Specify this option only for one-time use for a VM or group of VMs. After you reset change block tracking
for a VM by running an incremental-forever backup operation, remove the include.vmresetcbt option
from the options file. Use this option only if change block tracking needs to be reset for a VM, such as
when one or more third-party or manual snapshots exist on a VM.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

414 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Supported Clients
This option can be used with supported Windows and Linux clients.

Options file
Place this option in the client options file (dsm.opt).

Syntax
INCLUDE.VMResetcbt vmname

Parameters
vmname
Specifies the name of a VM for which you want to reset change block tracking. The name is the VM
display name. This parameter is required.
Only one VM can be specified on each include.vm statement. However, you can specify as many
include.vmresetcbt statements as needed.
You can include wildcards in the VM name. An asterisk (*) matches any character string. A question
mark (?) matches a single character. If the VM name contains a space character, enclose the name in
double quotation marks (").
Tip: There is no equivalent option that excludes VMs from having change block tracking reset.
Therefore, you must specify more granular VM names when you reset change block tracking for a
group of VMs. For example, you cannot specify an include.vmresetcbt statement to include all
VMs that begin with "EXEC" and an exclude statement to exclude the VMs that begin with
"EXECTEST".

Examples
Task 1
Reset change block tracking on all VMs with names that begin with "Prod" followed by any single
character:

INCLUDE.VMRESETCBT Prod?

Task 2
Reset change block tracking on all VMs with names that begin with any two characters, followed by
"Prod", followed by zero or more characters:

INCLUDE.VMR ??Prod*

Task 3
Reset change block tracking on all VMs with names that begin with one or more characters, and end
with "Prod":

INCLUDE.VMRESETCBT ?*Prod

or

INCLUDE.VMRESETCBT *?Prod

Task 4
Reset change block tracking on all VMs with names that begin with "Corporate Mail", followed by zero
or more characters:

include.vmr "Corporate Mail*"

Task 5
Reset change block tracking on all VMs:

Chapter 10. Processing options 415

 include.vmresetcbt *

Related reference
“Vmnocbtcontinue” on page 564
Use the vmnocbtcontinue option to specify whether to back up a virtual machine (VM) without using
the change block tracking function when one or more snapshots already exist on the VM and change block
tracking must be enabled or reset.

INCLUDE.VMSNAPSHOTATTEMPTS
Use the INCLUDE.VMSNAPSHOTATTEMPTS option to determine the total number of snapshot attempts to
try for a virtual machine (VM) backup operation that fails due to snapshot failure.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.

Supported Clients
This option can be used with supported Linux clients that are configured to back up VMware virtual
machines.

Options File
This option is valid in the client options file (dsm.opt). It can also be included on the server in a client
option set. It is not valid on the command line.

Syntax
INCLUDE.VMSNAPSHOTATTEMPTS vmname num_with_quiescing

num_without_quiescing

Parameters
vmname
A required positional parameter that specifies the name of the virtual machine to attempt the total
number of snapshots for, if a backup attempt fails due to snapshot failure. The name is the virtual
machine display name.
Only one virtual machine can be specified on each INCLUDE.VMSNAPSHOTATTEMPTS statement.
However, to configure the total snapshot attempts for other virtual machines, you can use the
following methods:
• For each virtual machine that you want this option to apply to, specify as many
INCLUDE.VMSNAPSHOTATTEMPTS statements as needed to reattempt snapshots that failed.
• Use wildcard characters for the vmname parameter value to specify virtual machine names that
match the wildcard pattern. An asterisk (*) matches any character string. A question mark (?)
matches a single character. If the virtual machine name contains a space character, enclose the
name in double quotation marks (").
Tip: If the virtual machine name contains special characters, type the question mark wildcard (?) in
place of the special characters when you specify the virtual machine name.
num_with_quiescing
A positional parameter that specifies the following action:
For VMware backup operations:
• For Windows virtual machines with IBM Spectrum Protect application protection enabled,
num_with_quiescing specifies the number of times to attempt the snapshot with IBM Spectrum

416 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Protect VSS quiescing and Microsoft Windows system provider VSS quiescing. VSS quiescing
applies only to Windows virtual machines.
Depending on the number that you specify, the first snapshot attempt is always made with IBM
Spectrum Protect VSS quiescing. Subsequent snapshot attempts are made with Windows
system provider VSS quiescing.
• For Windows virtual machines without IBM Spectrum Protect application protection enabled
and for Linux virtual machines, num_with_quiescing specifies the number of times to attempt
the snapshot with VMware Tools file system quiescing.
The maximum value that you can specify is ten (10). The default value is two (2). The minimum
value that you can specify is zero (0).
num_without_quiescing
For VMware backup operations:
A positional parameter that specifies the number of times to attempt the snapshot with VMware
Tools file system quiescing and application (VSS) quiescing disabled after the specified number of
attempts with VSS quiescing (num_with_quiescing) completes. For example, you can specify this
parameter for a virtual machine that is already protected by an IBM Data Protection agent that is
installed in a guest virtual machine.
The maximum value that you can specify is ten (10). The minimum value that you can specify is
zero (0), which is the default value.
Important: When this parameter is applied to a virtual machine backup, the backup is considered
crash-consistent. As a result, operating system, file system, and application consistency are not
guaranteed. An include.vmsnapshotattempts 0 0 entry is not valid. Backup operations
require at least one snapshot.

Examples
VMware examples:
Example 1
The following INCLUDE.VMSNAPSHOTATTEMPTS statement in the client options file tries two total
snapshot attempts (with VSS quiescing) for virtual machine VM_a:

INCLUDE.VMSNAPSHOTATTEMPTS VM_a 2 0

Example 2
The following INCLUDE.VMSNAPSHOTATTEMPTS statement in the client options file tries three total
snapshot attempts for Windows virtual machines that match the vmServer_Dept* string:
• The first attempt is made with IBM Spectrum Protect VSS quiescing.
• The second attempt is made with Windows system provider VSS quiescing.
• The third snapshot attempt is taken without VSS quiescing.

INCLUDE.VMSNAPSHOTATTEMPTS vmServer_Dept* 2 1

Example 3
The following INCLUDE.VMSNAPSHOTATTEMPTS statement in the client options file tries one total
snapshot attempt (with VSS quiescing) for virtual machines that match the vmDB_Dept* string:

INCLUDE.VMSNAPSHOTATTEMPTS vmDB_Dept* 1 0

Example 4
The following INCLUDE.VMSNAPSHOTATTEMPTS statement in the client options file tries two total
snapshot attempts (with VSS quiescing) for all virtual machines:
• The first attempt is made with IBM Spectrum Protect VSS quiescing.

Chapter 10. Processing options 417

 • The second attempt is made with Windows system provider VSS quiescing.

INCLUDE.VMSNAPSHOTATTEMPTS * 2 0

Example 5
In this example, the virtual machine DB15 has an IBM Data Protection agent that is installed in a
guest virtual machine and does not need an application-consistent snapshot. The following
INCLUDE.VMSNAPSHOTATTEMPTS statement in the client options file tries one total snapshot
attempt (without VSS quiescing) for virtual machine DB15:

INCLUDE.VMSNAPSHOTATTEMPTS DB15 0 1

Related reference
“INCLUDE.VMTSMVSS” on page 418
The INCLUDE.VMTSMVSS option notifies virtual machine applications that a backup is about to occur.
This option allows the application to truncate transaction logs and commit transactions so that the
application can resume from a consistent state when the backup completes. An optional parameter can
be specified to suppress truncation of the transaction logs.

INCLUDE.VMTSMVSS
The INCLUDE.VMTSMVSS option notifies virtual machine applications that a backup is about to occur.
This option allows the application to truncate transaction logs and commit transactions so that the
application can resume from a consistent state when the backup completes. An optional parameter can
be specified to suppress truncation of the transaction logs.
When a virtual machine is included by this option, IBM Spectrum Protect provides application protection.
That is, the client freezes and thaws the VSS writers and, optionally, truncates the application logs.
If a VMware virtual machine is not protected by this option, application protection is provided by VMware,
and VMware freezes and thaws the VSS writers, but application logs are not truncated.
If a Hyper-V virtual machine is not protected by this option, application protection is provided by Hyper-V,
which freezes and thaws the VSS writers, but does not truncate application logs.
Important: Before you begin application protection backups, ensure that the application database, such
as the Microsoft SQL Server database or Microsoft Exchange Server database, is on a non-boot drive (any
drive other than the boot drive), in case a diskshadow revert operation is needed during restore.

Supported clients
This option can be used with supported x86_64 Linux clients.

Options file
Set this option in the client options file. This option cannot be set by the preferences editor or on the
command line.

Syntax
INCLUDE.VMTSMVSS vmname OPTions=KEEPSqllog

Parameters
vmname
Specifies the name of the virtual machine that contains the applications to quiesce. The name is the
virtual machine display name. Specify one virtual machine per INCLUDE.VMTSMVSS statement. For
example, to include a virtual machine named Windows VM3 [2012R2], use this syntax in the options
file: INCLUDE.VMTSMVSS "Windows VM3 [2012R2]".
To protect all virtual machines with this option, use an asterisk as a wildcard (INCLUDE.VMTSMVSS
*). You can also use question marks to match any single character. For example,

418 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 INCLUDE.VMTSMVSS vm?? protects all virtual machines that have names that begin with vm and are
followed by any two characters (vm10, vm11, vm17, and so on).
Tip: If the virtual machine name contains special characters, such as bracket characters ([ or ]), the
virtual machine name might not be correctly matched. If a virtual machine name uses special
characters in the name, you can use the question mark character (?) to match the special characters
in the virtual machine name.
There is no default value for this parameter. To enable application protection, you must include virtual
machines to be protected on one or more INCLUDE.VMTSMVSS statements. Make sure that you do
not exclude a disk on a virtual machine (by using the EXCLUDE.VMDISK option) if the disk contains
application data that you want protected.
OPTions=KEEPSqllog
If the OPTions KEEPSqllog parameter is specified on an INCLUDE.VMTSMVSS statement, the
parameter prevents SQL server logs from being truncated when a backup-archive client that is
installed on a data mover node backs up a virtual machine that is running a SQL server. Specifying this
parameter allows the SQL server administrator to manually manage (backup, and possibly truncate)
the SQL server logs, so that they can be preserved and be used to restore SQL transactions to a
specific checkpoint, after the virtual machine is restored.
When this option is specified, the SQL log is not truncated and the following message is displayed and
logged on the server:
ANS4179I IBM Spectrum Protect application protection
did not truncate the Microsoft SQL Server logs on VM 'VM'.
You can remove the OPTIONS=KEEPSQLLOG option to enable truncation of the SQL logs when a
backup completes.
Note: The client does not back up the SQL log files. The SQL administrator must back up the log files
so that they can be applied after the database is restored.

Examples
Options file

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.
Configure application protection for a virtual machine that is named vm_example:

INCLUDE.VMTSMVSS vm_example

Configure application protection for vm11, vm12, and vm15:

INCLUDE.VMTSMVSS vm11
INCLUDE.VMTSMVSS vm12
INCLUDE.VMTSMVSS vm15 options=keepsqllog

Command line
Not applicable; this option cannot be specified on the command line.
Related reference
“Vmtimeout” on page 581
VMTIMEOut specifies the maximum time, in seconds, to wait before abandoning a backup vm operation,
when the INCLUDE.VMTSMVSS option is used to provide application protection. To use this option, the
IBM Spectrum Protect for Virtual Environments license must be installed.
“Exclude.vmdisk” on page 378
The EXCLUDE.VMDISK option excludes a virtual machine disk from backup operations.
“Include.vmdisk” on page 411

Chapter 10. Processing options 419

 The INCLUDE.VMDISK option includes a virtual machine (VM) disk in backup operations. If you do not
specify one or more disk labels, all disks in the VM are backed up.
“INCLUDE.VMSNAPSHOTATTEMPTS” on page 416
Use the INCLUDE.VMSNAPSHOTATTEMPTS option to determine the total number of snapshot attempts to
try for a virtual machine (VM) backup operation that fails due to snapshot failure.

Incrbydate
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, unless you exclude the file
from backup.
Important: Files that are modified or created after their respective directory was processed by the
backup-archive client, but before the incremental-by-date backup completes, are not backed up and will
not be backed up in future incremental-by-date backups, unless the files are modified again. For this
reason, a run a regular incremental backup periodically, without specifying the incrbydate option.
An incremental-by-date updates the date and time of the last incremental at the server. If you perform an
incremental-by-date on only part of a file system, the date of the last full incremental is not updated and
the next incremental-by-date backs up these files again.
Important:
The last incremental backup time refers to the server time and the file modification time refers to the
client time. If the client and server time are not synchronized, or the client and server are in different time
zones, this affects incremental-by-date backup with mode=incremental.
The last incremental backup time refers to the server time and the file modification time refers to the
client time. If the client and server time are not synchronized, or the client and server are in different time
zones, this affects incremental-by-date backup and image backup with mode=incremental.
Both full incremental backups and incrementals-by-date backups backup new and changed files. An
incremental-by-date takes less time to process than a full incremental and requires less memory.
However, unlike a full incremental backup, an incremental-by-date backup does not maintain current
server storage of all your workstation files for the following reasons:
• It does not expire backup versions of files that are deleted from the workstation.
• It does not rebind backup versions to a new management class if the management class has changed.
• It does not back up files with attributes that have changed, such as Access control list (ACL) data,
unless the modification dates and times have also changed.
• It ignores the copy group frequency attribute of management classes.
Tip: If you have limited time during the week to perform backups, but extra time on weekends, you can
maintain current server storage of your workstation files by performing an incremental backup with the
incrbydate option on weekdays and a full incremental backup on weekends.

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
INCRbydate

Parameters
There are no parameters for this option.

420 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Examples
Command line:
dsmc incremental -incrbydate

Incremental
Use the incremental option with the restore image command to ensure that any changes that were
made to the base image are also applied to the restored image.
If you also use the deletefiles option, changes include the deletion of files and directories that were in
the original image but later deleted from the workstation.
Note: Using the incremental option with the restore image command to perform a dynamic image
backup is not supported.

Supported Clients
This option is valid only for AIX, Linux x86_64, Linux on POWER, and Solaris. The IBM Spectrum Protect
API does not support this option.

Syntax
INCREmental

Examples
Command line:
res i "/home/devel/projecta/*" -incremental

Instrlogmax
The instrlogmax option specifies the maximum size of the instrumentation log (dsminstr.log), in
MB. Performance data for the client is collected in the dsminstr.log file during backup or restore
processing when the enableinstrumentation option is set to yes.
If you change the value of the instrlogmax option, the existing log is extended or shortened to
accommodate the new size. If the value is reduced, the oldest entries are deleted to reduce the file to the
new size.

Supported Clients
This option is valid for all clients and the IBM Spectrum Protect API.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax
INSTRLOGMAX size

Parameters
size
Specifies the maximum size, in MB, for the instrumentation log file. The range of values is 0 - 2047.
The default value is 25.
When the size of the dsminstr.log file exceeds the maximum size, the log file is renamed to
dsminstr.log.bak. Subsequent instrumentation data continues to be saved to the dsminstr.log
file.
If you specify 0, the log file grows indefinitely.

Chapter 10. Processing options 421

 Examples
Options file:
instrlogmax 100
Command line:
dsmc sel /home/mydir/* -subdir=yes -enableinstrumentation=yes -
instrlogmax=100
This option is valid only on the initial command line. It is not valid in interactive mode.
Related reference
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.
Instrlogname
The instrlogname option specifies the path and file name where you want to store performance
information that the backup-archive client collects.

Instrlogname
The instrlogname option specifies the path and file name where you want to store performance
information that the backup-archive client collects.
When you use the enableinstrumentation yes option to collect performance data during backup
and restore operations, the client automatically stores the information in a log file.
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 the API-dependent products IBM Spectrum Protect for Databases: Data Protection for Microsoft SQL
Server and IBM Spectrum Protect for Mail: Data Protection for Microsoft Exchange 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).
Use this option only when you want to change the file name and location of the instrumentation log.
If you want to control the size of the log file, use the instrlogmax option.

Supported Clients
This option is valid for all clients and the IBM Spectrum Protect API.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.
Important: Set the DSM_LOG environment variable to name a directory where the log is to be placed. The
directory that is specified must have permissions that allow write-access from the account under which
the client is run. The root directory is not a valid value for DSM_LOG.

Syntax
INSTRLOGNAME filespec

Parameters
filespec
Specifies the path and file name where you want to store performance information during backup or
restore processing. If any part of the path that you specify does not exist, the client attempts to create
it.

422 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 If you specify a file name only, the file is stored 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 you issued the dsmc command). The
instrumentation log file cannot be a symbolic link.
For Mac OS X, if you specify a file name only, the file is stored in your default folder. The default
directories are:

~/Library/Logs/tivoli/tsm
/Library/Logs/tivoli/tsm

This instrumentation log file name replaces the previous instrumentation log file name
dsminstr.report.pXXX that was created by the TESTFLAG=instrument:detail or
instrument:API option.

Examples
Options file:
For AIX, Linux, and Oracle Solaris clients:

instrlogname /home/user1/mydir/mydsminstr.log

For Mac OS X clients:

instrlogname /Users/user1/Library/Logs/mydsminstr.log

Command line:
For AIX, Linux, and Oracle Solaris clients:

dsmc sel /home/user1/mydir/* -subdir=yes -instrlogname=/usr/log/mydsminstr.log

For Mac OS X clients:

dsmc sel /Users/user1/mydir/* -subdir=yes -instrlogname=/Users/user1/Library/Logs/

mydsminstr.log

This option is valid only on the initial command line. It is not valid in interactive mode.
Related reference
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.
Instrlogmax
The instrlogmax option specifies the maximum size of the instrumentation log (dsminstr.log), in
MB. Performance data for the client is collected in the dsminstr.log file during backup or restore
processing when the enableinstrumentation option is set to yes.

Lanfreecommmethod
The lanfreecommmethod option specifies the communications protocol between the IBM Spectrum
Protect client and Storage Agent. This enables processing between the client and the SAN-attached
storage device.
If you are using LAN failover, you must have lanfreecommmethod in the dsm.sys file within a server
stanza.
For AIX, Linux and Solaris, use the lanfreeshmport option to specify the shared memory port number
where the Storage Agent is listening.

Supported Clients
This option is valid for AIX, Linux, and Oracle Solaris clients.

Chapter 10. Processing options 423

 Options File
Place this option in the dsm.sys file within a server stanza.

Syntax
LANFREECommmethod commmethod

Parameters
commmethod
Specifies the supported protocol for the backup-archive client:
TCPip
The Transmission Control Protocol/Internet Protocol (TCP/IP) communication method.
Use the lanfreetcpport option to specify the TCP/IP port number where the Storage Agent is
listening. The TCP/IP communication method is the default for non-root users on all supported
platforms.
V6Tcpip
Indicates that either TCP/IP v4 or v6 should be used, depending on the system configuration and
results of a domain name service lookup. The only time this is not true is when dsmc schedule is
used and schedmode is prompt. A valid DNS environment must be available.
SHAREdmem
Use the shared memory communication method when the client and Storage Agent are running on
the same system. Shared memory provides better performance than the TCP/IP protocol. This is
the default communication method for AIX, Linux, and Solaris root users. When specifying this
communication method on AIX, the backup-archive client user can be logged in as root or non-
root, as long as the Storage Agent is running as root. If the Storage Agent is not running as root,
the user ID running the backup-archive client must match the user ID running the Storage Agent.

Examples
Options file:
lanfreecommmethod tcp
Use only TCP/IP v4
lanfreecommmethod V6Tcpip
Use both TCP/IP v4 or v6, depending on how the system is configured and the results of a domain
name service lookup.
Command line:
-lanfreec=tcp
-lanfreec=V6Tcpip
This option is valid only on the initial command line. It is not valid in interactive mode.
Related information
“Lanfreeshmport” on page 425
“Lanfreetcpport” on page 425

424 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Lanfreeshmport
Use the lanfreeshmport option when lanfreecommmethod=SHAREdmem is specified for
communication between the backup-archive client and the storage agent. This enables processing
between the client and the SAN-attached storage device.

Supported Clients
This option is valid for AIX, Linux, and Oracle Solaris clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax
LANFREEShmport port_address

Parameters
port_address
Specifies the number that is used to connect to the storage agent. The range of values is 1 through
32767.
For Windows clients, the default is 1.
For all clients except Windows clients, the default is 1510.

Examples
Options file:
lanfrees 1520
Command line:
-lanfrees=1520
This option is valid only on the initial command line. It is not valid in interactive mode.
Related information
“Lanfreecommmethod” on page 423

Lanfreetcpport
The lanfreetcpport option specifies the TCP/IP port number where the IBM Spectrum Protect Storage
Agent is listening.
Use this option when you specify lanfreecommmethod=TCPip for communication between the backup-
archive client and Storage Agent. Do not specify the lanfreetcpport option if you want to use the
NAMedpipes communication method for LAN-free communication.

Supported Clients
This option is valid only for AIX, Linux x86_64, Linux on POWER, and Oracle Solaris clients.

Options File
Place this option in the dsm.sys file within a server stanza.

Syntax
LANFREETCPPort port_address

Chapter 10. Processing options 425

 Parameters
port_address
Specifies the TCP/IP port number where the Storage Agent is listening. The range of values is 1
through 32767; the default is 1500.
Note: The client lanfreetcpport value must match Storage Agent tcpport value for
communications with the Storage Agent (virtual server). The client tcpport value must match the
server tcpport value for communications with the actual server.

Examples
Options file:
lanfreetcpp 1520
Command line:
-lanfreetcpp=1520
This option is valid only on the initial command line. It is not valid in interactive mode.
Related information
“Lanfreecommmethod” on page 423

Lanfreessl
Use the lanfreessl option to enable Secure Sockets Layer (SSL) to provide secure client and Storage
Agent communications. This option is deprecated if you are connecting to an IBM Spectrum Protect
server V8.1.2 and later levels, and V7.1.8 and later V7 levels.
To enable SSL for data movement, set SSL YES on the client and the storage agent. To disable SSL for
data movement, set SSL NO on the client and the storage agent. When the client and storage agent are
on the same system, use of SSL between them is not recommended for performance reasons. Use shared
memory or named pipes instead.
The client SSL option is set in the client options file. For more information, see “Ssl” on page 509.
The storage agent SSL option is set when it is defined by the DSMSTA SETSTORAGESERVER command.
For more information, see Configuring a storage agent to use SSL.
Note: Authentication is always achieved by using SSL, regardless of the SSL option setting.

Supported Clients
This option is supported on all clients, except for Mac OS X clients.

Options File
Place this option in the client options file. You cannot set this option in the GUI or on the command line.

Syntax
No
LANFREESSL
Yes

Parameters
No
Specifies that the backup-archive client does not use SSL when communicating with the Storage
Agent. No is the default.
Yes
Specifies that the backup-archive client enables SSL when communicating with the Storage Agent. To
enable SSL, specify lanfreessl=yes and change the value of the lanfreetcpport option.

426 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Changing the value of the lanfreetcpport option is necessary because the IBM Spectrum Protect
Storage Agent is typically set up to listen for SSL connections on a separate port.

Examples
Options file:

lanfreessl yes
lanfreessl no

Command line:
Not applicable. You cannot set this option on the command line.

Lanfreetcpserveraddress
The lanfreetcpserveraddress option specifies the TCP/IP address for the IBM Spectrum Protect
Storage Agent.
Use this option when you specify lanfreecommmethod=TCPip or V6Tcpip for communication between
the backup-archive client and Storage Agent.
Overriding the default for this option is useful when configuring LAN-free in an environment where the
client and storage agent are running on different systems. You can obtain this Storage Agent address from
your administrator.

Supported Clients
This option is valid only for AIX, Linux x86_64, Linux on POWER, and Oracle Solaris clients.

Options File
Place this option in the client system-options file.

Syntax
LANFREETCPServeraddress stagent_address

Parameters
stagent_address
Specifies a 1 to 64 character TCP/IP address for a server. Specify a TCP/IP domain name or a numeric
IP address. The numeric IP address can be either a TCP/IP v4 or TCP/IP v6 address. The default value
is 127.0.0.1 (localhost).

Examples
Options file:

LANFREETCPServeraddress stagent.example.com

LANFREETCPServeraddress 192.0.2.1

Command line:
Does not apply.

Latest
Use the latest option to restore the most recent backup version of a file, even if the backup is inactive.
You can use the latest option with the following commands:
• restore
• restore group

Chapter 10. Processing options 427

 If you are performing a point-in-time restore (using the pitdate option), it is not necessary to specify
latest since this option is implicit when pitdate is used.

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
LATest

Parameters
There are no parameters for this option.

Examples
Command line:
dsmc restore "/Users/devel/projecta/*" -latest
Command line:
dsmc restore "/home/devel/projecta/*" -latest

Localbackupset
The localbackupset option specifies whether the backup-archive client GUI bypasses initial logon with
the IBM Spectrum Protect server to restore a local backup set on a standalone workstation.
If you set the localbackupset option to yes, the GUI does not attempt initial logon with the server. In
this case, the GUI only enables the restore functionality.
If you set the localbackupset option to no (the default), the GUI attempts initial logon with the server
and enables all GUI functions.
Note: The restore backupset command supports restore of local backup sets on a standalone
workstation without using the localbackupset option.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax
No
LOCALbackupset
Yes

Parameters
No
Specifies that the GUI attempts initial logon with the server and enables all functions. This is the
default.
Yes
Specifies that the GUI does not attempt initial logon with the server and enables only the restore
functionality.

428 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Examples
Options file:
localbackupset yes
This option is not valid with the dsmc command-line client.
Related information
“Restore Backupset” on page 668

Makesparsefile
Use the makesparsefile option with the restore or retrieve commands to specify how sparse files
are recreated.
Sparse files do not have disk space allocated for every block in the whole address space, leading to holes
within the file. The backup-archive client detects sparse files during a backup operation and marks them
as sparse on the IBM Spectrum Protect server. Holes are detected by their content, which is always zeros.
If you set the makesparsefile option to yes (default), holes within the file are not written to disk so no
additional disk space is allocated during a restore.
If you set the makesparsefile option to no, holes are not recreated, leading to disk blocks allocated for
the whole address space. This might result in a larger amount of used disk space. Ensure that you have
enough disk space to restore all data.
On some UNIX and Linux systems, it might be necessary to back up system specific files as non-sparse
files. Use the makesparsefile option for files where the existence of physical disk blocks is required,
such as ufsboot on Solaris, which is executed during boot time. The boot file loader of the operating
system accesses physical disk blocks directly and does not support sparse files.

Supported Clients
This option is valid for all UNIX and Linux clients except Mac OS X.

Options File
Place this option in the client user options file (dsm.opt).

Syntax
Yes
MAKESParsefile
No

Parameters
Yes
Specifies that holes within the file are not written so that no additional disk space is allocated during a
restore. This is the default.
No
Specifies that holes are not recreated leading to disk blocks allocated for the whole address space.

Examples
Options file:
makesparsefile no
Command line:
-makesparsefile=no
This option is valid only on the initial command line. It is not valid in interactive mode.

Chapter 10. Processing options 429

Managedservices
The managedservices option specifies whether the IBM Spectrum Protect client acceptor service
manages the scheduler, the web client, or both.
Restriction: You cannot use the dsmcad for scheduling when you set the sessioninitiation option to
serveronly.
The client acceptor daemon 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 executed immediately or the
scheduler exits. The client acceptor daemon restarts the scheduler when it is time to execute the
scheduled event.
Note:
1. If you set the schedmode option to prompt, the server prompts the client acceptor daemon when it is
time to run the schedule. The scheduler connects to and disconnects from the server when the client
acceptor daemon is first started.
The dsmc schedule command cannot be used when both schedmode prompt and commmethod
V6Tcpip are specified.
2. For Mac OS X, if you do not specify the managedservices option, the client acceptor daemon
manages both the scheduler program and the web client, by default.
3. Set the passwordaccess option to generate in your dsm.sys file and generate a password, so IBM
Spectrum Protect can manage your password automatically.
Using the client acceptor daemon to manage the scheduler service can provide the following benefits:
• Memory retention problems that can occur when using traditional methods of running the scheduler are
resolved. Using the client acceptor daemon to manage the scheduler requires very little memory
between scheduled operations.
• The client acceptor daemon can manage both the scheduler program and the web client, reducing the
number of background processes on your workstation.
• To use the web client, you must specify this option in the client system-options file.

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 system-options file (dsm.sys) within a server stanza. You can set this option
on the Web Client tab of the Preferences editor.

Syntax
MANAGEDServices mode

Parameters
mode
Specifies whether the client acceptor daemon manages the scheduler, the web client, or both.
webclient
Specifies that the client acceptor daemon manages the web client. This is the default for UNIX
and Linux. Both webclient and schedule are the defaults for Mac OS X.
schedule
Specifies that the client acceptor daemon manages the scheduler. Both webclient and
schedule are the defaults for Mac OS X.

430 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 none
For Mac OS X, specifies that the client acceptor daemon not manage the web client or schedules.
Set managedservices to none to enable the dsmc schedule command.

Examples
Options file:
The following are examples of how you might specify the managedservices option in your client
system-options file (dsm.sys).
Task
Specify that the client acceptor daemon manages only the web client.

managedservices webclient

Task
Specify that the client acceptor daemon manages only the scheduler.

managedservices schedule

Task
Specify that the client acceptor daemon manages both the web client and the scheduler.

managedservices schedule webclient

Note: The order in which these values are specified is not important.
Task
For Mac OS X, to use the dsmc schedule command, specify:

managedservices none

Command line:
Does not apply.
Related information
“Passwordaccess” on page 449
See “Configuring the scheduler” on page 63 for instructions to set up the client acceptor daemon to
manage the scheduler.
“Sessioninitiation” on page 490
“Cadlistenonport” on page 320

Maxcmdretries
The maxcmdretries option specifies the maximum number of times the client scheduler (on your
workstation) attempts to process a scheduled command that fails.
The command retry starts only if the client scheduler has not yet backed up a file, never connected to the
server, or failed before backing up a file. This option is only used when the scheduler is running.
Your IBM Spectrum Protect administrator can also set this option. If your administrator specifies a value
for this option, that value overrides what you specify in the client options file after your client node
successfully contacts the server.

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.

Chapter 10. Processing options 431

 Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the Scheduler tab, in the Maximum command retries field of the Preferences editor.

Syntax
MAXCMDRetries maxcmdretries

Parameters
maxcmdretries
Specifies the number of times the client scheduler can attempt to process a scheduled command that
fails. The range of values is zero through 9999; the default is 2.

Examples
Options file:
maxcmdr 4
Command line:
-maxcmdretries=4
This option is valid only on the initial command line. It is not valid in interactive mode.

Mbobjrefreshthresh
The mbobjrefreshthresh (megablock object refresh threshold) option is a number defining a
threshold. When the number of IBM Spectrum Protect objects that are needed to describe any 128 MB
megablock exceeds this value, the entire megablock is refreshed and the objects that were used to
represent this area, in previous backups, are expired.
When you backup a virtual machine, the data is stored on the IBM Spectrum Protect server in 128 MB
units, called megablocks. If an area on the production disk changes and a new incremental backup is
performed, a new megablock is created to represent the changes that were made to the previously
backed up data. Because a new megablock can be created with each incremental backup, eventually the
megablocks can adversely affect the performance of the IBM Spectrum Protect database, and therefore,
adversely affect the performance of most IBM Spectrum Protect operations.
Use this option when estimating IBM Spectrum Protect objects that represent production data for each
virtual machine backup. For example, when the number of IBM Spectrum Protect objects exceed this
value, the megablock is refreshed. This action means that the entire 128-MB block is copied to the server
and is represented as a single IBM Spectrum Protect object. The minimum value is 2 and the maximum
value is 8192. The default value is 50.

Supported clients
This option is valid for data movers that protect VMware virtual machines. To use this option, you must
have a license agreement to use IBM Spectrum Protect for Virtual Environments: Data Protection for
VMware.

Options file
This option is valid in the client options file (dsm.opt). It can also be included on the server in a client
options set. It is not valid on the command line.

Syntax
50
MBOBJREFRESHTHRESH
integer

432 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Parameters
The minimum value you can specify is 2 megablocks, the largest value is 8192 megablocks; the default is
50 megablocks.

Examples
Set this option to trigger a megablock refresh when the number of objects needed to represent an
updated megablock exceeds 20 objects:

MBOBJREFRESHTHRESH 20

Mbpctrefreshthresh
The mbpctrefreshthresh (megablock percentage refresh threshold) option is a number defining a
threshold. When the percentage of IBM Spectrum Protect objects that are needed to describe any 128
MB megablock exceeds this value, the entire megablock is refreshed and the objects that were used to
represent this area, in previous backups, are expired.
When you backup a virtual machine, data is stored on the IBM Spectrum Protect server in 128 MB units,
called megablocks. If an area on the production disk changes and a new incremental backup is
performed, a new megablock is created to represent the changes that were made to the previously
backed up data. Because a new megablock can be created with each incremental backup, eventually the
megablocks can adversely affect the performance of the IBM Spectrum Protect database, and therefore,
adversely affect the performance of most IBM Spectrum Protect operations.
Use this option when estimating the amount of additional data that is backed up for each virtual machine.
For example, when a 128-MB block of a production disk changes more than the percentage specified, the
entire 128-MB block is copied to the server. The block is represented as a single IBM Spectrum Protect
object.

Supported clients
This option is valid for clients that act as data mover nodes that protect VMware virtual machines. To use
this option, you must have a license agreement to use IBM Spectrum Protect for Virtual Environments:
Data Protection for VMware.

Options file
This option is valid in the client options file (dsm.opt). It can also be included on the server in a client
options set. It is not valid on the command line.

Syntax
50
MBPCTREFRESHTHRESH
integer

Parameters
The minimum value you can specify is 1 percent, the largest value is 99 percent; the default is 50 percent.

Examples
Set this option to trigger a megablock refresh when 50 percent (or more) of the objects in a megablock on
a production disk have changed:
MBPCTREFRESHTHRESHOLD 50

Chapter 10. Processing options 433

Memoryefficientbackup
The memoryefficientbackup option specifies the memory-conserving algorithm to use for processing
full file space backups.
One method backs up one directory at a time, using less memory. The other method uses much less
memory, but requires more disk space.
Use the memoryefficientbackup option with the incremental command when your workstation is
memory constrained. You can also use this option as a parameter to the include.fs option in order to
select the algorithm that the backup-archive client uses on a per-filespace basis.
Use memoryefficientbackup=diskcachemethod for any file space that has too many files for the
client to complete the incremental backup with either the default setting,
memoryefficientbackup=no, or with memoryefficientbackup=yes.
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 path
length of the files and directories to be backed up. For UNIX and Linux estimate 1 byte per character in
the path name. For Mac OS X, estimate 4 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 200 MB for UNIX and Linux, and 800 MB for Mac OS X clients. 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.
A second disk cache file is created for the list of migrated files when backing up an HSM managed file
system. The combined disk cache files, created by disk cache incremental backups and HSM managed file
system backups, can require above 400 MB of disk space for each million files being backed up. The disk
cache file can become very large. Large file support must be enabled on the file system that is being used
for the disk cache file.

Supported Clients
This option is valid for all clients. The server can also define this option.

Options File
This option is allowed in dsm.opt and within a server stanza in dsm.sys, but the value in dsm.opt is
ignored if it also appears in dsm.sys. You can also place this option on the initial command line. In
interactive mode, this option can be used with the incremental command. You can also set this option
on the Performance Tuning tab in the Preferences editor, and selecting the Use memory-saving
algorithm check box.

Syntax
No
MEMORYEFficientbackup
Yes

DISKCACHEMethod

Parameters
No
Your client node uses the faster, more memory-intensive method when processing incremental
backups. This is the default.
Yes
Your client node uses the method that requires less memory when processing incremental backups.
Diskcachemethod
Your client node uses the method that requires much less memory but more disk space when
processing incremental backups for full file systems.

434 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Examples
Options file:

memoryefficientbackup yes
memoryefficientbackup diskcachem

Command line:
-memoryef=no
Related information
“Include options” on page 403

Mode
Use the mode option to specify the backup mode to use when performing specific backup operations.
The mode option has no effect on a when backing up a raw logical device.
You can use the mode option with the following backup commands:
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 containing a list of files from one or
more file space origins.
backup vm
For VMware virtual machines, this parameter specifies whether to perform an incremental-forever-full
or incremental-forever-incremental backup of VMware virtual machines.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.

Supported Clients
This option is valid on all supported clients, except Mac OS. The IBM Spectrum Protect API does not
support this option.
This option is valid for data movers that protect VMware virtual machines. To use this option, you must
have a license agreement to use IBM Spectrum Protect for Virtual Environments: Data Protection for
VMware.

Syntax
For image backups of client file systems
Selective
MODE =
Incremental

For image backup of NAS file systems

differential
MODE =
full

Chapter 10. Processing options 435

 For group backups
full
MODE =
differential

For backing up VMware virtual machines

IFIncremental
MODE=
IFFull

Parameters
Image backup parameters
selective
Specifies that you want to perform a full (selective) image backup. This is the default mode for
image backups of client file systems.
incremental
Specifies that you want to back up only the data that has changed since the most recent image
backup. If an image backup has not already been created, then the first backup is a full image
backup (mode=selective), regardless of what mode option you specify.
NAS backup parameters
differential
This is the default for NAS objects. Specifies that you want to perform a NAS backup of files that
changed since the last full backup. If there is no copy of a full image stored on the IBM Spectrum
Protect server, a full backup occurs. If a full image exists, whether it is restorable, or expired and
being maintained because of dependent differential images, specifying MODE=differential
sends a differential image backup. If a full image is sent during a differential backup, it is reflected
as a full image using the QUERY NASBACKUP server command.
A full image can be eligible for expiration based on versioning or retention (verexists
retextra), but still be maintained on the server to allow for restoring dependent differential
images. A full image that is eligible for expiration cannot be selected for restore, so it is not
displayed using the QUERY NASBACKUP server command. The differential image backups that
depend on an "expired" full image can be restored.
full
Specifies that you want to perform a full backup of NAS file systems.
Group backup parameters
full
Specifies that you want to perform a full backup of group objects. This is the default for group
backups.
differential
Specifies that you want to perform a group backup of files that changed since the last full backup.
If there is no copy of a full image stored on the IBM Spectrum Protect server, a full backup occurs.
If a full image exists, whether it is restorable, or expired and being maintained because of
dependent differential images, specifying MODE=differential sends a differential image
backup. If a full image is sent during a differential backup, it is reflected as a full image using the
QUERY GROUP server command.
A full image can be eligible for expiration based on versioning or retention (verexists
retextra), but still be maintained on the server to allow for restoring dependent differential
images. A full image that is eligible for expiration cannot be selected for restore, so it is not
displayed using the QUERY GROUP server command. The differential image backups that depend
on an "expired" full image can be restored.

436 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
VMware virtual machine parameters
IFFull
Specifies that you want to perform an incremental-forever-full backup of a virtual machine. An
incremental-forever-full backup backs up all used blocks on a VMware virtual machine's disks.
By default, the first backup of a VMware virtual machine is an incremental-forever-full
(mode=iffull) backup, even if you specify mode=ifincremental (or let the mode option
default). Subsequent backups default to mode=ifincremental.
You cannot use this backup mode to back up a virtual machine if the client is configured to encrypt
the backup data.
For a description of the incremental-forever backup strategy for VMware virtual machines, see
Backup and restore types.
IFIncremental
Specifies that you want to perform an incremental-forever-incremental backup of a virtual
machine. An incremental-forever-incremental backup backs up only the disk blocks that have
changed since the last backup.
This mode is the default backup mode for VMware virtual machine backups.
You cannot use this backup mode to back up a virtual machine if the client is configured to encrypt
the backup data.

Examples
Task
Perform a backup of a VMware virtual machine named vm1, using the incremental-forever-
incremental mode to back up only the data that has changed since the last backup.

dsmc backup vm vm1 -mode=ifincremental

-vmbackuptype=full

Task
Perform the NAS image backup of the entire file system.

dsmc backup nas -mode=full -nasnodename=nas1

/vol/vol0 /vol/vol1

Task
Back up the /home/test file space using an image incremental backup that backs up only new and
changed files after the last full image backup.

dsmc backup image /home/test -mode=incremental -snapshotproviderimage=none

Task
Perform a full backup of all the files in filelist /home/dir1/filelist1 to the virtual file space
name /virtfs containing the group leader /home/group1 file.

dscm backup group -filelist=/home/dir1/filelist1

-groupname=group1 -virtualfsname=/virtfs -mode=full

Related reference
“Backup VM” on page 608
“Backup Group” on page 600
Use the backup group command to create and back up a group containing a list of files from one or
more file space origins to a virtual file space on the IBM Spectrum Protect server.
“Backup Image” on page 602
The backup image command creates an image backup of one or more volumes on your system.
“Backup NAS” on page 606

Chapter 10. Processing options 437

 The backup nas command creates an image backup of one or more file systems that belong to a
Network Attached Storage (NAS) file server, otherwise known as NDMP Backup. You are prompted for the
IBM Spectrum Protect administrator ID.

Monitor
The monitor option specifies whether to monitor an image backup or restore of file systems belonging to
a Network Attached Storage (NAS) file server.
If you specify monitor=yes, the backup-archive client monitors the current NAS image backup or restore
operation and displays processing information on your screen. This is the default.
If you specify monitor=no, the client does not monitor the current NAS image backup or restore
operation and is available to process the next command.
Use this option with the backup nas or restore nas commands.

Supported Clients
This option is valid for AIX, Linux, and Solaris clients only.

Syntax
Yes
MONitor =
No

Parameters
Yes
Specifies that you want to monitor the current NAS image backup or restore operation and display
processing information on your screen. This is the default.
No
Specifies that you do not want to monitor the current NAS image backup or restore operation.

Examples
Command line:

backup nas -mode=full -nasnodename=nas1 -monitor=yes

/vol/vol0 /vol/vol1

Myreplicationserver
The myreplicationserver option specifies which secondary server stanza that the client uses during a
failover.
The secondary server stanza is identified by the replservername option and contains connection
information about the secondary server.
This option is set by the IBM Spectrum Protect server administrator for the client node. During the normal
(non-failover) logon process, the option is sent to the client and is saved in the client options file.
Do not edit this option during normal operations.
Edit this option only during situations such as the following ones:
• The primary server is offline and the information for the secondary server is not in the options file.
• The secondary server information is out-of-date or incorrect.
Any values that you edit are removed or updated the next time you log in to the primary server.

438 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Supported Clients
This option is valid for all clients.

Options File
This option is placed within a server stanza in the dsm.sys file.

Syntax
MYREPLICATIONServer repl_servername

Parameters
repl_servername
Specifies the name of the stanza for the secondary server to be used during a failover. This value is
usually the name of the secondary server, not the host name of the server. Also, the value of the
repl_servername parameter is not case-sensitive, but the value must match the value that is
specified for the REPLSERVERName option.

Examples
Options file:
MYREPLICATIONServer TargetReplicationServer1
Command line:
Does not apply.
Options file:
The following example demonstrates how to specify options for three different servers in the
dsm.sys file, and how to reference the secondary server.
Connection information for multiple secondary server is presented in stanzas. Each stanza is
identified by the replservername option and the name of the secondary server.
The servername stanza must contain the myreplicationserver option, which points to the
secondary server that is specified by the replservername stanza.
Only one secondary server can be specified per servername stanza.

REPLSERVERNAME TargetReplicationServer1
REPLTCPSERVERADDRESS TargetReplicationServer1
REPLTCPPORT 1505
REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.00

REPLSERVERNAME TargetReplicationServer2
REPLTCPSERVERADDRESS TargetReplicationServer2
REPLTCPPORT 1505
REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.02

SErvername server_a
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname1.example.com
PASSWORDAccess prompt
MYREPLICATIONServer TargetReplicationServer1

SErvername server_b
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname2.example.com
PASSWORDAccess generate
INCLExcl /adm/tsm/archive.excl
MYREPLICATIONServer TargetReplicationServer2

SErvername server_c
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname3.example.com

Chapter 10. Processing options 439

 PASSWORDAccess generate
MYREPLICATIONServer TargetReplicationServer1

Related concepts
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
Configuring the client for automated failover
You can manually configure the client to automatically fail over to the secondary server.

Nasnodename
The nasnodename option specifies the node name for the NAS file server when processing NAS file
systems. The client prompts you for an administrator ID.
The node name identifies the NAS file server to the IBM Spectrum Protect server. The server must
register the NAS file server.
You can specify this option on the command line or in the client system-options file (dsm.sys).
You can override the default value in the dsm.sys file by entering a different value on the command line. If
you do not specify the nasnodename option in the dsm.sys file, you must specify this option on the
command line when processing NAS file systems.
You can use the nasnodename option with the following commands:
• backup nas
• delete filespace
• query backup
• query filespace
• restore nas
You can use the delete filespace command to interactively delete NAS file spaces from server
storage.
Use the nasnodename option to identify the NAS file server. Place the nasnodename option in your client
system-options file (dsm.sys). The value in the client system-options file is the default, but this value can
be overridden on the command line. If the nasnodename option is not specified in the client system-
options file, you must specify this option on the command line when processing NAS file systems.
Use the class option to specify the class of the file space to delete. To display a list of file spaces
belonging to a NAS node so that you can choose one to delete, use the -class=nas option.
To delete NAS file spaces using the web client, see the topic for backing up your data.

Supported Clients
This option is only valid for the AIX, Linux, and Solaris clients. The IBM Spectrum Protect API does not
support this option.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the General tab of the Preferences editor.

Syntax
NASNodename nodename

440 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Parameters
nodename
Specifies the node name for the NAS file server.

Examples
Options file:
nasnodename nas2
Command line:
-nasnodename=nas2

Nfstimeout
The nfstimeout option specifies the number of seconds the client waits for a status system call on an
NFS file system before it times out.
You can use this option to mitigate the default behavior of status calls on file systems. For example, if an
NFS file system is stale, a status system call is timed out by NFS (soft mounted) or hang the process (hard
mounted).
When the value of this option is changed to a value other than zero, a new thread is created by a caller
thread to issue the status system call. The new thread is timed out by the caller thread and the operation
can continue.
Note: On Solaris, the nfstimeout option can fail if the NFS mount is hard. If a hang occurs, deactivate
the nfstimeout option and mount the NFS file system soft mounted, as follows:

mount -o soft,timeo=5,retry=5 machine:/filesystem /mountpoint

The parameters are defined as follows:

soft
Generates a soft mount of the NFS file system. If an error occurs, the stat() function returns with an
error. If the option hard is used, stat() does not return until the file system is available.
timeo=n
Sets the time out for a soft mount error to n tenths of a second.
retry=n
Set the internal retries and the mount retries to n, the default is 10000.

Supported Clients
This option is for all UNIX and Linux clients. The server can also define this option.

Options File
Place this option in the dsm.sys file within a server stanza or the client options file (dsm.opt).

Syntax
NFSTIMEout number

Parameters
number
Specifies the number of seconds the client waits for a status system call on a file system before timing
out. The range of values is 0 through 120; the default is 0 seconds.

Examples
Options file:
nfstimeout 10

Chapter 10. Processing options 441

 Command line:
-nfstimeout=10
This option is valid only on the initial command line. It is not valid in interactive mode.
Related information
See “NFS hard and soft mounts” on page 209 for a discussion of how NFS hard and soft mounts are
handled.

Nodename
Use the nodename option in your client options file to identify your workstation to the server. You can use
different node names to identify multiple operating systems on your workstation.
When you use the nodename option, you are prompted for the password that is assigned to the node that
you specify, if a password is required.
If you want to restore or retrieve files from the server while you are working from a different workstation,
use the virtualnodename option. You can also use the asnodename option, if it is set up by the
administrator.
When connecting to a server, the client must identity itself to the server. This login identification is
determined in the following manner:
• In the absence of a nodename entry in the dsm.sys file, or a virtualnodename entry in the client
user-options file (dsm.opt), or a virtual node name specified on a command line, the default login ID is
the name that the hostname command returns.
• If a nodename entry exists in the dsm.sys file, the nodename entry overrides the name that the
hostname command returns.
• If a virtualnodename entry exists in the client system-options file (dsm.sys), or a virtual node name
is specified on a command line, it cannot be the same name as the name returned by the hostname
command. When the server accepts the virtual node name, a password is required (if authentication is
on), even if the passwordaccess option is generate. When a connection to the server is established,
access is permitted to any file that is backed up using this login ID.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the dsm.sys file within a server stanza. You can set this option on the General tab, in
the Node Name field of the Preferences editor.

Syntax
NODename nodename

Parameters
nodename
Specifies a 1 to 64 character node name for which you want to request IBM Spectrum Protect
services. The default is the value returned with the hostname command.
Not specifying a node name permits the node name to default to the host name of the workstation

Examples
Options file:
nodename cougar
“Virtualnodename” on page 541

442 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Nojournal
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.
Journal-based incremental backup differs from the traditional full incremental backup in the following
ways:
• Non-default copy frequencies (other than 0) are not enforced on the IBM Spectrum Protect server.
• UNIX special file changes are not detected by the Journal daemon and are not, therefore, backed up.
For these reasons, you want to use the nojournal option periodically to perform a traditional full
incremental backup.

Supported Clients
This option is valid for the AIX and Linux backup-archive client.

Syntax
NOJournal

Parameters
There are no parameters for this option.

Examples
Command line:

dsmc incr /home -nojournal

Related concepts
“Journal-based backup” on page 631
A backup for a particular file system is journal-based when the IBM Spectrum Protect journal daemon is
installed and configured to journal the file system, and a valid journal has been established.

Noprompt
The noprompt option suppresses the confirmation prompt that is presented by the delete group,
delete archive, expire, restore image, and set event commands.
• delete archive
• delete backup
• delete group
• expire
• restore image
Note: The restore image command does not apply to Mac OS X operating systems.

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
NOPrompt

Parameters
There are no parameters for this option.

Chapter 10. Processing options 443

 Examples
Command line:
dsmc delete archive -noprompt "/Users/van/Documents/*"
Command line:
dsmc delete archive -noprompt "/home/project/*"

Nrtablepath
The nrtablepath option specifies the location of the node replication table on the client. The backup-
archive client uses this table to store information about each backup or archive operation to the IBM
Spectrum Protect server.
The server to which you back up your data must be at version 7.1 or newer and must replicate client node
data to the secondary server.
When a failover occurs, the information that is on the secondary server might not be the most recent
version if replication did not happen before the failover. The client can compare the information in the
node replication table against the information that is on the secondary server to determine whether the
backup on the server is the most recent backup version.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys).
This option can also be configured in the client option set on the IBM Spectrum Protect server.

Syntax
NRTABLEPath path

Parameters
path
Specifies the location where the node replication table database is created. The default location is the
backup-archive client installation directory.
For non-root users, you must specify a path that your user ID has write access to, such as a temporary
directory. Most non-root users do not have access to the client installation directory.
Restriction: The node replication table cannot be created in the root directory (/). If you choose to
specify a location for the node replication table, do not specify the root directory.

Example
Options file:
nrtablepath /Volumes/nrtbl
Command line:
Does not apply.
Related tasks
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.
Configuring the client for automated failover

444 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 You can manually configure the client to automatically fail over to the secondary server.

Numberformat
The numberformat option specifies the format you want to use to display numbers.
The AIX and Solaris clients support locales other than English that describe every user interface that
varies with location or language.
By default, the backup-archive and administrative clients obtain format information from the locale
definition in effect at the time the client is called. Consult the documentation on your local system for
details about setting up your locale definition.
Note: The numberformat option does not affect the web client. The web client uses the number format
for the locale that the browser is running in. If the browser is not running in a supported locale, the web
client uses the number format for US English.
You can use the numberformat option with the following commands:
• delete archive
• delete backup
• expire
• query archive
• query backup
• query image
• query nas
• restore
• restore image
• restore nas
• retrieve
• set event

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client user-options file (dsm.opt). You can set this option on the Regional Settings
tab, Number Format field of the Preferences editor.

Syntax
NUMberformat number

Parameters
number
Displays numbers using any one of the following formats. Specify the number (0–6) that corresponds
to the number format you want to use.
0
Use the locale-specified date format. This is the default (does not apply to Mac OS X).
1
1,000.00
This is the default for the following available translations:
• US English

Chapter 10. Processing options 445

 • Japanese
• Chinese (Traditional)
• Chinese (Simplified)
• Korean
2
1,000,00
3
1 000,00
This is the default for the following available translations:
• French
• Czech
• Hungarian
• Polish
• Russian
4
1 000.00
5
1.000,00
This is the default for the following available translations:
• Brazilian Portuguese
• German
• Italian
• Spanish
6
1'000,00
For AIX and Solaris: To define number formats, modify the following lines in the source file of your locale.
Whatever format you select applies both to output and to input.
decimal_point
The character that separates the whole number from its fractional part.
thousands_sep
The character that separates the hundreds from the thousands from the millions.
grouping
The number of digits in each group that is separated by the thousands_sep character.

Examples
Options file:
num 4
Command line:
-numberformat=4
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.

446 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Optfile
The optfile option specifies the client options file to use when you start a backup-archive client
session.

Supported Clients
This option is valid for all clients.

Syntax
OPTFILE = file_name

Parameters
file_name
Specifies an alternate client options file, if you use the fully qualified path name. If you specify only
the file name, the client assumes the file name specified is located in the current working directory.
The default is dsm.opt.
Restriction: Specify the full path when you use this option with the client acceptor daemon (dsmcad),
because the client acceptor daemon changes its working directory to root ("/") after initialization.

Examples
Command line:

dsmc query session -optfile=myopts.opt

Client acceptor daemon:

dsmcad -optfile=/usr/tivoli/tsm/client/ba/bin/myopts.opt

This option is valid only on the initial command line. It is not valid in interactive mode.

Password
The password option specifies a password for IBM Spectrum Protect.
If you do not specify this option and your administrator has set authentication to On, you are prompted for
a password when you start a backup-archive client session.
Note:
1. If the server prompts for a password, the password is not displayed as you enter it. However, if you
use the password option on the command line, your password is displayed as you enter it.
2. If the IBM Spectrum Protect server name changes or the backup-archive clients are directed to a
different server, all clients must re-authenticate with the server because the stored encrypted
password must be regenerated.
The password option is ignored when the passwordaccess option is set to generate.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client user-options file (dsm.opt).

Chapter 10. Processing options 447

 Syntax
PASsword password

Parameters
password
Specifies the password you use to log on to the IBM Spectrum Protect server.
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 server that your client
connects to.
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 b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9 . ! @ # $ % ^ & * _ - + = ` ( )
| { } [ ] : ; < > , ? / ~

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 b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9 . ! @ # $ % ^ & * _ - + = ` ( )
| { } [ ] : ; < > , ? / ~

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 b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 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 AIX, Linux, and Solaris systems:
Enclose the command parameters in single quotation marks (').
Command line example:
dsmc set password -type=vmguest 'Win 2012 SQL' 'tsml2dag
\administrator' '7@#$%^&7'
Quotation marks are not required when you type a password with special characters in an options file.

Examples
Options file:
password secretword

448 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Command line:
-password=secretword
-password='my>pas$word'
This option is valid only on the initial command line. It is not valid in interactive mode.

Passwordaccess
The passwordaccess option specifies whether you want to generate your password automatically or set
as a user prompt.
Your administrator can require a password for your client node by enabling the authentication feature.
Ask your administrator if a password is required for your client node.
If a password is required, you can choose one of the following methods:
• Set the password for your client node yourself and have the client prompt for it each time you request
services.
• Let the client automatically generate a new password for your client node each time it expires, encrypt
and store the password in a file, and retrieve the password from that file when you request services.
You are not prompted for the password.
• If the server is not configured to require a password to log on to it, you can still be prompted to enter
your node password when the backup-archive client establishes a connection with the server. This
behavior occurs if this option, passwordaccess, is allowed to default or if you set it to
passwordaccess prompt. The password that you supply in response to the prompt is used only to
encrypt your login information; it is not used to log onto the server. In this configuration, you can avoid
entering a password by setting this option to passwordaccess generate. Setting passwordaccess
generate causes the client to create, store, and submit the password for you. When
passwordaccess generate is set, the password option is ignored.
Setting the passwordaccess option to generate is required in the following situations:
• When using the HSM client.
• When using the web client.
• When performing NAS operations.
• When using IBM Spectrum Protect for Workstations.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the dsm.sys file within a server stanza. You can set this option on the Authorization
tab, in the Password Access section of the Preferences editor.

Syntax
prompt
PASSWORDAccess
generate

Parameters
prompt
You are prompted for your client node password each time a client connects to the server. This is the
default.
To keep your client node password secure, enter commands without the password and wait for the
client to prompt you for the password.

Chapter 10. Processing options 449

 Each user must know the IBM Spectrum Protect password for your client node. Any user who knows
the password for your client node can gain access to all backups and archives that originate from your
client node. For example: If the user enters the node name and password for your client node from a
different client node, the user becomes a virtual root user.
API applications must supply the password when a session is initiated. The application is responsible
for obtaining the password.
generate
Encrypts and stores your password locally and generates a new password when the old password
expires. The new password is randomly generated by the client. Password constraints vary,
depending on where the passwords are stored and managed, and depending on the version of the
server that your client connects to. Generated passwords are 63 characters in length and contain at
least two of the following characters:
• upper case letters
• lower case letters
• numeric characters
• special characters
Additionally, the first and last character of a generated password is an alphabetic character, and they
can be either upper or lower case. Generated passwords do not contain repeated characters.
A password prompt is displayed when registering a workstation with a server using open registration or if
your administrator changes your password manually.
When logging in locally, users do not need to know the password for the client node. However, by using
the nodename option at a remote node, users can access files they own and files to which another user
grants access.

Examples
Options file:
passwordaccess generate
Command line:
Does not apply.
Related information
For information on where the password is stored, see “Passworddir” on page 450.

Passworddir
The passworddir option specifies the directory location in which to store an encrypted password file.
The default directory for AIX is /etc/security/adsm and for other UNIX and Linux platforms it
is /etc/adsm. The default directory for Mac is /Library/Preferences/Tivoli Storage Manager.
Regardless of where it is stored, the password file that is created by the client is always named TSM.sth.
In turn three files comprise a password file. TSM.KDB stores the encrypted passwords. TSM.sth stores
the random encryption key that is used to encrypt passwords in the TSM.KDB file. This file is protected by
the file system. TSM.IDX is an index file that is used to track the passwords in the TSM.KDB file.

Supported Clients
This option is valid for all UNIX clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

450 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Syntax
PASSWORDDIR directoryname

Parameters
directoryname
Specifies the path in which to store the encrypted password file. The name of the password file is
TSM.sth. If any part of the specified path does not exist, IBM Spectrum Protect attempts to create it.

Examples
Options file:

passworddir "/Users/user1/Library/Preferences/Tivoli Storage Manager/"

passworddir /etc/security/tsm

Command line:
Does not apply.

Pick
The pick option creates a list of backup versions 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.
For images, if you do not specify a source file space and destination file space, the pick list contains all
backed up images. In this case, the images selected from the pick list are restored to their original
location. If you specify the source file space and the destination file space, you can select only one entry
from the pick list.
Use the pick option with the following commands:
• delete archive
• delete backup
• delete group
• expire
• restore
• restore group
• restore image
• restore nas
• retrieve

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
PIck

Parameters
There are no parameters for this option.

Chapter 10. Processing options 451

 Examples
Command line:
dsmc restore "/Users/van/Documents/*" -pick -inactive
Command line:
dsmc restore "/home/project/*" -pick -inactive

Pitdate
Use the pitdate option with the pittime option to establish a point in time to display or restore the
latest version of your backups.
Files that were backed up on or before the date and time you specify, and which were not deleted before
the date and time you specify, are processed. Backup versions that you create after this date and time are
ignored.
Use the pitdate option with the following commands:
• delete backup
• query backup
• query group
• query image
• restore
• restore group
• restore image
• restore nas
When pitdate is used, the inactive and latest options are implicit.

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
PITDate = date

Parameters
date
Specifies the appropriate date. Enter the date in the format you selected with the dateformat
option.
When you include dateformat with a command, it must precede the fromdate, pitdate, and
todate options.

Examples
Command line:
dsmc restore "/Volumes/proj4/myproj/*" -sub=y -pitdate=08/01/2003 -
pittime=06:00:00
Command line:
dsmc restore "/fs1/*" -sub=y -pitdate=08/01/2003 -pittime=06:00:00

452 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Pittime
Use the pittime option with the pitdate option to establish a point in time to display or restore the
latest version of your backups.
Files that were backed up on or before the date and time you specify, and which were not deleted before
the date and time you specify, are processed. Backup versions that you create after this date and time are
ignored. This option is ignored if you do not specify pitdate option.
Use the pittime option with the following commands:
• delete backup
• query backup
• query image
• restore
• restore image
• restore nas

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
PITTime = time

Parameters
time
Specifies a time on a specified date. If you do not specify a time, the time defaults to 23:59:59.
Specify the time in the format you selected with the timeformat option.
When you include the timeformat option in a command, it must precede the fromtime, pittime,
and tottime options.

Examples
Command line:
dsmc query backup -pitt=06:00:00 -pitd=08/01/2003 "/Volumes/proj5/myproj/*"
Command line:
dsmc q b "/fs1/*" -pitt=06:00:00 -pitd=08/01/2003

Postschedulecmd/Postnschedulecmd
The postschedulecmd/postnschedulecmd option specifies a command that the client program
processes after it runs a schedule.
If you want the client program to wait for the command to complete before it continues with other
processing, use the postschedulecmd option. If you do not want to wait for the command to complete
before the client continues with other processing, specify the postnschedulecmd option.
Return code handling and scheduled action behavior depends on both the option specified, and the type
of operation that is scheduled:
• For scheduled operations where the scheduled action is something other than COMMAND:
If the postschedulecmd command does not complete with return code 0 (zero), the return code for
the scheduled event is either 8, or the return code of the scheduled operation, whichever is greater. If
you do not want the postschedulecmd command to be governed by this rule, you can create a script
or batch file that starts the command and exits with return code 0. Then configure postschedulecmd
to start the script or batch file.

Chapter 10. Processing options 453

 • For scheduled operations where the scheduled action is COMMAND:
The return code from the command specified on the postschedulecmd option does not affect the
return code that is reported to the server when the scheduled event completes. If you want the results
of postschedulecmd operations to affect the return code of the scheduled event, include the
postschedulecmd operations in the scheduled action command script instead of using the
postschedulecmd option.
• If the scheduler action cannot be started, and the command specified on the preschedulecmd option
completes with a return code of zero (0), the command specified by the postschedulecmd option is
run.
• The return code from an operation specified on the postnschedulecmd option is not tracked, and
does not influence the return code of the scheduled event.

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.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the Scheduler tab in the Schedule Command text box in the Preferences editor. The server can also
define these options.

Syntax
POSTSChedulecmd cmdstring

POSTNSChedulecmd

Parameters
cmdstring
Specifies the command to process. You can enter a command to be run after a schedule with this
option. Use only one postschedulecmd option.
If the command string contains blanks, enclose the command string in quotation marks. If you placed
quotation marks within the command string, then enclose the entire command string in single
quotation marks.
Use a blank, or null, string for cmdstring if you want to prevent any commands from running that the
IBM Spectrum Protect server administrator uses for postschedulecmd or preschedulecmd. If you
specify a blank or null string on either option, it prevents the administrator from using a command on
both options.
If your administrator uses a blank or null string on the postschedulecmd option, you cannot run a
post-schedule command.
For Mac OS X, if the postschedulecmd schedule command is an AppleScript, you must use the
osascript command to run the script. For example, if "Database Script" is an AppleScript, enter
this command:

postschedulecmd osascript "/Volumes/La Pomme/Scripting/

Database Script"

Examples
Options file:
For Mac OS X: postschedulecmd "/Volumes/La Pomme/Scripting/postsched.sh"
Options file:
postschedulecmd "restart database"

454 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 The command string is a valid command for restarting your database.
Command line:
-postschedulecmd="/Volumes/La Pomme/Scripting/postsched.sh"
Command line:
-postschedulecmd="'restart database'"
This option is valid only on the initial command line. It is not valid in interactive mode.
Related concepts
“Client return codes” on page 263
The backup-archive command-line interface and the scheduler exit with return codes that accurately
reflect the success or failure of the client operation.
Related reference
DEFINE SCHEDULE command

Postsnapshotcmd
The postsnapshotcmd option allows you to run operating system shell commands or scripts after the
backup-archive client starts a snapshot during a snapshot-based backup operation.
AIX only: This option is only applicable to JFS2 snapshot-based file backup or archive and snapshot-
based image backup. For a snapshot-based file backup or archive, use this option with the backup
command, the include.fs option, or in the dsm.sys file.
Linux only: This option is only valid if the LVM is installed and configured on your system, allowing you to
perform a snapshot-based image backup operation.
AIX and Linux only: For a snapshot-based image backup, use this option with the backup image
command, the include.image option, or in the dsm.sys file.
If the postsnapshotcmd fails the operation continues, but appropriate warnings are logged.

Supported Clients
This option is valid for AIX clients and Linux x86_64 clients only. The IBM Spectrum Protect API does not
support this option. The server can also define this option.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can also set this
option on the Image-Snapshot tab of the Preferences editor.

Syntax
POSTSNAPshotcmd "cmdstring"

Parameters
"cmdstring"
Specifies a command to process.
Use the srvprepostsnapdisabled option to prevent the IBM Spectrum Protect server
administrator from executing operating system commands on the client system.
If the command string contains blanks, enclose the command string in quotation marks:

"resume database myDb"

If you placed quotation marks within the command string, then enclose the entire command string in
single quotation marks:

Chapter 10. Processing options 455

 'resume database "myDb"'

Examples
Options file:
postsnapshotcmd "any command"
The command string is a valid command for restarting your application.
Command line:
backup image -postsnapshotcmd="any command"
This option is valid only on the initial command line. It is not valid in interactive mode.
Related information
“Include options” on page 403
“Srvprepostscheddisabled” on page 507

Preschedulecmd/Prenschedulecmd
The preschedulecmd option specifies a command that the client program processes before it runs a
schedule.
The client program waits for the command to complete before it starts the schedule. If you do not want it
to wait, specify prenschedulecmd.
Note:
1. Successful completion of the preschedulecmd command is considered to be a prerequisite to
running the scheduled operation. If the preschedulecmd command does not complete with return
code 0, the scheduled operation and any postschedulecmd and postnschedulecmd commands
will not run. The client reports that the scheduled event failed, and the return code is 12. If you do not
want the preschedulecmd command to be governed by this rule, you can create a script or batch file
that invokes the command and exits with return code 0. Then configure preschedulecmd to invoke
the script or batch file. The return code for the prenschedulecmd command is not tracked, and does
not influence the return code of the scheduled event.
2. The server can also define the preschedulecmd option (and the prenschedulecmd option).

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.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the Scheduler tab, in the Schedule Command dialog box in the Preferences editor.

Syntax
PRESChedulecmd cmdstring

PRENSChedulecmd

Parameters
cmdstring
Specifies the command to process. Use only one preschedulecmd option. You can enter a command
to be executed before a schedule using this option.

456 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 If the command string contains blanks, enclose the command string in quotation marks. If you placed
quotation marks within the command string, then enclose the entire command string in single
quotation marks.
Use a blank or null string for cmdstring if you want to prevent any commands from running that the
IBM Spectrum Protect server administrator uses for postschedulecmd and preschedulecmd. If
you specify a blank or null string on either option, it prevents the administrator from using a command
on both options.
If your administrator uses a blank or null string on the preschedulecmd option, you cannot run a
pre-schedule command.
For Mac OS X, if the preschedulecmd schedule command is an AppleScript, you must use the
osascript command to run the script. For example, if "Database Script" is an apple script, enter
this command:

preschedulecmd osascript "/Volumes/La Pomme/Scripting/

Database Script"

Examples
Options file:

preschedulecmd "<the quiesce command of your database product>

database"

The command string is a valid command for quiescing your database.

Command line:
-preschedulecmd="'quiesce database'"
This option is valid only on the initial command line. It is not valid in interactive mode.
Related concepts
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.

Preservelastaccessdate
Use the preservelastaccessdate option to specify whether a backup or archive operation changes
the last access time.
A backup or archive operation can change the last access time of a file. After an operation, the backup-
archive client can reset the last access time to the value before the operation. The last access time can be
preserved, rather than modified, by the backup-archive client. Resetting the last access time requires
extra processing for each file that is backed up or archived.
If you enable open file support, the last access date for files is always preserved regardless of the setting
for preservelastaccessdate. When open file support is enabled, do not use the
preservelastaccessdate option.
Use this option with the incremental, selective, or archive commands.
Note:
1. This option applies only to files; it does not apply to directories.
2. Resetting the last access date affects backup and archive performance.
3. Resetting the last access date can affect applications that rely on accurate last-access dates such as a
Storage Resource Management (SRM) application.
4. On file systems that are not managed by the IBM Spectrum Protect for Space Management client or
when non-root users back up or archive, the ctime attribute is reset. The last changed time and date
(ctime) attribute is reset to the date and time of the backup or archive operation.

Chapter 10. Processing options 457

 5. The updatectime option takes precedence over the preservelastaccessdate option. If both
options are set to yes, the preservelastaccessdate option is ignored
6. On file systems that are not managed by the IBM Spectrum Protect for Space Management client, do
not use preservelastaccessdate yes and the GPFS mmbackup command. The mmbackup
command and preservelastaccessdate yes selects all files for each backup operation.
7. You cannot reset the last access date of read-only files. The preservelastaccessdate option
ignores read-only files and does not change their date.

Supported Clients
This option is valid for all clients.
The server can also define this option.

Options File
Place this option in the client user options file (dsm.opt). You can set this option on the Backup tab of the
Preferences editor.

Syntax
No
PRESERVELAstaccessdate
Yes

Parameters
No
A backup or archive operation can change the last access date. This value is the default.
Yes
A backup or archive operation does not change the last access date.

Examples
Options file:
preservelastaccessdate yes
Command line:
Incremental /proj/test/test_file -preservelastaccessdate=yes
Related information
mmbackup command: IBM Spectrum Protect requirements
Guidance for integrating IBM Spectrum Scale AFM with IBM Spectrum Protect
Considerations for using IBM Spectrum Protect include and exclude options with IBM Spectrum Scale
mmbackup command

Preservepath
The preservepath option 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.
Use the -subdir=yes option to include the entire subtree of the source directory (directories and files
below the lowest-level source directory) as source to be restored. If a required target directory does not
exist, it is created. If a target file has the same name as a source file, it is overwritten. Use the -
replace=prompt option to have the client prompt you before files are overwritten.
Use the preservepath option with the following commands:
• restore
• restore backupset

458 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
• restore group
• retrieve

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.

Syntax
Subtree
PRESERvepath =
Complete

NOBase

NONe

Parameters
Subtree
Creates the lowest-level source directory as a subdirectory of the target directory. Files from the
source directory are stored in the new subdirectory. This is the default.
Complete
Restores the entire path, starting from the root, into the specified directory. The entire path includes
all the directories except the file space name.
NOBase
Restores the contents of the source directory without the lowest level, or base directory, into the
specified destination directory.
NONe
Restores all selected source files to the target directory. No part of the source path at or above the
source directory is reproduced at the target.
If you specify SUBDIR=yes, the client restores all files in the source directories to the single target
directory.

Examples
Command line:
Assume that the server file space contains the following backup copies:

/fs/h1/m1/file.a
/fs/h1/m1/file.b
/fs/h1/m1/l1/file.x
/fs/h1/m1/l1/file.y

This command:

dsmc res /fs/h1/m1/ /u/ann/ -preser=complete

Restores these directories and files:

/u/ann/h1/m1/file.a
/u/ann/h1/m1/file.b

This command:

dsmc res /fs/h1/m1/ /u/ann/ -preser=nobase

Chapter 10. Processing options 459

 Restores these directories and files:

/u/ann/file.a
/u/ann/file.b

This command:

dsmc res backupset /fs/h1/m1/ /u/ann/ -su=yes

-preser=nobase -loc=file

Restores these directories and files:

/u/ann/file.a
/u/ann/file.b
/u/ann/file.x
/u/ann/file.y

This command:

dsmc res /fs/h1/m1/ /u/ann/ -preser=subtree

Restores these directories and files:

/u/ann/m1/file.a
/u/ann/m1/file.b

This command:

dsmc res /fs/h1/m1/ /u/ann/ -preser=none

Restores these directories and files:

/u/ann/file.a
/u/ann/file.b

This command:

dsmc res /fs/h1/m1/ /u/ann/ -su=yes -preser=complete

Restores these directories and files:

/u/ann/h1/m1/file.a
/u/ann/h1/m1/file.b
/u/ann/h1/m1/l1/file.x
/u/ann/h1/m1/l1/file.y

This command:

dsmc res /fs/h1/m1/ /u/ann/ -su=yes -preser=nobase

Restores these directories and files:

/u/ann/file.a
/u/ann/file.b
/u/ann/l1/file.x
/u/ann/l1/file.y

This command:

dsmc res /fs/h1/m1/ /u/ann/ -su=yes -preser=subtree

Restores these directories and files:

/u/ann/m1/file.a
/u/ann/m1/file.b
/u/ann/m1/l1/file.x
/u/ann/m1/l1/file.y

460 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 This command:

dsmc res /fs/h1/m1/ /u/ann/ -su=yes -preser=none

Restores these directories and files:

/u/ann/file.a
/u/ann/file.b
/u/ann/file.x
/u/ann/file.y

Presnapshotcmd
The presnapshotcmd option allows you to run operating system commands before the backup-archive
client starts a snapshot.
This allows you to quiesce an application before the client starts the snapshot during a snapshot-based
backup or archive.
AIX only: This option is only applicable to JFS2 snapshot-based file backup or archive and snapshot-
based image backup. For a snapshot-based file backup or archive, use this option with the backup
command, the include.fs option, or in the dsm.sys file.
Linux only: This option is only valid if the LVM is installed and configured on your system, allowing you to
perform a snapshot-based image backup.
AIX and Linux only: For a snapshot-based image backup, use this option with the backup image
command, the include.image option, or in the dsm.sys file.
If the presnapshotcmd fails it is assumed that the application is not in a consistent state and the client
stops the operation and display the appropriate error message.

Supported Clients
This option is valid for AIX JFS2 and Linux x86_64 clients only. The IBM Spectrum Protect API does not
support this option. The server can also define this option.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set also this
option on the Image-Snapshot tab of the Preferences editor.

Syntax
PRESNAPshotcmd "cmdstring"

Parameters
"cmdstring"
Specifies a command to process.
Use the srvprepostsnapdisabled option to prevent the IBM Spectrum Protect server
administrator from running operating system commands on the client system.
If the command string contains blanks, enclose the command string in quotation marks:

"quiesce database myDb"

If you placed quotation marks within the command string, then enclose the entire command string in
single quotation marks:

'resume database "myDb"'

Chapter 10. Processing options 461

 Examples
Options file:

presnapshotcmd "any shell command or script"

Command line:

backup image -presnapshotcmd="any shell command or script"

This option is valid only on the initial command line. It is not valid in interactive mode.
Related information
“Include options” on page 403
“Srvprepostscheddisabled” on page 507

Queryschedperiod
The queryschedperiod option specifies the number of hours you want the client scheduler to wait
between attempts to contact the server for scheduled work.
This option applies only when you set the schedmode option to polling. This option is used only when
the scheduler is running.
Your administrator can also set this option. If your administrator specifies a value for this option, that
value overrides the value set in your client options file after your client node successfully contacts the
server.
Tip: If the period set by the queryschedperiod option is much smaller than the randomization window
of a schedule that is set by the server administrator, the start of the schedule can be delayed. To avoid
such a delay, adjust the following values:
• The client action duration (with the SET CLIENTACTDURATION server command)
• The randomization of scheduled start times (with the SET RANDOMIZE server command)
• The value of the queryschedperiod option
Given the settings for the client action duration and the randomization window of a schedule, the
following examples show how to calculate the query schedule period.
Example 1:

Client Action Duration: 1 Days

Schedule Randomization Percentage: 25%
Query Schedule Period: 6 hours

Client Action Duration of 1 day = 24 hours

24 hours x .25 = 6 hours
Use a query schedule period of 6 hours or higher.

Example 2:

Client Action Duration: 3 Days

Schedule Randomization Percentage: 10%
Query Schedule Period: 8 hours

Client Action Duration of 3 days = 72 hours

72 x .10 = 7.2
Use a query schedule period of 8 hours or higher.

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.

462 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax
QUERYSCHedperiod hours

Parameters
hours
Specifies the number of hours the client scheduler waits between attempts to contact the server for
scheduled work. The range of values is 1 - 9999; the default is 4.

Example
Options file:
querysch 6

Querysummary
The querysummary option provides statistics about files, directories and objects that are returned by the
query backup or query archive commands.
The following statistics are provided by the querysummary option:
• The aggregate number of files and directories that are returned by the query backup or query archive
command
• The aggregate amount of data of the objects that are returned by the query backup or query archive
command
• The classic restore memory-utilization estimate to restore objects that are returned by the query
backup or query archive command
• The total number of unique server volumes where the objects that are returned by the query command
reside

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
QUERYSUMMARY

Parameters
There are no parameters for this option.

Examples
Command line:
dsmc q ba '/usr/fs1/*' -sub=yes -querysummary

[root@kaveri:/home/cpark] $ dsmc q ba '/kalafs1/*' -sub=yes -querysummary

IBM Spectrum Protect
Command Line Backup-Archive Client Interface
Client Version 8, Release 1, Level 0.0
Client date/time: 12/09/2016 12:05:35
(c) Copyright by IBM Corporation and other(s) 1990, 2016. All Rights Reserved.

Node Name: KAVERI

Session established with server TEMPLAR: AIX-RS/6000
Server Version 8, Release 1, Level 0.0
Server date/time: 12/09/2016 12:05:35 Last access: 12/07/2016 07:48:59

Chapter 10. Processing options 463

 Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
4,096 B 08/07/08 12:07:30 BASVT2 A /kalafs1/
256 B 08/07/08 12:07:30 BASVT2 A /kalafs1/dir1
10,485,760 B 08/07/08 12:07:30 DEFAULT A /kalafs1/info1
5,242,880 B 08/07/08 12:07:30 DEFAULT A /kalafs1/info2
1,044 B 08/07/08 12:07:30 DEFAULT A /kalafs1/dir1/subfile1
1,044 B 08/07/08 12:07:30 DEFAULT A /kalafs1/dir1/subfile2

Summary Statistics

Total Files Total Dirs Avg. File Size Total Data Memory Est.
----------- ---------- -------------- ---------- ----------
4 2 3.75 MB 15.00 MB 1.07 KB

Estimated Number of Volumes: 2

[root@kaveri:/home/cpark] $

Quiet
The quiet option limits the number of messages that are displayed on your screen during processing..
For example, when you run the incremental, selective, or archive commands, information might
appear about each file that is backed up. Use the quiet option if you do not want to display this
information
When you use the quiet option, error and processing information appears on your screen, and messages
are written to log files. If you do not specify quiet, the default option, verbose is used.

Supported Clients
This option is valid for all clients. The server can also define the quiet option, overriding the client
setting. The IBM Spectrum Protect API does not support this option.

Options File
Place this option in the client user-options file (dsm.opt). You can set this option on the Command Line
tab, Do not display process information on screen checkbox of the Preferences editor.

Syntax
QUIET

Parameters
There are no parameters for this option.

Examples
Options file:
quiet
Command line:
-quiet
This option is valid only on the initial command line. It is not valid in interactive mode.

464 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Quotesareliteral
The quotesareliteral option specifies whether single quotation marks (') or double quotation marks
(") are interpreted literally, when they are included in a file list specification on a filelist option.
Ordinarily, the client requires you to use single or double quotation marks to delimit file specifications
that contain space characters. Some file systems, such as the IBM Spectrum Scale (formerly GPFS) file
system, allow single and double quotation marks in file and directory names.
To prevent errors that would otherwise occur, when file specifications are included on a filelist option
and they contain single quotation marks (') or double quotation marks ("), set quotesareliteral yes.
When quotesareliteral is set to yes, quotation marks that are included in a file list specification on a
filelist option are interpreted literally, as quotation marks, and not as delimiters.
This option applies to any command that accepts a filelist option as command parameter.

Supported Clients
This option is valid for all supported UNIX and Linux platforms. The option is applied to any command that
takes a file list specification as a parameter.

Options File
Place this option in the client user options file (dsm.opt).

Syntax
no
QUOTEsareliteral
yes

Parameters
no
Specifies that single quotation marks (') and double quotation marks (") are interpreted as delimiters
for file list specifications included on a filelist option. The default setting is No.
yes
Specifies that single quotation marks (') and double quotation marks (") are interpreted literally, and
not as delimiters, for file list specifications that are included on a filelist option. Specify this value
if you are backing up files from a file system that allows quotation marks in file or directory names.

Examples
Options file:
QUOTESARELITERAL YES
Command line:
Assuming that the file system allows quotation marks in paths, the following are examples of files in a
file list specification that can be successfully processed if QUOTESARELITERAL is set to YES
Assume the command that is issued is dsmc sel -filelist=/home/user1/important_files,
where important_files.txt contains the list of files to process.

/home/user1/myfiles/"file"1000
/home/user1/myfiles/'file'
/home/user1/myfiles/file'ABC
/home/user1/myfiles/ABC"file"

Related information
For information about the filelist option, see “Filelist” on page 387.
For information about syntax for file specifications, see “Specifying input strings that contain blank
spaces or quotation marks” on page 135.

Chapter 10. Processing options 465

 “Wildcardsareliteral” on page 583

Removeoperandlimit
The removeoperandlimit option specifies that the client removes the 20-operand limit.
If you specify the removeoperandlimit option with the incremental, selective, archive, or
backup image command, the 20-operand limit is not enforced and is restricted only by available
resources or other operating system limits.
The removeoperandlimit option can be useful if you generate scripts which can invoke the command-
line client with a large number of operands. For example, you can prescan a directory tree looking for files
to back up. As each eligible file is discovered, it is added to the operand list of a selective command.
Later, this selective command is submitted by a controlling script. In this case, specifying the
removeoperandlimit option removes the 20-operand limit.
Note:
1. The removeoperandlimit option must be placed immediately after the incremental, selective,
archive, or backup image command before any file specifications.
2. This option does not accept a value. If this option is specified on a command, the 20-operand limit is
removed.
3. Because it adversely affects performance to allow the shell to expand wild cards, use the
removeoperandlimit option in backup or archive operations in which wild cards are not used.
4. The removeoperandlimit option is valid only on the incremental, selective, archive, and
backup image commands in batch mode. It is not valid in the client options file (dsm.opt) or dsm.sys
file.

Supported Clients
This option is valid for all UNIX and Linux clients.

Syntax
REMOVEOPerandlimit

Parameters
There are no parameters for this option.

Examples
Command line:
-removeoperandlimit

Replace
The replace option specifies whether to overwrite existing files on your workstation, or to prompt you
for your selection when you restore or retrieve files.
Important: The replace option does not affect recovery of directory objects. Directory objects are
always recovered, even when specifying replace=no. To prevent overwriting existing directories, use the
filesonly option.
You can use this option with the following commands:
• restore
• restore backupset
• restore group
• retrieve

466 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Note: Replace prompting does not occur during a scheduled operation. If you set the replace option to
prompt, the backup-archive client skips files without prompting you during a scheduled operation.

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 user-options file (dsm.opt). You can set this option on the Restore tab,
Action for files that already exist section of the Preferences editor.

Syntax
Prompt
REPlace
All

Yes

No

Parameters
Prompt
For nonscheduled operations, you specify whether to overwrite existing files. For scheduled
operations, existing files are not overwritten and no prompts are displayed. This is the default.
All
All existing files are overwritten, including read-only files. If access to a file is denied, you are
prompted to skip or overwrite the file. No action is taken on the file until there is a response to the
prompt.
Yes
Existing files are overwritten, except read-only files. For nonscheduled operations, you specify
whether to overwrite existing read-only files. For scheduled operations, existing read-only files are
not overwritten and no prompts are displayed. If access to a file is denied, the file is skipped.
No
Existing files are not overwritten. No prompts are displayed.

Examples
Options file:
replace all
Command line:
-replace=no
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.

Replserverguid
The replserverguid option specifies the globally unique identifier (GUID) that is used when the client
connects to the secondary server during failover. The GUID is used to validate the secondary server to
ensure that it is the expected server.
The replication GUID is different from the machine GUID of the server. It is generated one time for a
server that is doing the replication and never changes.

Chapter 10. Processing options 467

 This option must be specified within a replservername stanza in the client options file. The
replservername stanza contains connection information about the secondary server.
This option is set by the IBM Spectrum Protect server administrator for the client node. During the normal
(non-failover) logon process, the option is sent to the client and is saved in the client options file.
Do not edit this option during normal operations.
Edit this option only during situations such as the following ones:
• The primary server is offline and the information for the secondary server is not in the options file.
• The secondary server information is out-of-date or incorrect.
Any values that you edit are removed or updated the next time you log in to the primary server.

Supported Clients
This option is valid for all clients.

Options File
This option is placed in the dsm.sys file within the replservername stanza.

Syntax
replserverguid serverguid

Parameters
serverguid
Specifies the GUID of the secondary server that is used during a failover.

Examples
Options file:
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.02
Command line:
Does not apply.
Options file:
The following example demonstrates how to specify options for three different servers in the
dsm.sys file, and how to reference the secondary server.
Connection information for multiple secondary server is presented in stanzas. Each stanza is
identified by the replservername option and the name of the secondary server.
The servername stanza must contain the myreplicationserver option, which points to the
secondary server that is specified by the replservername stanza.
Only one secondary server can be specified per servername stanza.

REPLSERVERNAME TargetReplicationServer1
REPLTCPSERVERADDRESS TargetReplicationServer1
REPLTCPPORT 1505
REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.00

REPLSERVERNAME TargetReplicationServer2
REPLTCPSERVERADDRESS TargetReplicationServer2
REPLTCPPORT 1505
REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.02

SErvername server_a
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname1.example.com
PASSWORDAccess prompt

468 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 MYREPLICATIONServer TargetReplicationServer1

SErvername server_b
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname2.example.com
PASSWORDAccess generate
INCLExcl /adm/tsm/archive.excl
MYREPLICATIONServer TargetReplicationServer2

SErvername server_c
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname3.example.com
PASSWORDAccess generate
MYREPLICATIONServer TargetReplicationServer1

Related concepts
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
Configuring the client for automated failover
You can manually configure the client to automatically fail over to the secondary server.

Replservername
The replservername option specifies the name of the secondary server that the client connects to
during a failover.
The replservername option begins a stanza in the client options file that contains connection
information about the secondary server.
This option is set by the IBM Spectrum Protect server administrator for the client node. During the normal
(non-failover) logon process, the option is sent to the client and is saved in the client options file.
Do not edit this option during normal operations.
Edit this option only during situations such as the following ones:
• The primary server is offline and the information for the secondary server is not in the options file.
• The secondary server information is out-of-date or incorrect.
Any values that you edit are removed or updated the next time you log in to the primary server.

Supported Clients
This option is valid for all clients.

Options File
This option is placed in the client-system options dsm.sys.

Syntax
replservername repl_servername

Parameters
repl_servername
Specifies the name of the secondary server to be used during a failover. This value is usually the name
of the secondary server, not the host name of the server.

Chapter 10. Processing options 469

 Examples
Options file:
REPLSERVERName TargetReplicationServer1
Command line:
Does not apply.
Options file:
The following example demonstrates how to specify options for three different servers in the
dsm.sys file, and how to reference the secondary server.
Connection information for multiple secondary server is presented in stanzas. Each stanza is
identified by the replservername option and the name of the secondary server.
The servername stanza must contain the myreplicationserver option, which points to the
secondary server that is specified by the replservername stanza.
Only one secondary server can be specified per servername stanza.

REPLSERVERNAME TargetReplicationServer1
REPLTCPSERVERADDRESS TargetReplicationServer1
REPLTCPPORT 1505
REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.00

REPLSERVERNAME TargetReplicationServer2
REPLTCPSERVERADDRESS TargetReplicationServer2
REPLTCPPORT 1505
REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.02

SErvername server_a
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname1.example.com
PASSWORDAccess prompt
MYREPLICATIONServer TargetReplicationServer1

SErvername server_b
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname2.example.com
PASSWORDAccess generate
INCLExcl /adm/tsm/archive.excl
MYREPLICATIONServer TargetReplicationServer2

SErvername server_c
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname3.example.com
PASSWORDAccess generate
MYREPLICATIONServer TargetReplicationServer1

Related concepts
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
Configuring the client for automated failover
You can manually configure the client to automatically fail over to the secondary server.

Replsslport
The replsslport option specifies the TCP/IP port on the secondary server that is SSL-enabled. The
replsslport option is used when the client connects to the secondary server during a failover. This

470 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
option is deprecated if you are connecting to an IBM Spectrum Protect server V8.1.2 and later levels, and
V7.1.8 and later V7 levels.
The replsslport option is sent to the client by the primary server only if the secondary server is
configured for SSL.
This option is applicable only when the client is configured to use SSL for secure communications
between the IBM Spectrum Protect server and client. If the client is not configured to use SSL, the port
that is specified by the repltcpport option is used. You can determine whether the client uses SSL by
verifying the SSL client option.
This option must be specified within a replservername stanza in the client options file. The
replservername stanza contains connection information about the secondary server.
During the normal (non-failover) logon process, this option is sent to the client and is saved in the client
options file.
Do not edit this option during normal operations.
Edit this option only during situations such as the following ones:
• The primary server is offline and the information for the secondary server is not in the options file.
• The secondary server information is out-of-date or incorrect.
Any values that you edit are removed or updated the next time you log in to the primary server.

Supported Clients
This option is valid for all clients.

Options File
This option is placed in the dsm.sys file within the replservername stanza.

Syntax
replsslport port_address

Parameters
port_address
Specifies the TCP/IP port address that is enabled for SSL and that is used to communicate with the
secondary server.

Examples
Options file:
REPLSSLPORT 1506
Command line:
Does not apply.
Options file:
The following example demonstrates how to specify options for three different servers in the
dsm.sys file, and how to reference the secondary server.
Connection information for multiple secondary server is presented in stanzas. Each stanza is
identified by the replservername option and the name of the secondary server.
The servername stanza must contain the myreplicationserver option, which points to the
secondary server that is specified by the replservername stanza.
Only one secondary server can be specified per servername stanza.

REPLSERVERNAME TargetReplicationServer1
REPLTCPSERVERADDRESS TargetReplicationServer1

Chapter 10. Processing options 471

 REPLTCPPORT 1505
REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.00

REPLSERVERNAME TargetReplicationServer2
REPLTCPSERVERADDRESS TargetReplicationServer2
REPLTCPPORT 1505
REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.02

SErvername server_a
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname1.example.com
PASSWORDAccess prompt
MYREPLICATIONServer TargetReplicationServer1

SErvername server_b
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname2.example.com
PASSWORDAccess generate
INCLExcl /adm/tsm/archive.excl
MYREPLICATIONServer TargetReplicationServer2

SErvername server_c
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname3.example.com
PASSWORDAccess generate
MYREPLICATIONServer TargetReplicationServer1

Related concepts
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
Configuring the client for automated failover
You can manually configure the client to automatically fail over to the secondary server.

Repltcpport
The repltcpport option specifies the TCP/IP port on the secondary server to be used when the client
connects to the secondary server during a failover.
This option must be specified within a replservername stanza in the client options file. The
replservername stanza contains connection information about the secondary server.
This option is set by the IBM Spectrum Protect server administrator for the client node. During the normal
(non-failover) logon process, the option is sent to the client and is saved in the client options file.
Do not edit this option during normal operations.
Edit this option only during situations such as the following ones:
• The primary server is offline and the information for the secondary server is not in the options file.
• The secondary server information is out-of-date or incorrect.
Any values that you edit are removed or updated the next time you log in to the primary server.

Supported Clients
This option is valid for all clients.

Options File
This option is placed in the dsm.sys file within the replservername stanza.

472 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Syntax
repltcpport port_address

Parameters
port_address
Specifies the TCP/IP port address that is used to communicate with the secondary server.

Examples
Options file:
REPLTCPPort 1500
Command line:
Does not apply.
Options file:
The following example demonstrates how to specify options for three different servers in the
dsm.sys file, and how to reference the secondary server.
Connection information for multiple secondary server is presented in stanzas. Each stanza is
identified by the replservername option and the name of the secondary server.
The servername stanza must contain the myreplicationserver option, which points to the
secondary server that is specified by the replservername stanza.
Only one secondary server can be specified per servername stanza.

REPLSERVERNAME TargetReplicationServer1
REPLTCPSERVERADDRESS TargetReplicationServer1
REPLTCPPORT 1505
REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.00

REPLSERVERNAME TargetReplicationServer2
REPLTCPSERVERADDRESS TargetReplicationServer2
REPLTCPPORT 1505
REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.02

SErvername server_a
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname1.example.com
PASSWORDAccess prompt
MYREPLICATIONServer TargetReplicationServer1

SErvername server_b
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname2.example.com
PASSWORDAccess generate
INCLExcl /adm/tsm/archive.excl
MYREPLICATIONServer TargetReplicationServer2

SErvername server_c
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname3.example.com
PASSWORDAccess generate
MYREPLICATIONServer TargetReplicationServer1

Related concepts
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.

Chapter 10. Processing options 473

 Related tasks
Configuring the client for automated failover
You can manually configure the client to automatically fail over to the secondary server.

Repltcpserveraddress
The repltcpserveraddress option specifies the TCP/IP address of the secondary server to be used
when the client connects to the secondary server during a failover.
This option must be specified within a replservername stanza in the client options file. The
replservername stanza contains connection information about the secondary server.
This option is set by the IBM Spectrum Protect server administrator for the client node. During the normal
(non-failover) logon process, the option is sent to the client and is saved in the client options file.
Do not edit this option during normal operations.
Edit this option only during situations such as the following ones:
• The primary server is offline and the information for the secondary server is not in the options file.
• The secondary server information is out-of-date or incorrect.
Any values that you edit are removed or updated the next time you log in to the primary server.

Supported Clients
This option is valid for all clients.

Options File
This option is placed in the dsm.sys file within the replservername stanza.

Syntax
REPLTCPServeraddress server_address

Parameters
server_address
Specifies a TCP/IP address for a server that is 1 - 64 characters in length. Specify a TCP/IP domain
name or a numeric IP address. The numeric IP address can be either a TCP/IP v4 or TCP/IP v6
address. You can use only IPv6 addresses if you specified the commmethod V6Tcpip option.

Examples
Options file:
REPLTCPServeraddress dsmchost.example.com
Command line:
Does not apply.
Options file:
The following example demonstrates how to specify options for three different servers in the
dsm.sys file, and how to reference the secondary server.
Connection information for multiple secondary server is presented in stanzas. Each stanza is
identified by the replservername option and the name of the secondary server.
The servername stanza must contain the myreplicationserver option, which points to the
secondary server that is specified by the replservername stanza.
Only one secondary server can be specified per servername stanza.

REPLSERVERNAME TargetReplicationServer1
REPLTCPSERVERADDRESS TargetReplicationServer1
REPLTCPPORT 1505

474 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.00

REPLSERVERNAME TargetReplicationServer2
REPLTCPSERVERADDRESS TargetReplicationServer2
REPLTCPPORT 1505
REPLSSLPORT 1506
REPLSERVERGUID 91.0f.ef.90.5c.cc.11.e1.ae.34.08.00.00.00.00.02

SErvername server_a
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname1.example.com
PASSWORDAccess prompt
MYREPLICATIONServer TargetReplicationServer1

SErvername server_b
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname2.example.com
PASSWORDAccess generate
INCLExcl /adm/tsm/archive.excl
MYREPLICATIONServer TargetReplicationServer2

SErvername server_c
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname3.example.com
PASSWORDAccess generate
MYREPLICATIONServer TargetReplicationServer1

Related concepts
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
Configuring the client for automated failover
You can manually configure the client to automatically fail over to the secondary server.

Resourceutilization
Use the resourceutilization option in your option file to regulate the level of resources the IBM
Spectrum Protect server and client can use during processing.

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 dsm.sys file within a server stanza. You can set this option on the General tab, in
the Resource Utilization field of the Preferences editor.

Syntax
RESOURceutilization number

Parameters
number
Specifies the level of resources the IBM Spectrum Protect server and client can use during
processing. The range of values that you can specify is 1 - 100. The default value is 2.

Chapter 10. Processing options 475

 Examples
Options file:
resourceutilization 7
Command line:
-resourceutilization=7
This option is valid only on the initial command line. It is not valid in interactive mode.

Regulating backup and archive sessions

When you request a backup or archive, the client can use more than one session to the server.
The default is to use a maximum of two sessions; one to query the server and one to send file data. The
client can use only one server session if you set the resourceutilization option to 1.
A client can use more than the default number of sessions when it connects to the IBM Spectrum Protect
server. For example, resourceutilization 10 permits up to eight sessions with the server. Multiple
sessions can be used for querying the server and sending file data.
Multiple query sessions are used when you specify multiple file specifications with a backup or archive
command. For example, if you enter the following commands and you specify resourceutilization
5, the client might start a second session to query files on file space B.

inc /Volumes/filespaceA /Volumes/filespaceB

Whether the second session starts depends on how long it takes to query the server about files that are
backed up on file space A. The client might also try to read data from the file system and send it to the
server on multiple sessions.
Note: During a backup operation, if you enter multiple file specifications, the result might be that files
from one file specification are stored on multiple tapes and interspersed with files from different file
specifications. This can decrease restore performance. 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).
Related reference
“Collocatebyfilespec” on page 322
Use the collocatebyfilespec option to specify whether the backup-archive client uses only one
server session to send objects generated from one file specification.

Regulating restore sessions

When you request a restore, the default is to use a maximum of one session.
Additional restore sessions are based on:
• resourceutilization value
• how many tapes on which the requested data is stored
• how many tape drives are available
• the maximum number of mount points that are allowed for the node
Note:
1. If all of the files are on disk, only one session is used. There is no multi-session for a pure disk storage
pool restore. However, if you are performing a restore in which the files are on 4 tapes and others are
on disk, you could use up to 5 sessions during the restore.
2. The IBM Spectrum Protect server can set the maximum number of mount points a node can use on the
server by using the MAXNUMMP parameter. If the resourceutilization option value exceeds the
value of the MAXNUMMP on the server for a node, the backup can fail with an Unknown System Error
message.

476 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 3. You can get a multi-session restore from your single restore command, and from a single volume on
the server, if that volume is device class FILE.
For example, if the data you want to restore is on 5 different tape volumes, the maximum number of
mount points is 5 for your node, and resourceutilization is set to 3, then 3 sessions are used for the
restore. If you increase the resourceutilization setting to 5, then 5 sessions are used for the
restore. There is a 1 to 1 relationship between the number of restore sessions that are allowed and the
resourceutilization setting. Multiple restore sessions are only allowed for no-query restore
operations.

Multiple client session considerations

This topic lists some items to consider when working with multiple client sessions.
The following factors can affect the throughput of multiple sessions:
• The ability of the server to handle multiple client sessions. Is there sufficient memory, multiple storage
volumes, and processor cycles to increase backup throughput?
• The ability of the client to drive multiple sessions (sufficient processor cycles, memory, etc.).
• The configuration of the client storage subsystem. File systems that are striped across multiple disks,
using either software striping or RAID-5 can better handle an increase in random read requests than a
single drive file system. Additionally, a single drive file system might not see performance improvement
if it attempts to handle many random concurrent read requests.
• Sufficient bandwidth in the network to support the increased traffic.
Potentially undesirable aspects of running multiple sessions include:
• The client could produce multiple accounting records.
• The server might not start enough concurrent sessions. To avoid this, the server maxsessions parameter
must be reviewed and possibly changed.
• A query node command might not summarize client activity.
• It is possible that files are restored instead of hard links.
Restoring files instead of hard links can occur when the following criteria are all true:
– You restore an entire file system.
– During the restore operation, the value of the resourceutilization option is greater than 1.
– The file system contained hard links when the file system was backed up.
The chance of restoring linked files instead of hard links increases as the number of sessions increases.
When you restore a file system that contained hard links when the file system was backed up, set
resourceutilization=1 to ensure that hard links are restored.

Retryperiod
The retryperiod option 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. Use this option only when the scheduler is running.
Your administrator can also set this option. If your administrator specifies a value for this option, that
value overrides the value in your client system options file after your client node successfully contacts the
server.

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 system-options file (dsm.sys) within a server stanza. You can set this option
on the Scheduler tab, in the Retry period field of the Preferences editor.

Chapter 10. Processing options 477

 Syntax
RETRYPeriod minutes

Parameters
minutes
Specifies the number of minutes the client scheduler waits between attempts to contact the server, or
to process a scheduled command that fails. The range of values is 1 through 9999; the default is 20.

Examples
Options file:
retryp 10
Command line:
-retryperiod=10
This option is valid only on the initial command line. It is not valid in interactive mode.

Revokeremoteaccess
The revokeremoteaccess option restricts an administrator with client access privilege from accessing
a client workstation that is running the web client.
This option does not restrict administrators with client owner, system, or policy privilege from accessing
your workstation through the web client.

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 system-options file (dsm.sys) within a server stanza. You can set this option
on the Web Client tab of the Preferences editor.

Syntax
None
REVOKEremoteaccess
Access

Parameters
None
Does not revoke access to administrators who have client access authority for the client. This is the
default.
Access
Revokes access to administrators who have client access authority for the client.

Examples
Options file:
revokeremoteaccess none
Command line:
Does not apply.

478 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Schedcmddisabled
The schedcmddisabled option specifies whether to disable the scheduling of commands by the server
action=command option on the define schedule server command.
This 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 disable the scheduling of commands defined by your IBM Spectrum Protect administrator by
setting the schedcmddisabled option to yes.
Use the query schedule command to query the schedules defined by your administrator.

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 dsm.sys file within a server stanza.

Syntax
No
SCHEDCMDDisabled
Yes

Parameters
Yes
Specifies that the server disables the scheduling of commands using the action=command option on
the DEFINE SCHEDULE server command.
No
Specifies that the server does not disable the scheduling of commands using the action=command
option on the DEFINE SCHEDULE server command. This is the default.

Examples
Options file:
schedcmddisabled no
Command line:
Does not apply.
Related information
“Query Schedule” on page 657

Schedcmdexception
The schedcmexception option is used in conjunction with the schedcmddisabled option to disable
the scheduling of commands by the server action=command option on the DEFINE SCHEDULE server
command, except for specific command strings.
You must specify the exact string that matches the "objects" definition in the schedule for the scheduled
server command to be accepted. If the string does not match exactly (for example, there is an extra space
or the capitalization is different), the scheduled command action is blocked.
You can provide multiple schedcmexception options in the options file. This option is not honored if
schedcmddisabled is not enabled. The placement of this option in the options file is independent of the
placement of the schedcmddisabled option.

Chapter 10. Processing options 479

 Supported Clients
This option is valid for all clients. This option is not valid in the IBM Spectrum Protect server client options
set.

Options File
Place this option in the dsm.sys file within a server stanza.

Syntax
SCHEDCMDException string

Parameters
string
For commands scheduled by the action=command option on the DEFINE SCHEDULE server
command, this parameter indicates the objects pattern to enable if the schedcmddisabled=yes
option is specified. This parameter is case sensitive, and must match the command string on the IBM
Spectrum Protect server schedule definition.

Example
Options file:
schedcmddisabled yes
schedcmdexception "start echo hello, world!"
Related information
“Schedcmddisabled” on page 479

Schedgroup
The schedgroup option assigns a schedule to a group.
An example of the use of this option is to group multiple daily local backup schedules with a single server
backup schedule.

Supported Clients
This option is valid for all clients as a command-line option for the server DEFINE SCHEDULE command.
This option cannot be added to a client option set that is on the IBM Spectrum Protect server.

Syntax
SCHEDGROUP schedule_group_name

Parameters
schedule_group_name
Specifies the name of the schedule group. You can specify up to 30 characters for the name.
For a list of valid characters that you can use in the schedule group name, see Naming IBM Spectrum
Protect objects.

Examples
The following example commands group schedules SCHED_A_1, SCHED_A_2, SCHED_A_3, and
SCHED_A_4 in to schedule group GROUP_A.
Command line:
This example shows a local backup at 6 AM:

480 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 define schedule standard SCHED_A_1 Type=Client ACTion=Backup SUBACTion=VM
OPTions='-vmfulltype=vstor -vmbackuptype=fullvm -vmbackuplocation=local -
domain.vmfull="SCHEDULE-TAG" -asnodename=DC_SARTRE_WB -SCHEDGROUP=GROUP_A'
STARTDate=02/06/2017 STARTTime=06:00:00 SCHEDStyle=Enhanced DAYofweek=ANY
This example shows a local backup at 12 PM:
define schedule standard SCHED_A_2 Type=Client ACTion=Backup SUBACTion=VM
OPTions='-vmfulltype=vstor -vmbackuptype=fullvm -vmbackuplocation=local -
domain.vmfull="SCHEDULE-TAG" -asnodename=DC_SARTRE_WB -SCHEDGROUP=GROUP_A'
STARTDate=02/06/2017 STARTTime=12:00:00 SCHEDStyle=Enhanced DAYofweek=ANY
This example shows a local backup at 6 PM:
define schedule standard SCHED_A_3 Type=Client ACTion=Backup SUBACTion=VM
OPTions='-vmfulltype=vstor -vmbackuptype=fullvm -vmbackuplocation=local -
domain.vmfull="SCHEDULE-TAG" -asnodename=DC_SARTRE_WB -SCHEDGROUP=GROUP_A'
STARTDate=02/06/2017 STARTTime=18:00:00 SCHEDStyle=Enhanced DAYofweek=ANY
This example shows a local and server backup at midnight:
define schedule standard SCHED_A_4 Type=Client ACTion=Backup SUBACTion=VM
OPTions='-vmfulltype=vstor -vmbackuptype=fullvm -vmbackuplocation=both -
domain.vmfull="SCHEDULE-TAG" -asnodename=DC_SARTRE_WB -SCHEDGROUP=GROUP_A'
STARTDate=02/06/2017 STARTTime=00:00:00 SCHEDStyle=Enhanced DAYofweek=ANY
Tip: Ensure that each schedule in the group can complete before the next schedule is set to start.
This option is valid only on the initial command line. It is not valid in interactive mode.

Schedlogmax
The schedlogmax option specifies the maximum size of the schedule log (dsmsched.log) and web
client log (dsmwebcl.log), in megabytes.
This option causes the log files that get created for scheduler events (dsmsched.log) and web client
events (dsmwebcl.log) to wrap around when they reach their maximum size. As scheduler and web
client events are logged, log records are added to the end of the log files until the maximum specified size
is reached. When the maximum specified size is reached, a log record saying Continued at
beginning of file is placed as the last record in the file. Subsequent logging is resumed at the
beginning of the file. The end of the wrapped log is indicated by a record saying END OF DATA.
When you set the schedlogmax option, scheduler and web client log messages are not saved in a prune
file. If you want to prune logs and save the pruned log entries to another file, see the
schedlogretention option.
If you change from log wrapping (schedlogmax option) to log pruning (schedlogretention option), all
existing log entries are retained and the log is pruned using the new schedlogretention criteria.
If you change from log pruning (schedlogretention option) to log wrapping (schedlogmax option), all
records in the existing logs are copied to a file containing the pruned entries. For example, log records
pruned from the dsmsched.log file are copied to dsmsched.pru. Log records pruned from
dsmwebcl.log are copied to dsmweblog.pru. The existing logs (dsmsched.log and dsmwebcl.log)
are emptied, and logging begins using the new log wrapping criteria.
If you simply change the value of the schedlogmax option, the existing log is extended or shortened to
accommodate the new size. If the value is reduced, the oldest entries are deleted to reduce the file to the
new size.
If neither schedlogmax nor schedlogretention is specified, the error log can grow without any limit
on its size. You must manually manage the log contents to prevent the log from depleting disk resources.
When the log has been created with neither option specified, if you later issue a command and specify the
schedlogretention option, the log is pruned using the retention value specified. When the log has
been created with neither option specified, if you later issue a command and specify the schedlogmax
option, the existing log is treated as if it was a pruned log. That is, the content of the dsmsched.log file

Chapter 10. Processing options 481

 is copied to a file called dsmsched.pru, the content of dsmwebcl.log is copied to a file called
dsmwebcl.pru, and new log entries are created in dsmsched.log and dsmwebcl.log, and both files
wrap when they reach their maximum size.
Note: If you specify a non-zero value for schedlogmax (which enables log wrapping), you cannot use the
schedlogretention option to create pruned logs. Logs can be pruned or wrapped, but not both.
Logs created with the schedlogmax option contain a log header record that contains information similar
to this example record:

LOGHEADERREC 661 104857600 IBM Spectrum Protect 8.1.0.0 Fri Dec 9 06:46:53 2014

Note that the dates and time stamps in the LOGHEADERREC text are not translated or formatted using the
settings specified on the dateformat or timeformat options.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.
You can also set this option on the Client Preferences > Scheduler tab in the GUI, by selecting Enable
scheduler log file wrapping and by specifying a non-zero maximum size for the log file. To prevent log
file wrapping, set the maximum size to zero. When the maximum wrapping is set to zero, clearing or
setting the Enable scheduler log file wrapping option has no effect; log wrapping does not occur if the
maximum size is set to zero.

Syntax
SCHEDLOGMAX size

Parameters
size
Specifies the maximum size, in megabytes, for the log file. The range of values is 0 to 2047; the
default is 0, which disables log file wrapping and allows the log file to grow indefinitely.

Examples
Options file:
schedlogmax 100
Command line:
-schedlogmax=100
This option is valid only on the initial command line. It is not valid in interactive mode.

Schedlogname
The schedlogname option specifies the path and file name where you want to store schedule log
information.
Use this option only when you want to store schedule log information. This option applies only when the
scheduler is running.
If this option is not used, the dsmsched.log file is created in the same directory as the dsmerror.log
file.
When you run the schedule command, output from scheduled commands appears on your screen.
Output is also sent to the file you specify with this option. If any part of the path you specify does not
exist, the client attempts to create it.

482 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 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 system-options file (dsm.sys) within a server stanza. You can set this option
on the Scheduler tab, in the Schedule Log text box, in the Preferences editor.
Note: Set the DSM_LOG environment variable to name a directory where the log is to be placed. The
directory specified must have permissions which allow write access from the account under which the
client is run. The root directory is not a valid value for DSM_LOG.

Syntax
SCHEDLOGName filespec

Parameters
filespec
Specifies the path and file name where you want to store schedule log information when processing
scheduled work. If any part of the path you specify does not exist, the client attempts to create it.
If you specify a file name only, the file is stored in your current directory. The default is the current
working directory with a file name of dsmsched.log. The dsmsched.log file cannot be a symbolic
link.
For Mac OS X, if you specify a file name only, the file is stored in your default folder. The default
directories are:

~/Library/Logs/tivoli/tsm
/Library/Logs/tivoli/tsm

Examples
Options file:

SCHEDLOGN /Users/user1/Library/Logs/schedlog.jan

schedlogname /home/mydir/schedlog.jan

Command line:
-schedlogname=/Users/user1/Library/Logs/schedlog.jan
Command line:
-schedlogname=/home/mydir/schedlog.jan
This option is valid only on the initial command line. It is not valid in interactive mode.
Related information
See “Errorlogname” on page 372 for more information on placement of the dsmsched.log file.

Schedlogretention
The schedlogretention option specifies the number of days to keep entries in the schedule log
(dsmsched.log) and the web client log (dsmwebcl.log), and whether to save the pruned entries in
another file.
The schedule log (dsmsched.log) is pruned when the scheduler starts and after a scheduled event
completes. Pruned entries are written to a file called dsmsched.pru.
The web client log (dsmwebcl.log) is pruned during the initial start of the client acceptor daemon.
Pruned entries are written to a file called dsmwebcl.pru.

Chapter 10. Processing options 483

 If you change from log pruning (schedlogretention option) to log wrapping (schedlogmax option), all
records in the existing log are copied to the pruned log (dsmsched.pru and dsmwebcl.pru), and the
existing logs (dsmsched.log and dsmwebcl.log) are emptied, and logging begins using the new log
wrapping criteria.
If you change from log wrapping (schedlogmax option) to log pruning (schedlogretention option), all
existing log entries are retained and the log is pruned using the new schedlogretention criteria.
Pruned entries are saved in their corresponding *.pru files.
If neither schedlogmax nor schedlogretention is specified, the logs can grow without any limit on
their size. You must manually manage the log contents to prevent the log from depleting disk resources.
When the log has been created with neither option specified, if you later issue a command and specify the
schedlogretention option, the log is pruned using the retention value specified. When the log has
been created with neither option specified, if you later issue a command and specify the schedlogmax
option, the existing log is treated as if it was a pruned log. That is, the content of the dsmsched.log file
is copied to a file called dsmsched.pru, the content of dsmwebcl.log is copied to dsmwebcl.pru, and
new log entries are created in both dsmsched.log and dsmwebcl.log, and both files wrap when they
reach their maximum size.
Note: If you specify schedlogretention option to create pruned logs, you cannot specify the
schedlogmax option. Logs can be pruned or wrapped, but not both.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.
You can also set this option on the Client preferences > Scheduler tab in the GUI, by selecting Prune old
entries and by specifying a value for Prune entries older than. Selecting the Save pruned entries option
saves the pruned scheduler log entries in the dsmsched.pru log file. Selecting Save pruned entries also
saves web client log entries in the dsmwebcl.pru log file.

Syntax
N D
SCHEDLOGRetention
days S

Parameters
N or days
Specifies how long to wait before pruning the log.
N
Do not prune the log. This permits the log to grow indefinitely. This is the default.
days
Specifies the number of days to keep log file entries before pruning. The range of values is zero
through 9999.
D or S
Specifies whether to save the pruned entries. Use a space or comma to separate this parameter from
the previous one.
D
Discards the log entries when pruning the log. This is the default.
S
Saves the log entries when pruning the log.

484 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Pruned entries are copied to the file of pruned entries (dsmsched.pru or dsmsched.pru), which
is stored in the same directory as the log.

Examples
Options file:
schedlogretention 30 S
Command line:
-schedlogretention=30,S
This option is valid only on the initial command line. It is not valid in interactive mode.

Schedmode
The schedmode option specifies whether you want to use the polling mode (your client node
periodically queries the server for scheduled work), or the prompted mode (the server contacts your
client node when it is time to start a scheduled operation).
All communication methods can use the client polling mode, but only TCP/IP can use the server prompted
mode.
This option applies only if you are using the TCP/IP communication method, and the schedule command
is running.
Your administrator can specify that the server support both modes or just one mode. If your administrator
specifies that both modes are supported, you can select either schedule mode. If your administrator
specifies only one mode, you must specify that mode in your dsm.sys file or scheduled work is not
processed.
If you specify prompted mode, you should consider supplying values for the tcpclientaddress and
tcpclientport options in your dsm.sys file or on the schedule command; the client can then be
contacted at either an address or a port of your choice (useful for client systems with multiple network
interface cards).
Note:
1. When changing the setting of this option in the dsm.sys file you must stop and restart the scheduler
service for the setting to take effect.
2. The server can also define this option.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the Scheduler tab, in the Schedule Mode section in the Preferences editor.

Syntax
POlling
SCHEDMODe
PRompted

Parameters
POlling
The client scheduler queries the server for scheduled work at prescribed time intervals. This is the
default. You can set the time intervals using the queryschedperiod option.

Chapter 10. Processing options 485

 PRompted
The client scheduler waits for the server to contact your client node when scheduled work needs to be
done.
Note:
1. If you use the dsmc schedule command and both schedmode prompted and commmethod
V6Tcpip are specified, the client and IBM Spectrum Protect server must be configured for IPv6.
Additionally, the client host name must be set up for the IPv6 address.

Examples
Options file:
schedmode prompted
Command line:
-schedmod=po
This option is valid only on the initial command line. It is not valid in interactive mode.
Related reference
“Cadlistenonport” on page 320
The cadlistenonport option specifies whether to open a listening port for the client acceptor.
“Tcpclientaddress” on page 524
The tcpclientaddress option 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.
“Tcpclientport” on page 524
The tcpclientport option specifies a TCP/IP port number for the server to contact the client when the
server begins the server prompted scheduled operation.

Schedrestretrdisabled
The schedrestretrdisabled option specifies whether to disable the execution of restore or retrieve
schedule operations.

Supported Clients
This option is valid for all clients. The server cannot define this option. The IBM Spectrum Protect API
does not support this option.

Options File
Place this option in the dsm.sys file within a server stanza for the scheduler. You can set this option on the
Scheduler tab in the Schedule Command section in the Preferences editor.

Syntax
No
SCHEDRESTRETRDisabled
Yes

Parameters
No
Specifies that the client does not disable the execution of restore and retrieve schedule operations.
This parameter is the default.
Yes
Specifies that the client disables the execution of restore and retrieve schedule operations.

486 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Examples
Options file:
schedrestretrdisabled yes
Command line:
Does not apply.

Scrolllines
The scrolllines option specifies the number of lines of information that are displayed on your screen
at one time.
Use this option when you set the scrollprompt option to Yes.
You can use the scrolllines option with the following commands only:
• delete filespace
• query archive
• query backup
• query backupset
• query filespace
• query group
• query image
• query nas
• query node
• query options

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 client user-options file (dsm.opt). You can set this option in Command Line >
Number of lines to display in the Preferences editor.

Syntax
SCROLLLines number

Parameters
number
Specifies the number of lines of information that are displayed on your screen at one time. The range
of values is 1 through 80; the default is 20.

Examples
Options file:
scrolllines 25
Command line:
-scrolll=25
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.

Chapter 10. Processing options 487

Scrollprompt
The scrollprompt option specifies whether you want the bakup-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.
You can use the scrollprompt option with the following commands only:
• delete filespace
• query archive
• query backup
• query backupset
• query filespace
• query group
• query image
• query nas
• query node
• query options

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 client user-options file (dsm.opt). You can set this option on the Command Line
tab, Pause after displaying the following number of lines field of the Preferences editor.

Syntax
No
SCROLLPrompt
Yes

Parameters
No
Scrolls to the end of the list and stops. This is the default.
Yes
Stops and waits after displaying the number of lines you specified with the scrolllines option. The
following prompt is displayed on the screen:

Press ‘Q' to quit, ‘C' to continuous scroll, or ‘Enter' to

continue.

Examples
Options file:
scrollprompt yes
Command line:
-scrollp=yes
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.

488 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Servername
In your dsm.sys file, the servername option specifies the name you want to use to identify a server and
to begin a stanza containing options for that server. You can name and specify options for more than one
server.
The following example demonstrates how to specify options for two different servers:

SErvername server_a
COMMMethod TCPip
TCPPort 1500
TCPServeraddress server_hostname2.domain.company.com
PASSWORDAccess prompt
GRoups tsm
USERs sullivan mushock tallan
INCLExcl /adm/tsm/backup.excl

SErvername server_b
COMMMethod SHAREdmem
shmport 1520
PASSWORDAccess generate
GRoups system tsm
INCLExcl /adm/tsm/archive.excl

In your client user-options file (dsm.opt), the servername option specifies which server, of those named
in your dsm.sys file, to contact for backup-archive services. When specified in a client user-options file
(dsm.opt) or on the command line, the servername option overrides the default server specified in your
client system options file.
Note:
1. You cannot use the servername option to override the server that is specified for migration in your
client system options file.
2. If the IBM Spectrum Protect server name changes or backup-archive clients are directed to a different
IBM Spectrum Protect server, all clients must have a new password initialized for the new server
name.

Supported Clients
This option is for all UNIX and Linux clients.

Options File
Place this option in the client user options file (dsm.opt) and in the client system options file (dsm.sys). In
the dsm.sys file, the servername option is the beginning of a server stanza.
Do not modify this option in dsm.opt when you are running the Backup-Archive client in a command-line
session or when your are running the Backup-Archive client GUI.

Syntax
SErvername servername

Parameters
servername
In your dsm.sys file, specify the name you want to assign to a particular server. In your client user-
options file (dsm.opt) or on the command line, specify the name of the server you want to contact for
backup-archive services. The value of servername in dsm.opt must match a servername value in
dsm.sys, or the client cannot contact the server.
A server name is not case sensitive; it can have up to 64 characters.

Chapter 10. Processing options 489

 Examples
Options file:
servername server_a
Command line:
-se=server_b
This option is valid only on the initial command line. It is not valid in interactive mode.

Sessioninitiation
Use the sessioninitiation option to control whether the server or client initiates sessions through a
firewall. The default is that the client initiates sessions. You can use this option with the schedule
command.
For the client scheduler, you do not need 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 must be 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. If you set the sessioninitiation option to serveronly,
with the exception of client acceptor daemon-managed schedulers, the command-line client, and the
backup-archive client GUI still attempt to initiate sessions.
Attention: You cannot use the dsmcad for scheduling when you set the sessioninitiation
option to serveronly
Note: If you set the sessioninitiation option to serveronly, the client setup wizard and scheduler
service are unable to authenticate to the IBM Spectrum Protect server. In this case, you can execute the
scheduler from the command line (dsmc schedule) and enter the password for your node when
prompted.
A similar problem can occur if an encryption key is required for backup operations. In this case, you can
execute the scheduler from the command line (dsmc schedule) and enter the encryption key when
prompted. After the password and encryption key are updated, you must restart the scheduler.
If you set the sessioninitiation option to client, the client initiates sessions with the server 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.
Note:
1. The IBM Spectrum Protect server can specify SESSIONINITiation=clientorserver or
SESSIONINITiation=serveronly on the register node and update node commands. If the
server specifies SESSIONINITiation=clientorserver, the client can decide which method to
use. If the server specifies SESSIONINITiation=serveronly, all sessions are initiated by the
server.
2. 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.

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 dsm.sys file within a server stanza. You can set this option on the Scheduler tab,
Session Initiation field of the Preferences editor.

490 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Syntax
Client
SESSIONINITiation
SERVEROnly

Parameters
Client
Specifies that the client initiates sessions with the server 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.
SERVEROnly
Specifies that the server will not accept client requests for sessions. All sessions must be initiated by
server prompted scheduling on the port defined on the client with the tcpclientport option.
Except for client acceptor daemon-managed schedulers, the command-line client, and the backup-
archive client GUI still attempt to initiate sessions.
If the server AUTHENTICATION option is set to LDAP, do not set the client sessioninitiation
option to serveronly; if you do, schedules cannot run.

Examples
Options file:
sessioninitiation serveronly
Command line:
schedule -sessioninitiation=serveronly
This option is valid only on the initial command line. It is not valid in interactive mode.
Related information
“Configuring the scheduler” on page 63
“Tcpclientport” on page 524

Setwindowtitle
Use the setwindowtitle option to modify the title of the administrative client command window during
processing.
For example, when you run the administrative client command (dsmadmc) on the client node and the
administrative client connects to the IBM Spectrum Protect server, the following text is displayed in the
title of the command window:

CONNECTED TO SERVER: servername(serverhostname)

where servername is the name of the IBM Spectrum Protect server, and serverhostname is the host name
of the IBM Spectrum Protect.
When you use the setwindowtitle option, any user-defined title of the command window is
overwritten. After you disconnect the administrative client from the IBM Spectrum Protect server, the
window title is reset to the user-defined window title.
On AIX, Linux, and Oracle Solaris operating systems, the terminal window title is reset to the title
"Terminal" after you disconnect from the server.

Supported Clients
This option is valid for all clients.

Chapter 10. Processing options 491

 Options File
Place this option in the client user-options file (dsm.opt) or the client system-options file (dsm.sys).

Syntax
No
SETWINDOWTITLE
Yes

Parameters
No
The title of the administrative client command window is not changed during processing. This
parameter is the default.
Yes
The IBM Spectrum Protect server name and host server name is displayed in the title of the
administrative client command window.

Examples
Options file:
SETWINDOWTITLE YES
Command line:
-setwindowtitle=yes
This option is valid only on the initial command line. It is not valid in interactive mode.

Shmport
The shmport option specifies the TCP/IP port address of a server when using shared memory. All shared
memory communications start with a TCP/IP connection.
Note: The value specified for the shmport option in the dsm.sys file must match the value specified for
shmport in the server options file.

Supported Clients
This option is valid for AIX, Linux, and Oracle Solaris clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax
SHMPort port_number

Parameters
port_number
Specifies the port number. You can specify a value from 1000 to 32767. The default value is 1510.

Examples
Options file:
shmport 1580
Command line:
Does not apply.

492 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Showmembers
Use the showmembers option to display all members of a group.
You can use the showmembers option with the query group, and restore group commands.
The showmembers option is not valid with the inactive option. If you want to display members of a
group that are not currently active, use the pitdate and pittime options.

Supported Clients
This option is valid for all UNIX and Linux clients except Mac OS X.

Syntax
SHOWMembers

Parameters
There are no parameters for this option.

Examples
Command line:

restore group /virtfs/* -pick -showmembers

Skipacl
The skipacl option allows you to include or exclude access control list (ACL) data during a backup or
archive operation; by default, ACL data is included.
When this option is set to yes, the backup-archive client does not include ACL data when it backs up or
archives files and directories. The default is no, which enables the ACL data to be included when objects
are copied to the server. You should only set the skipacl to yes when ACLs are not defined on the file
system, or when you are certain that you do not need the ACL data when the files are retrieved or
restored.

Supported Clients
This option is valid for all UNIX and Linux clients. On Linux and AIX systems, setting skipacl to yes also
omits the extended attributes.

Options File
Place this option in the client user options (dsm.opt) file.

Syntax
No
SKIPACL
Yes

Parameters
No
If you specify No, the ACL data is backed up. This is the default.
Yes
If you specify Yes, the ACL data is not backed up, and consequently, it cannot be restored.
skipacl=yes overrides skipaclupdatecheck settings.

Chapter 10. Processing options 493

 Examples
Options file:
skipacl yes

Skipaclupdatecheck
The skipaclupdatecheck option disables checksum and size comparisons of ACL data.
When set to yes (default is no), the backup-archive client will not perform checksum and size
comparisons before or after backup and during incremental processing (ACL checksum from previous
backup and current ACL) to detect ACL updates. However, current ACL data is backed up if the file is
selected for backup due to other reasons. If only ACLs are updated on a file, the next incremental backup
will not recognize this ACL update, and the file is not backed up.

Supported Clients
This option is valid for all UNIX and Linux clients.

Options File
Place this option in the client user options (dsm.opt) file.

Syntax
No
SKIPACLUPdatecheck
Yes

Parameters
No
If you specify No, the client performs checksum and size comparisons of the ACL data, before and
after backup and during incremental processing. This is the default.
Yes
If you specify Yes, the client does not perform checksum and size comparisons of the ACL data.

Examples
Options file:
skipaclup yes

Snapdiff
Using the snapdiff (snapshot difference) option with the incremental command streamlines the
incremental backup process. The command runs an incremental backup of the files that were reported as
changed by NetApp instead of scanning all of the volume for changed files.
The snapdiff option is for backing up NAS/N-Series file server volumes that are NFS attached.
You must configure a user ID and password on the backup-archive client to enable snapshot difference
processing. For more information about setting up the snapdiff option, see “Configuring NetApp and
IBM Spectrum Protect for snapshot difference incremental backups” on page 104.
Use this option with an incremental backup of a NAS file server volume, instead of a simple incremental
backup or an incremental backup with the snapshotroot option, whenever the NAS file server is
running ONTAP 7.3.0, or later. Do not use the snapdiff and snapshotroot options together.
Restriction: Incremental backups with snapshot difference processing are only available with the Linux
x86_64 backup-archive client.
The first time that you run an incremental backup with the snapshot difference option, a snapshot is
created (the base snapshot) and a traditional incremental backup is run by using this snapshot as the

494 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
source. The name of the snapshot that is created is recorded in the IBM Spectrum Protect server
database. The initial incremental backup must complete without failure in order for the next backup
operation to use snapshot difference processing.
The second time an incremental backup is run with this option, a newer snapshot is either created, or an
existing one is used (depending on the value set for the diffsnapshot option) to find the differences
between these two snapshots. The second snapshot is called the diffsnapshot, or differences snapshot.
The client then incrementally backs up the files that are reported as changed, by NetApp, to the IBM
Spectrum Protect server. The file system that you select for snapshot difference processing must be
mounted to the root of the volume. You cannot use the snapdiff option for any file system that is not
mounted to the root of the volume. After you backed up the data with the snapdiff option, the snapshot
that was used as the base snapshot is deleted from the snapshot directory.
On Linux systems, the snapshot directory is in .snapshot.
The client does not delete any snapshots that it did not create.
When a snapshot-differential-incremental backup operation completes, the client ensures that only the
most recently-registered base snapshot persists on the filer volume. All snapshots that are created by a
snapshot-differential-incremental backup on the backup-archive client begin with the characters "TSM_".
If you use a snapshot tool other than the backup-archive client to produce snapshots, ensure that you do
not use the string "TSM_" at the beginning of the snapshot name. If the snapshot names begin with
"TSM_", the files are deleted when the client initiates the next snapshot-differential-incremental backup
operation.
To run a snapshot-differential-incremental backup of read-only NetApp filer volumes, the
useexistingbase option must be specified to prevent an attempt to create a snapshot on the read-only
volume. Also, specify the name of the base snapshot to use (basesnapshotname option) and the name
of the differential snapshot to use (diffsnapshotname option).
For NAS and N-Series file servers that are running ONTAP 7.3.0, or later, you can use the
createnewbase option to back up any files that were skipped because of one of the following reasons:
• A file is excluded because the include-exclude file has an exclude rule in effect. A file is excluded when
you did not change the include-exclude file, but you removed the rule that excluded the file. The NetApp
API detects file changes only between two snapshots, not changes to the include-exclude file.
• If you added an include statement to the option file, that include option does not take effect unless
NetApp detects that the file changes occurred. The client does not inspect each file on the volume
during backup.
• You used the dsmc delete backup command to explicitly delete a file from the IBM Spectrum
Protect server inventory. NetApp does not detect that a file was manually deleted from the server.
Therefore, the file remains unprotected in IBM Spectrum Protect storage until it is changed on the
volume and the change is detected by NetApp, signaling the client to back it up again.
• Policy changes such as changing the policy from mode=modified to mode=absolute are not
detected.
• The entire file space is deleted from the IBM Spectrum Protect inventory. This action causes the
snapshot difference option to create a snapshot to use as the source, and runs a full incremental
backup.
• A file is excluded from backup because the file name contains a character that is not in the 7 bit-ASCII
character set. The createnewbase option creates a base snapshot and uses it as a source to run a full
incremental backup. NetApp controls what constitutes a changed object.
Tip: You can use the snapdiffhttps option to run snapshot-differential-incremental backups of
NetApp filers with a secure HTTPS connection. To successfully run snapshot-differential-incremental
backups, previous releases of the backup-archive client required HTTP administrative access to be
enabled on the NetApp 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 filer.
Snapshot differential backup operations are not supported in the IBM Spectrum Protect for Virtual
Environments environment. You cannot run snapshot differential backup operations of a file system that

Chapter 10. Processing options 495

 resides on a NetApp filer on a host where the Data Protection for VMware or Data Protection for Microsoft
Hyper-V data mover is also installed.
In the list of options that are used by the traditional incremental command, the last column shows the
interaction of each option with the snapdiff option. The following information describes the definitions
of valid, not valid, and no effect:
Valid
Processing runs normally when the option is used.
Not valid
If the option is used with the snapdiff option, an error message is generated.
No effect
The option can be used, but it is ignored.

Table 76. Incremental command: Related options

Option Where specified With
snapdiff
asnodename “Asnodename” on page 309 Client system options file Valid
(dsm.sys) or command line.
automount “Automount” on page 316 Client options file (dsm.opt). No effect
basesnapshotname “Basesnapshotname” on Client options file (dsm.opt) or Valid
page 319 command line.
changingretries “Changingretries” on page Client system options file No effect
321 (dsm.sys) or command line.
compressalways “Compressalways” on page 325 Client options file (dsm.opt) or Valid
command line.
compression “Compression” on page 326 Client system options file Valid
(dsm.sys) within a server stanza,
or command line.
createnewbase “Createnewbase” on page 329 Command line only. Valid
diffsnapshot “Diffsnapshot” on page 343 Command line only. Valid
diffsnapshotname “Diffsnapshotname” on page Client options file (dsm.opt) or Valid
344 command line.
dirsonly “Dirsonly” on page 346 Command line only. Valid
domain “Domain” on page 349 Client system options file Valid
(dsm.sys), client user-options file
(dsm.opt), or command line.
efsdecrypt “Efsdecrypt” on page 363 Client system options file No effect
(dsm.sys), client user-options file
(dsm.opt), or command line.
enablelanfree “Enablelanfree” on page 367 Client system options file Valid
(dsm.sys) or command line.
encryptiontype “Encryptiontype” on page 368 system-options file (dsm.sys) Valid
within a server stanza.
encryptkey “Encryptkey” on page 369 System-options file (dsm.sys) Valid
within a server stanza.
exclude.fs.nas “Exclude options” on page 374 Client system options file No effect
(dsm.sys).

496 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 76. Incremental command: Related options (continued)
Option Where specified With
snapdiff
filelist “Filelist” on page 387 Command line only. Not valid
filesonly “Filesonly” on page 390 Command line only. Valid
followsymboliclink “Followsymbolic” on page Client options file (dsm.opt). No effect
391
include.fs.nas “Include options” on page 403 Client system options file No effect
(dsm.sys) or command line.
inclexcl “Inclexcl” on page 402 Client system options file Valid, but only
(dsm.sys). when a file
change is
detected by
NetApp.
incrbydate “Incrbydate” on page 420 Command line only. Not valid
memoryefficientbackup This option is allowed in both No effect
“Memoryefficientbackup” on page 434 dsm.sys and dsm.opt, but the
value in dsm.opt is ignored if it is
also in dsm.sys. You can also
place this option within a server
stanza, or on the initial command
line.
monitor “Monitor” on page 438 Command line only. Not valid
nojournal “Nojournal” on page 443 Command line only. Not valid
postsnapshotcmd “Postsnapshotcmd” on page Client system options file Valid
455 (dsm.sys) or with the
include.fs option.
Client user-options file (dsm.opt) Valid
preservelastaccessdate
or command line.
“Preservelastaccessdate” on page 457

presnapshotcmd “Presnapshotcmd” on page 461 Client system options file Valid

(dsm.sys) or with the
include.fs option.
removeoperandlimit “Removeoperandlimit” on Command line only. Valid
page 466
skipaclupdatecheck “Skipaclupdatecheck” on Client options file (dsm.opt). Valid
page 494
snapdiffhttps “Snapdiffhttps” on page 501 Command line only. Valid
snapshotcachesize “Snapshotcachesize” on Client system options file No effect
page 502 (dsm.sys) or with the
include.fs option.
snapshotproviderfs “Snapshotproviderfs” on System-options file (dsm.sys) Not valid
page 503 within a server stanza or with the
include.fs option.

Chapter 10. Processing options 497

 Table 76. Incremental command: Related options (continued)
Option Where specified With
snapdiff
snapshotproviderimage Client system options file Not valid
“Snapshotproviderimage” on page 504 (dsm.sys) or with the
include.image option.
snapshotroot “Snapshotroot” on page 504 Command line only. Not valid
subdir “Subdir” on page 515 Client options file (dsm.opt) or Not valid
command line.
tapeprompt “Tapeprompt” on page 520 Client options file (dsm.opt) or Valid
command line.
toc “Toc” on page 531 Command line only. Not valid
useexistingbase “Useexistingbase” on page Command line only. Valid
535
virtualfsname “Virtualfsname” on page 539 Command line only. Not valid
virtualmountpoint “Virtualmountpoint” on Client system options file Not valid
page 539 (dsm.sys).

Supported Clients
This option is valid for Linux x86_64 clients.

Syntax
SNAPDiff

Parameters
There are no parameters for this option.

Examples
Command line:
Perform a snapshot-differential-incremental backup of an NFS mounted file system /vol/vol1
hosted on the file server homestore.example.com, where /net/home1 is the mount point
of /vol/vol1.
incremental -snapdiff -diffsnapshot=latest /net/home1
Command line:
Run a one-time full incremental backup after detecting that the NetApp server has migrated to a
unicode-enabled file server from a server that did not support unicode file names.

dsmc incremental -snapdiff -createnewbase=migrate /net/home1

Run a snapshot-differential-incremental backup after detecting that the NetApp server has migrated
to a unicode-enabled file server from a server that did not support unicode file names. This command
suppresses the warning message.

dsmc incremental -snapdiff -createnewbase=ign /net/home1

Perform a full incremental backup because you made some include or exclude changes:

dsmc incremental -snapdiff -createnewbase=yes /net/home1

498 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Related concepts
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.
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.
Related tasks
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.
Related reference
Snapdiffhttps
Specify the snapdiffhttps option to use a secure HTTPS connection for communicating with a NetApp
filer during a snapshot differential backup.
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.
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.
Useexistingbase
The useexistingbase option is used when you back up snapshots that are on NetApp filer volumes.
The useexistingbase option indicates that the latest snapshot that exists on the volume being backed
up, is to be used as the base snapshot, during a snapshot differential backup operation.
Diffsnapshot
The diffsnapshot option controls whether the backup-archive client creates the differential snapshot
when it runs a snapshot difference incremental backup.
Set Password
The set password command changes the IBM Spectrum Protect password for your workstation, or sets
the credentials that are used to access another server.

Snapdiffchangelogdir
The snapdiffchangelogdir option defines the location where the client stores persistent change logs
that are used for snapshot differential backup operations.
Important: If you previously used snapshot differential backups with a backup-archive client that is older
than Version 8.1.2, the first snapshot differential backup that you run with the V8.1.2 or later client will be
a full progressive incremental backup. To avoid this full progressive incremental backup, move the
existing change log files from the old location specified by the stagingdirectory option to the new
location specified by the snapdiffchangelogdir option before you run the first snapshot differential
backup.
For example, run the following copy command:

cp -R /tmp/TSM/TsmSnapDiff /opt/tivoli/tsm/client/ba/TsmSnapDiff

The change log files have the following naming patterns:

Chapter 10. Processing options 499

 .../TSM/TsmSnapDiff/.TsmSnapdiffChangeLogs/NetAppFiler/
SnapdiffChangeLog__VolumeName__.tsmDB
.../TSM/TsmSnapDiff/.TsmSnapdiffChangeLogs/NetAppFiler/
SnapdiffChangeLog__VolumeName__.tsmDB.Lock

where:
• NetAppFiler is the host name or IP address of the storage virtual machine (SVM) from the cluster
management server or the 7-mode file server.
• VolumeName is the volume that you want to protect.

Supported Clients
This option is valid for Linux x86_64 clients. This option can also be defined on the server.

Options File
Place this option in the client options file (dsm.opt). When snapdiffchangelogdir is specified on the
command line, it overrides the values that are specified in the options file. You can set this option on the
General tab of the Preferences editor.

Syntax
SNAPDIFFCHANGELOGDir path

Parameters
path
Specifies the directory path where the client stores persistent change logs for snapshot differential
backup operations. If you do not specify the snapdiffchangelogdir option, the client uses the
directory where the client is installed. The default installation directory is:

/opt/tivoli/tsm/client/ba

The exact name of the change log file is in the following format:

snapdiff_change_log_dir/TsmSnapDiff/.TsmSnapdiffChangeLogs/NetAppFiler/
SnapdiffChangeLog__VolumeName__.tsmDB

where:
• snapdiff_change_log_dir is the name of the directory for storing the snapshot differential change
logs, as specified by the snapdiffchangelogdir option.
• NetAppFiler is the host name or IP address of the storage virtual machine (SVM) from the cluster
management server or the 7-mode file server.
• VolumeName is the volume that you want to protect.
A lock file is also created to prevent the change log file from being updated by different snapshot
differential backups that are running at the same time.

Examples
Options file:
snapdiffchangelogdir /tmp/tsmdata
Command line:
-snapdiffchangelogd=/tmp/tsmdata
Related reference
“Diffsnapshot” on page 343

500 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 The diffsnapshot option controls whether the backup-archive client creates the differential snapshot
when it runs a snapshot difference incremental backup.
“Snapdiff” on page 494
Using the snapdiff (snapshot difference) option with the incremental command streamlines the
incremental backup process. The command runs an incremental backup of the files that were reported as
changed by NetApp instead of scanning all of the volume for changed files.

Snapdiffhttps
Specify the snapdiffhttps option to use a secure HTTPS connection for communicating with a NetApp
filer during a snapshot differential backup.
When you specify this option, the backup-archive client can establish a secure administrative session with
the NetApp filer regardless of whether HTTP administrative access is enabled on the NetApp filer.
Important: The default communication protocol that the backup-archive client uses to establish the
administrative session with the NetApp filer is HTTP. To use a secure HTTPS connection, you must specify
the snapdiffhttps option whenever you run a snapshot differential backup.
Restrictions:
The following restrictions apply to snapshot differential backups with HTTPS:
• 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.
• The snapdiffhttps option does not apply to vFilers because the HTTPS protocol is not supported on
the NetApp vFiler.
• The snapdiffhttps option is available only by using the command-line interface. It is not available for
use with the backup-archive client GUI.

Supported Clients
This option is valid for Linux x86_64 clients.

Options File
This option is valid only on the command-line interface. You cannot enter it in a client options file.

Syntax
SNAPDIFFHTTPS

Parameters
There are no parameters for this option.

Examples
Command line:
Issue the following command on a Linux system, with an NFS mounted file system /vol/vol1
hosted on the file server homestore.example.com, where /net/home1 is the mount point
of /vol/vol1.

dsmc incr /net/home1 -snapdiff -snapdiffhttps

Chapter 10. Processing options 501

 Related concepts
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.
Related reference
Snapdiff
Using the snapdiff (snapshot difference) option with the incremental command streamlines the
incremental backup process. The command runs an incremental backup of the files that were reported as
changed by NetApp instead of scanning all of the volume for changed files.

Snapshotcachesize
Use the snapshotcachesize option to specify an appropriate size to create the snapshot.
The size estimation is needed for storing the original data blocks for modified and deleted data for the
point in time when the snapshot was taken.
For snapshot-based file backup or archive, use the snapshotcachesize option with the include.fs
option, or in the server stanza in the dsm.sys file.
For snapshot-based image backups, use the snapshotcachesize option with the backup image
command, the include.image option, or in your dsm.sys file.

Supported Clients
This option is valid for AIX and Linux clients only. The IBM Spectrum Protect API does not support this
option. The server can also define this option.

Options File
Place this option in the server stanza in the dsm.sys file. You can set this option on the Image-Snapshot
tab of the Preferences editor.

Syntax
SNAPSHOTCACHESize size

Parameters
size
Specifies an appropriate size to create the snapshot for storing the original data blocks for modified
and deleted data for the point in time when the snapshot was taken. The value is the percent of the
file system size that is changed due to file system activity. The range of values is 1 to 100 percent. For
AIX JFS2 and Linux the default value is 100 percent of the file system size. If a sufficient amount of
free space is not available to create the snapshot, the command fails with an error message. You can
then either increase the size of the volume group or retry the operation. If based on your experience
with your AIX JFS2 file system activity, you find that a snapshot size of 100 percent is not necessary,
you can fine-tune the value.

Examples
Options file:

snapshotcachesize 95
AIX only: include.fs /kalafs1
snapshotproviderfs=JFS2 snapshotcachesize=95

AIX only: include.image /kalafs2

snapshotcachesize=95

502 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Linux only: include.image /linuxfs1
snapshotcachesize=100

Command line:
-snapshotcachesize=95
Related information
See “Include options” on page 403 for more information about include.fs.

Snapshotproviderfs
Use the snapshotproviderfs option to enable snapshot-based file backup and archive operations, and
to specify a snapshot provider.
You must be a root user to perform a snapshot-based file backup or archive operation. If you are not a
root user, the operation fails with an error message.

Supported Clients
This option is valid for AIX clients only. The IBM Spectrum Protect API does not support this option. The
server can also define this option.

Options File
Specify this option in the server stanza of the system-options file, dsm.sys, to enable snapshots for all
JFS2 file systems on the client. You can override the client-wide option for a specific operation by
specifying this option on the command line for the backup and archive commands. You can also override
the client-wide option for a specific file system by using the include.fs statement in the dsm.sys file. You
can also set this option using the Preferences editor.

Syntax
SNAPSHOTPROVIDERFs value

Parameters
value
Specifies one of the following values:
JFS2
Specifies that you want to perform a snapshot-based file backup or archive while the file system is
available to other system applications. Valid for JFS2 file systems on AIX clients only.
NONE
Specifies that no snapshots should be used. A file backup or archive operation is performed using the
specified file system. This is the default.

Examples
Options file:

snapshotproviderfs JFS2
include.fs /kalafs1 snapshotproviderfs=JFS

Command line:
-SNAPSHOTPROVIDERFs=JFS2

Chapter 10. Processing options 503

Snapshotproviderimage
Use the snapshotproviderimage option to enable snapshot-based image backup, and to specify a
snapshot provider.
You must be a root user to perform a snapshot-based image backup operation. If you are not a root user,
the operation fails with an error message.

Supported Clients
This option is valid for AIX and Linux clients only. The IBM Spectrum Protect API does not support this
option. The server can also define this option.

Options File
Specify this option in the server stanza of the system-options file, dsm.sys, to enable snapshots for all the
file systems on the client. You can override the client-wide option for a specific operation by specifying
this option on the command line for the backup image command. You can also override the client-wide
option for a specific file system using the include.image statement in the dsm.sys file. You can also set
this option using the Preferences editor.

Syntax
SNAPSHOTPROVIDERImage value

Parameters
value
Specifies one of the following values:
JFS2
Specifies that you want to perform a snapshot-based image backup while the file system is available
to other system applications. This is the default for JFS2 file systems. Valid for AIX clients only.
LINUX_LVM
Specifies that you want to perform a snapshot-based image backup while the file system is available
to other system applications. This is the default for file systems residing on logical volumes created by
the Linux Logical Volume Manager. Valid for Linux clients only.
NONE
Specifies that you do not want to perform a snapshot-based image backup operation. This performs a
static image backup operation using the specified file system. This is the default for file systems other
than AIX JFS2 and Linux LVM.

Examples
Options file:

snapshotprovideri JFS2
include.image /kalafs1 snapshotprovideri=JFS2

Command line:
-SNAPSHOTPROVIDERImage=NONE

Snapshotroot
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.
The snapshotroot option can be used to back up NFS mounted file systems. Both the backup
specification (source) and the snapshotroot value can be an NFS mounted file specification. For

504 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
example, the snapshotroot option can be used to backup an NFS file system that is hosted on a
network-attached storage (NAS) that supports snapshot.
This option should be used with an incremental backup of a NAS file server volume instead of a simple
incremental or incremental with snapshotroot option whenever the NAS file server is running ONTAP
V7.3 for performance reasons. The snapdiff and snapshotroot options should not be used together.
In the following example, filesystem test495 is NFS-mounted from a NAS file server philo and /
philo/test945/.snapshot/backupsnap represents the snapshot that is created at the NAS file
server.

dsmc i /philo/test945 -snapshotroot=/philo/test945/.snapshot/backupsnap

You can also specify a directory with the snapshotroot option when you backup each file set as a
separate file space.
The snapshotroot option does not provide any facilities to take a volume snapshot, only to manage
data that is created by a volume snapshot.
For example, consider an application that takes a snapshot of the /usr file system and mounts it
as /snapshot/day1. If you back up this data by using the following command, a unique file space that is
called /snapshot/day1 is created on the server.

dsmc incremental /snapshot/day1

However, you might want to associate the snapshot data with the data already processed for the /usr file
system. Using the snapshotroot option, you can associate the data with the file space corresponding to
the /usr file system on the IBM Spectrum Protect server:

dsmc incremental /usr -snapshotroot=/snapshot/day1

On a subsequent day, you can back up a snapshot that was written to an alternative location, but
managed under the same file space on the server:

dsmc incremental /usr -snapshotroot=/snapshot/day2

You can perform incremental backups, selective backups, or archives of a single directory, directory
structure, or single file by using the snapshotroot option. In all instances, the snapshotroot option
must identify the root of the logical volume that was created by the snapshot. For example:

dsmc incremental /usr/dir1/* -subdir=yes

-snapshotroot=/snapshot/day1
dsmc selective /usr/dir1/sub1/file.txt
-snapshotroot=/snapshot/day1
dsmc archive /usr/dir1/sub1/*.txt
-snapshotroot=/snapshot/day1

If you want to include or exclude specific file specifications, the include and exclude statements should
contain the name of the file system that was the source of the snapshot (the /usr file system), and not
the name of the target of the snapshot (/snapshot/day1). Doing this allows you to preserve a set of
include and exclude statements regardless of the name of the logical volume to which the snapshot is
written. The following are examples of include and exclude statements.

include /usr/dir1/*.txt 1yrmgmtclass

exclude /usr/mydocs/*.txt

The following include-exclude statements are not valid because they contain the name of the snapshot:

include /snapshot/day1/dir1/*.txt 1yrmgmtclass

exclude /snapshot/day1/mydocs/*.txt

Chapter 10. Processing options 505

 You must use the snapshotroot option with a single file specification for an incremental, selective, or
archive operation. You cannot specify multiple file specifications or no file specifications. For example,
these commands are valid:

dsmc incremental /usr -snapshotroot=/snapshot/day1

dsmc incremental /usr/dir1/* -snapshotroot=/snapshot/day1

The following command is invalid because it contains two file specifications:

dsmc incremental /usr/dir1/* /home/dir2/*

-snapshotroot=/snapshot/day1

The following command is invalid because it contains no file specification:

dsmc incremental -snapshotroot=/snapshot/day1

Notes:
1. Ensure that the snapshotroot option references a snapshot of the correct volume. Ensure that
snapshotroot location refers to the root of the snapshot. If these rules are not followed, unintended
results, such as files that expire incorrectly, can result.
2. If you specify the filelist option and the snapshotroot option, all files that are specified in the
filelist option are assumed to be in the same file system. If there are entries in the filelist in a
different file system, they are skipped and an error is logged. If the filelist contains files that were
created in the file system after the snapshot was taken, these entries are also skipped, and an error is
logged.
3. You cannot use the snapshotroot option with the snapdiff option.
4. You can use the snapshotroot option with the preschedulecmd and postschedulecmd options,
or in an automated script that you run with the client scheduler.

Supported Clients
This option is valid for the following clients:
• UNIX and Linux clients except Mac OS X.

Syntax
SNAPSHOTRoot = snapshot_volume_name

Parameters
snapshot_volume_name
Specifies the root of the logical volume that is created by the independent software vendor snapshot
application.

Examples
Command line:
dsmc incremental /usr -SNAPSHOTRoot=/snapshot/day1

Srvoptsetencryptiondisabled
The srvoptsetencryptiondisabled option allows the client to ignore encryption options in a client
options set from the IBM Spectrum Protect server.
If the option is set to yes in the client options file, the client ignores the following options in a client
options set from the server:
• encryptkey
Note: The client ignores only the encryptkey generate option setting. Other possible encryptkey
option settings, for example, encryptkey prompt or encryptkey save are not ignored.

506 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • encryptiontype
• exclude.encrypt
• include.encrypt

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.sys) within a server stanza.

Syntax
no
SRVOPTSETENCryptiondisabled
yes

Parameters
yes
The backup-archive client ignores the values of the listed encryption options in a client options set
from the IBM Spectrum Protect server.
no
The backup-archive client processes the setting of the listed encryption options in a client options set
from the IBM Spectrum Protect server. This is the default.

Examples
Options file:
srvoptsetencryptiondisabled no
Command line:
Does not apply.

Srvprepostscheddisabled
The srvprepostscheddisabled option specifies whether to prevent the pre-schedule and post-
schedule commands specified by the IBM Spectrum Protect administrator from executing on the client
system, when performing scheduled operations.
The srvprepostscheddisabled option can be used in conjunction with the schedcmddisabled and
srvprepostscheddisabled options to disable the execution of any unwanted operating system
command by the IBM Spectrum Protect administrator on a client node.

Supported Clients
This option is valid for all backup-archive clients that use the IBM Spectrum Protect client scheduler. The
server cannot define this option.

Options File
Place this option in the dsm.sys file within a server stanza for the scheduler. You can set this option on the
Scheduler tab of the Preferences editor, in the Schedule Command section.

Chapter 10. Processing options 507

 Syntax
No
SRVPREPOSTSCHeddisabled
Yes

Parameters
No
Specifies that the client allows pre-schedule and post-schedule commands defined by the IBM
Spectrum Protect administrator to execute on the client system, when performing scheduled
operations. If a pre-schedule or a post-schedule command is defined by both the client and the IBM
Spectrum Protect administrator, the command defined by the administrator overrides the
corresponding command defined in the client option file. This is the default.
Yes
Specifies that the client prevents pre-schedule and post-schedule commands defined by the IBM
Spectrum Protect administrator to execute on the client system, when performing scheduled
operations. If a pre-schedule or a post-schedule command is defined by both the client and the IBM
Spectrum Protect administrator, the command defined by the administrator will not override the
corresponding command defined in the client option file. This option can be used in conjunction with
the schedcmddisabled and srvprepostscheddisabled options.

Examples
Options file:
srvprepostscheddisabled yes
Command line:
Does not apply.

Srvprepostsnapdisabled
The srvprepostsnapdisabled option specifies whether to prevent the pre-snapshot and post-
snapshot commands specified by the IBM Spectrum Protect administrator from executing on the client
system, when performing scheduled image snapshot backup operations.
The srvprepostsnapdisabled option can be used in conjunction with the schedcmddisabled and
srvprepostsnapdisabled options to disable the execution of any unwanted operating system
command by the IBM Spectrum Protect administrator on a client node.

Supported Clients
This option is valid for Linux clients that support the image snapshot backup command. The server cannot
define this option. The IBM Spectrum Protect API does not support this option.

Options File
Place this option in the dsm.sys file within a server stanza for the scheduler. You can set this option on the
Snapshot tab of the Preferences editor, in the Snapshot Options section.

Syntax
No
SRVPREPOSTSNApdisabled
Yes

508 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Parameters
No
Specifies that client allows pre-snapshot and post-snapshot commands defined by the IBM Spectrum
Protect administrator to execute on the client system, when performing scheduled image snapshot
backup operations. If a pre-snapshot or a post-snapshot command is defined by both the client and
the IBM Spectrum Protect administrator, the command defined by the administrator overrides the
corresponding command defined in the client option file. This is the default.
Yes
Specifies that the client does not allow pre-snapshot and post-snapshot commands defined by the
IBM Spectrum Protect administrator to execute on the client system, when performing scheduled
image snapshot backup operations. If a pre-snapshot or a post-snapshot command is defined by both
the client and the IBM Spectrum Protect administrator, the command defined by the administrator
will not override the corresponding command defined in the client option file. This option can be used
in conjunction with the schedcmddisabled and srvprepostsnapdisabled options.

Examples
Options file:
srvprepostsnapdisabled yes
Command line:
Does not apply.

Ssl
Use the ssl option to enable Secure Sockets Layer (SSL) to provide secure client and server
communications. When the backup-archive client communicates with an IBM Spectrum Protect server
V8.1.1 and earlier V8 levels, and V7.1.7 and earlier levels, it determines whether SSL is enabled. When
the backup-archive client communicates with an IBM Spectrum Protect server V8.1.2 and later levels,
and V7.1.8 and later V7 levels, SSL is always used and this option controls whether object data is
encrypted or not. For performance reasons, it might be desirable to not encrypt the object data.

Supported Clients
This option is valid for all supported clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can also set this
option on the Communication tab of the Preferences editor.

Syntax
No
SSL
Yes

Parameters for communicating with an IBM Spectrum Protect server V8.1.1 and earlier V8 levels,
and V7.1.7 and earlier levels.
No
Specifies that the backup-archive client does not use SSL to encrypt information. No is the default.
Yes
Specifies that the backup-archive client uses SSL to encrypt information.
To enable SSL, specify SSL Yes and change the value of the TCPPORT option. Changing the value of
the TCPPORT option is generally necessary because the IBM Spectrum Protect server is typically set
up to listen for SSL connections on a separate port.

Chapter 10. Processing options 509

 Parameters for communicating with an IBM Spectrum Protect server V8.1.2 and later levels, and
V7.1.8 and later V7 levels.
No
Specifies that the backup-archive client does not use SSL to encrypt object data when communicating
with the server. All other information is encrypted. No is the default.
Yes
Specifies that the backup-archive client uses SSL to encrypt all information, including object data,
when communicating with the server.
To use SSL for all data, specify SSL Yes.

Examples
Options file:
ssl yes
Command line:
Does not apply.
Related information
“Configuring IBM Spectrum Protect client/server communication with Secure Sockets Layer” on page 70.
“Sslrequired” on page 512
“Tcpport” on page 526

Sslacceptcertfromserv
Use the sslacceptcertfromserv option to control whether the backup-archive client or the API
application accept and trust the IBM Spectrum Protect server's Secure Sockets Layer (SSL) public
certificate the first time they connect. This option applies only the first time that the backup-archive client
or the API application connects to the IBM Spectrum Protect server. When the SSL public certificate is
accepted, future changes to the certificate are not automatically accepted, and must be manually
imported to the backup-archive client. You can use this option to connect only to an IBM Spectrum
Protect server V8.1.2 and later levels, and V7.1.8 and later V7 levels.

Supported Clients
This option is valid for all supported clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax
Yes
SSLACCEPTCERTFROMSERV
No

Parameters
Yes
Specifies that the backup-archive client does automatically accept the IBM Spectrum Protect server's
public certificate. Yes is the default.
No
Specifies that the backup-archive client does not automatically accept the IBM Spectrum Protect
server's public certificate.
To disable SSLACCEPTCERTFROMSERV, specify sslacceptcertfromserv no.

510 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Examples
Options file:
sslacceptcertfromserv no
Command line:
Does not apply.
Related information
“Ssl” on page 509
“Sslrequired” on page 512

Ssldisablelegacytls
Use the ssldisablelegacytls option to disallow the use of SSL protocols that are lower than TLS 1.2.

Supported Clients
This option is valid for all supported clients.

Options File
Place this option in the dsm.sys file. You can also set this option in the GUI by selecting the Require TLS
1.2 or above check box on the Communication tab of the Preferences editor. You cannot set this option
on the command line.

Syntax
No
SSLDISABLELEGACYtls
Yes

Parameters
No
Specifies that the backup-archive client does not require TLS 1.2 for SSL sessions. It allows
connection at TLS 1.1 and lower SSL protocols. When the backup-archive client communicates with
an IBM Spectrum Protect server V8.1.1 and earlier V8 levels, and V7.1.7 and earlier levels, No is the
default.
Yes
Specifies that the backup-archive client requires that all SSL sessions use TLS 1.2 (or higher) protocol.
When the backup-archive client communicates with an IBM Spectrum Protect server V8.1.2 and later
levels, and V7.1.8 and later V7 levels, Yes is the default.

Examples
Options file:
ssldisablelegacytls yes
Command line:
Does not apply.
Related reference
“Ssl” on page 509
Use the ssl option to enable Secure Sockets Layer (SSL) to provide secure client and server
communications. When the backup-archive client communicates with an IBM Spectrum Protect server
V8.1.1 and earlier V8 levels, and V7.1.7 and earlier levels, it determines whether SSL is enabled. When
the backup-archive client communicates with an IBM Spectrum Protect server V8.1.2 and later levels,
and V7.1.8 and later V7 levels, SSL is always used and this option controls whether object data is
encrypted or not. For performance reasons, it might be desirable to not encrypt the object data.

Chapter 10. Processing options 511

 “Sslrequired” on page 512
The sslrequired option specifies the conditions when SSL is or is not required when the client logs on
to the IBM Spectrum Protect server or storage agents. To actually enable SSL so client-to-server and
client-to-storage-agent communications are secure, you must set the client ssl option to yes. When
communicating with the IBM Spectrum Protect server V8.1.2 and later levels, and V7.1.8 and later V7
levels, this option no longer applies since SSL is always used.
“Tcpport” on page 526
The tcpport option specifies a TCP/IP port address for the IBM Spectrum Protect server. You can obtain
this address from your administrator.

Sslfipsmode
The sslfipsmode option specifies whether the client uses SSL Federal Information Processing
Standards (FIPS) mode for Secure Sockets Layer (SSL) communications with the server. The default is no.

Supported clients
This option is supported on all clients.

Options File
Set this option in the client options file. You cannot specify it as a command-line parameter and you
cannot set this option in a client options set.

Syntax
No
SSLFIPSMODE =
Yes

Parameters
No
Specifies that the client does not use SSL FIPS mode for secure communications with the server. SSL
in FIPS mode is supported only by version 6.3 and newer versions of the server. Set this client option
to no if the client uses SSL to connect to a server that is not at V6.3, or newer.
Yes
Specifies that the client uses SSL FIPS mode for secure communications with the server. Setting this
option to yes restricts SSL session negotiation to use only FIPS-approved cipher suites. SSL FIPS
mode is only supported by the V6.3 (or newer) server.

Example
To enable SSL FIPS mode on the client:

SSLFIPSMODE yes

Sslrequired
The sslrequired option specifies the conditions when SSL is or is not required when the client logs on
to the IBM Spectrum Protect server or storage agents. To actually enable SSL so client-to-server and
client-to-storage-agent communications are secure, you must set the client ssl option to yes. When
communicating with the IBM Spectrum Protect server V8.1.2 and later levels, and V7.1.8 and later V7
levels, this option no longer applies since SSL is always used.

Supported Clients
This option is supported on all clients.

512 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Options File
Place this option in the client options file or in the GUI, on the Communications tab. You cannot set this
option on the command line.

Syntax
Default
SSLREQuired
Yes

No

SERVERonly

Parameters
Default
This setting indicates that SSL is required to secure communications between the client and server,
and client and storage agents, if AUTHENTICATION=LDAP is set on the server. To secure
communications by using SSL, you must also set ssl=yes on the client.
If AUTHENTICATION=LOCAL is set on the server, this setting indicates that SSL is not required. Even
though SSL is not required when AUTHENTICATION=LOCAL and sslrequired=default, you can
still use SSL by setting the client ssl option to yes.
Yes
Indicates that SSL is always required to secure communications between the client and server, and
between the client and storage agents. sslrequired=yes has no dependency on the server
AUTHENTICATION option. If you set sslrequired=yes on the client, you must also set ssl=yes on
the client.
No
Indicates that you do not require SSL to be used to secure communications between the client and
server or between the client and storage agents. Choose this option only if you use a virtual private
network or other method to secure your session communications. You can still enable SSL by setting
ssl=yes on the client; but sslrequired=no specifies that SSL is not a prerequisite.
SERVERonly
Indicates that SSL is required for client-to-server communications and not for server-to-storage agent
communications. To use SSL for client to server communications, set sslrequired=serveronly
and ssl=yes. The server setting for the AUTHENTICATION option can be either LOCAL or LDAP.
For client to storage agent communications, use the client lanfreessl option to enable SSL.
The following table describes the situations under which authentication succeeds or fails, depending on
the settings of the SSLREQUIRED option on the server, and client, and the setting of the ssl option on the
client. The table results assume that valid credentials are supplied.

Table 77. Effects of server and client SSL settings on success or failure of login attempts

SSLREQUIRED sslrequired ssl option Authentication success or failure

option option
(client setting)
(server setting) (client setting)

Yes Yes Yes Authentication succeeds

Yes Yes No Authentication fails; the client rejects

the session

Yes No Yes Authentication succeeds

Chapter 10. Processing options 513

 Table 77. Effects of server and client SSL settings on success or failure of login attempts (continued)

SSLREQUIRED sslrequired ssl option Authentication success or failure

option option
(client setting)
(server setting) (client setting)

Yes No No Authentication fails; the server rejects

the session

No Yes Yes Authentication succeeds

No Yes No Authentication fails; the client rejects

the session

No No Yes Authentication succeeds

No No No Authentication succeeds

The following text describes how setting SSLREQUIRED=DEFAULT and SSLREQUIRED=SERVERONLY on

the server affects the ssl option on the client.
If the server sets SSLREQUIRED=DEFAULT and AUTHENTICATION=LDAP, the client must set ssl=yes or
authentication fails.
If the server sets SSLREQUIRED=DEFAULT and AUTHENTICATION=LOCAL, the client can set ssl=yes or
ssl=no.
If the server sets SSLREQUIRED=SERVERONLY, you must set ssl=yes on the client. The client
lanfreessl option can be set to yes, to secure communications with a storage agent, or to no if secure
communications with storage agents is not needed.

Examples
Options file:

sslrequired yes
sslrequired no
sslrequired default
sslrequired serveronly

Command line:
Not applicable; you cannot set this option on the command line.

Stagingdirectory
The stagingdirectory option defines the location where the client stores any data that it generates to
perform its operations. The data is deleted when processing is complete.
Important: Starting with Version 8.1.2, the snapdiffchangelogdir option is used to specify the
location to store change logs for snapshot differential backup operations. The stagingdirectory
option is no longer used for this purpose. For more information, see “Snapdiffchangelogdir” on page 499.

Supported Clients
This option is valid for Linux clients. The server can also define this option.

Options File
Place this option in the client options file (dsm.opt). When stagingdirectory is specified on the
command line, it overrides the values that are specified in the options file.

514 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Syntax
STAGINGDIRectory path

Parameters
path
Specifies the directory path where the client writes staging data. If you do not specify a staging
directory, the client stores temporary data in the temporary file system (typically /tmp).

Examples
Options file:
stagingdirectory /usr/tsmdata
stagingdirectory /private/tmp
Command line:
-stagingdir="/tmp/tsmtempdata"
Related reference
“Diffsnapshot” on page 343
The diffsnapshot option controls whether the backup-archive client creates the differential snapshot
when it runs a snapshot difference incremental backup.
“Snapdiff” on page 494
Using the snapdiff (snapshot difference) option with the incremental command streamlines the
incremental backup process. The command runs an incremental backup of the files that were reported as
changed by NetApp instead of scanning all of the volume for changed files.

Subdir
The subdir option specifies whether you want to include subdirectories of named directories for
processing.
You can use the subdir option with the following commands:
• archive
• delete archive
• delete backup
• incremental
• query archive
• query backup
• restore
• restore backupset
• restore group
• retrieve
• selective
If you set the subdir option to yes when backing up a specific path and file, the backup-archive client
recursively searches all of the subdirectories under that path, and looks for any instances of the specified
file that exist under any of those subdirectories. For example, assume that a file called myfile.txt
exists on a client in the following directories:

//myfile.txt
/dir1/myfile.txt
/dir1/dir_a/myfile.txt
/dir1/dir_b/myfile.txt

Chapter 10. Processing options 515

 Performing a selective backup of that file, as follows, backs up all four instances of myfile.txt:

dsmc sel /myfile.txt -subdir=yes

Similarly, the following command displays all instances of myfile.txt if you specify subdir=yes in the
client options file or in a client options set.

dsmc restore /myfile.txt -pick

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 client user-options file (dsm.opt).

Syntax
No
SUbdir
Yes

Parameters
No
Subdirectories are not processed. This is the default.
Yes
Subdirectories are processed. Because the client program searches all subdirectories of a directory
that is being processed, processing can take longer to complete. Specify Yes only when necessary.
If you use the preservepath option in addition to subdir=yes, it can affect which subdirectories
are processed.
If a subdirectory is a mounted file system, it is not processed even if you specify subdir=yes.
Note:
1. When you run the client in interactive mode, and if you use the -subdir=yes option, the setting persists
for all commands entered in interactive mode, until you end interactive mode, by typing Quit.
2. If subdir=yes is in effect when you restore multiple files, place a directory delimeter character at the
end of the destination file specification. If the delimeter is omitted, the client displays a message
indicating that the destination file specification is not valid.
3. It is a best practice to include only the default value for subdir (No) in a client options file or a client
options set.

Examples
Options file:
subdir no
Command line:
To restore the structure:

/Users/mike/dir1
/Users/mike/dir1/file1
/Users/mike/dir1/dir2
/Users/mike/dir1/dir2/file1

enter any of the following commands:

516 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 dsmc rest "/Users/van/dir1/*" /Users/mike/ -su=yes
dsmc rest "/Users/van/dir1/file*" /Users/mike/ -su=yes
dsmc rest "/Users/van/dir1/file1*" /Users/mike/ -su=yes

To restore the structure:

/path2/dir1
/path2/dir1/file1
/path2/dir1/dir2
/path2/dir1/dir2/file1

enter any of the following commands:

dsmc rest "/path/dir1/*" /path2/ -su=yes

dsmc rest "/path/dir1/file*" /path2/ -su=yes
dsmc rest "/path/dir1/file1*" /path2/ -su=yes

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.
Related information
“Preservepath” on page 458

Tagschedule
Use the -tagschedule option to back up or rebalance VMs.
W you can back up or rebalance VMs that are assigned to, or are associated with, a schedule and data
mover with specified vSphere Web Client GUI and VMware tags. You can use the -tagschedule option
with the backup VM command in two scenarios:
• To run an ad hoc backup operation. For example, you can rerun or preview a scheduled backup
operation.
• To rebalance the data movers on a tagged schedule. You can use the -VMREBALANCESCHEDULEONLY
option to rebalance the data movers on an ad hoc basis and the -VMREBALANCESCHEDULEPERIOD
option to rebalance the data movers on a regular basis.
The -tagschedule option works only with tag-based schedule names.

Supported Clients
This option is valid on Windows and Linux data movers.

Options File
Use the -tagschedule option on the command line. You can also use the options file to schedule
periodic rebalancing operations.
Related reference
UPDATE SCHEDULE (Update a client schedule)

Using the tagschedule option for ad hoc backup operations

If a scheduled backup operation fails, you can use the -tagschedule option to run a backup on all VMs
that are associated with that schedule.
When you run a backup operation with the -tagschedule option, the backup vm command generates a
list of VMs to back up. The list includes VMs for which:
• The VM Schedule (IBM Spectrum Protect) tag value matches what was passed in via the -
tagschedule option.
• The VM Data Mover (IBM Spectrum Protect) tag value matches the data mover node name.

Chapter 10. Processing options 517

 If both match, then that VM is selected for backup. You can also see which VMs are selected by using the
-preview option.
If, for example, SCHEDULE1 ran overnight but failed, you can issue a dsmc backup vm -
tagschedule=SCHEDULE1 command for a given data mover. That data mover then uses the string
SCHEDULE1 to filter the VM inventory and select the VMs that have a Schedule (IBM Spectrum Protect)
tag value of SCHEDULE1.
The selected VMs are also filtered to include only VMs with a Data Mover (IBM Spectrum Protect) tag
value matching the node name of the data mover in use. The backup also includes any VMs that do not
have a data mover tag assigned if the data mover being used is designated as the default data mover. A
data mover is designated as default either with the -vmtagdefaultdatamover option specified in the
opt file or passed on the command line.
Run the backup vm command on all data movers associated with a schedule if you want to include all
VMs associated with that schedule. Ensure that at least one of these data movers is run as the default
data mover. It is not always necessary to use the default data mover option. A schedule created by the VE
GUI always sets a default. But if you run the backup vm command ad hoc, the default value will not be
set unless it is explicitly specified in the data mover -optfile. By default, the configuration wizard sets
the first added data mover as the default TAGschedule data mover.
Tip: The query results in the Schedule table in the Monitor Schedule panel will not reflect that a tagged
schedule has run. However, the individual VM status will indicate that a backup operation occurred.
The entire SCHEDULE1 schedule is not rerun; only the machines with the Data Mover (IBM Spectrum
Protect) tag set to the schedule name passed in are backed up. You must run a separate command on the
other data movers to back up the VMs that are assigned to those data movers.

Syntax
TAGSCHEDule= schedule_name -ASNODENAME=
-preview

datacenter_name -OPTFILE= datamover_option_file_name

Parameters
-preview
Specify this parameter to preview the listing that will be obtained when the command is run with the
specified filter.
-schedule_name
Specify the schedule name to run the listing that will be obtained when the schedule is run with the
specified filter.
-ASNODENAME
Use this parameter in the options file to specify the name of the data center.
-OPTFILE
Use this parameter to specify the name of the options file.

Examples of backup scenarios

Command line:
dsmc backup vm -OPTFILE=dsm.MM1_DATACENTER1_DM1.opt -ASNODE=MM1_DATACENTER1
-tagschedule=SCHEDULE1
Backs up all VMs with schedule tag SCHEDULE1.
Command line:
dsmc backup vm -OPTFILE=dsm.MM1_DATACENTER1_DM1.opt -ASNODE=MM1_DATACENTER1
-tagschedule='DAILY_5AM' -preview

518 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Lists the VMs that qualify for backup operations using the VMs that contain DAILY_5AM as their value
for the Schedule (IBM Spectrum Protect) tag, and targeting the node MM1_DATACENTER1 for data
mover MM1_DATACENTER1_DM1.
Related reference
UPDATE SCHEDULE (Update a client schedule)

Using the tagschedule option to rebalance scheduled operations

To optimize a tagged schedule operation, you can balance tagged schedules according to the size (total
storage occupied) of the VMs in the selected schedule. By rebalancing tagged schedules, you reset which
data mover processes each VM that is backed up by the schedule.
The vSphere Web client plug-in assigns data movers to VMs as they are added to a schedule. To
rebalance tagged schedules by using the GUI, you must edit the schedule and ensure that the check box
for rebalancing the schedule is selected upon saving. VMs are added to schedules by other means. For
example, new VMs are also assigned data movers after the first backup by the default data mover. You
may want to periodically issue a full rebalance. The advantage of rebalancing tag schedules is that
backups are distributed evenly across storage resources. This can be done with the vSphere Web client
plug-in or by using the data mover command-line interface.
Re-balance operations are rarely necessary. VMs are balanced when they are added to a schedule and
new VMs are also assigned balanced data movers. A full rebalance operation might be required when a
significant number of VMs are deleted or moved. Use the VMREBALANCESCHEDULEONLY option when you
need to rebalance all data movers and VMs associated with a schedule.
To automate rebalance operations, a VMREBALANCESCHEDULEPERIOD option can be manually added as
a parameter on the schedule option string, or in the options file. Although you can place the option in the
default data mover's option file, it is preferable to add the option to the OPTion string of the schedule. In
this way, you can avoid ambiguity if one data mover services multiple schedules.
Specify the VMREBALANCESCHEDULEPERIOD option only if the schedule has multiple data movers
assigned. The option will be used only by the default data mover. A default data mover is assigned when
adding data movers to a schedule. The schedule is rebalanced after the number of days specified by the
VMREBALANCESCHEDULEPERIOD option and only after the schedule has completed its current backup
operation.

Syntax
TAGSCHEDule= schedule_name -VMREBALANCESCHEDULEONLY -ASNODENAME=

datacenter_name -OPTFILE= datamover_option_file_name

Parameters
-VMREBALANCESCHEDULEONLY
Use this parameter to balance data movers in tag schedules according to the size of the VM. Data
movers are assigned to the VMs by size, with the largest VM being assigned to the first data mover on
the list, the next largest VM assigned to the next data mover, and so on. Existing data mover
assignments are overwritten by reassigning the data mover tag on each VM.
-VMREBALANCESCHEDULEPERIOD
Use this parameter in the options file to specify the time (in days) between rebalancing operations by
the client. You can specify a value in the range 0 to 365. If you specify 0, which is the default,
rebalancing never occurs. If you specify 365, rebalancing occurs about once a year. The scheduled
rebalance operation is run on the default data mover.
-ASNODENAME
Use this parameter to specify the name of the data center.
-OPTFILE
Use this parameter to specify the name of the options file.

Chapter 10. Processing options 519

 Examples
Command line:
dsmc backup vm -OPTFILE=dsm.MM1_DATACENTER1_DM1.opt -tagschedule=VMWARE01 -
vmrebalancescheduleonly -asnodename=MY_DATACENTER_NODE
Rebalances the schedule named VMWARE01, which targets the node MY_DATACENTER_NODE. After
the rebalance operation, VMs that were asymmetrically assigned across data movers are now
symmetrically assigned. VMs that were unassigned to data movers are now assigned.
The following output shows before and after scenarios for a rebalance operation for schedule named
vmware_sxf1_cldev:

dsmc backup vm -tagschedule=vmware_sxf1_cldev -vmrebalancescheduleonly -

asnode=sxf1_cldev
Node Name: DEFENDER1
Accessing as node: SXF1_CLDEV
ANS4313I Rebalance Schedule VMWARE_SXF1_CLDEV Type: Full

Before Rebalance
----------------
Data Mover Name : DEFENDER1
Total Bytes Protected : 432.16 GB
Virtual Machines Protected : 10

Data Mover Name : SXF1_CLDEV_DM

Total Bytes Protected : 116.04 GB
Virtual Machines Protected : 3

Virtual Machines not assigned : 1

After Rebalance
----------------
Data Mover Name : DEFENDER1
Total Bytes Protected : 332.08 GB
Virtual Machines Protected : 7

Data Mover Name : SXF1_CLDEV_DM

Total Bytes Protected : 316.12 GB
Virtual Machines Protected : 7

Virtual Machines not assigned : 0

The rebalance output information is recorded in the schedule log and logged to the server activity log.

UPDate SCHedule domain_name schedule_name OPTions="-vmfulltype=vstor

-vmbackuptype=fullvm -asnodename=sxf1_cldev -mode=IFIncremental
-domain.vmfull=SCHEDULE-TAG -vmtagdefaultdatamover=DEFENDER1
-vmrebalancescheduleperiod=1"

Specifies that the default data mover rebalances the schedule every day.
Related reference
UPDATE SCHEDULE (Update a client schedule)

Tapeprompt
The tapeprompt option specifies whether you want the backup-archive 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.
In the backup-archive client GUI, the Media Mount dialog can display the Information Not
Available value in the Device and Volume Label fields if you perform a standard (also known as classic)
restore or retrieve operation. This value means that this information is only available for no-query restore
or retrieve operations; not a standard restore or retrieve operation. The Device field displays the name of
the device on which to mount the media needed to process an object. The Volume Label field displays
the name of the volume needed to process an object.

520 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Tape prompting does not occur during a scheduled operation regardless of the setting for the
tapeprompt option.
The tapeprompt option can be used with the following commands:
• archive
• delete archive
• delete backup
• incremental
• restore
• retrieve
• selective
Note: The server can also define this option.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client user-options file (dsm.opt). You can set this option on the General tab,
Prompt before mounting tapes check box of the Preferences editor.

Syntax
No
TAPEPrompt
Yes

Parameters
No
You are not prompted for your choice. The server waits for the appropriate tape to mount. This is the
default.
Note: For API applications, this permits backup directly to tape.
Yes
You are prompted when a tape is required to back up, archive, restore, or retrieve data. At the prompt,
you can wait for the appropriate tape to be mounted, always wait for a tape to be mounted, skip a
particular object, skip all objects on a single tape, skip all objects on all tapes, or cancel the entire
operation.

Examples
Options file:
tapeprompt yes
Command line:
-tapep=yes
This option is valid only on the initial command line. It is not valid in interactive mode.

Chapter 10. Processing options 521

Tcpadminport
Use the tcpadminport option to specify a separate TCP/IP port number on which the server waits for
requests for administrative client sessions, allowing secure administrative sessions within a private
network.
The client tcpadminport setting depends on how the IBM Spectrum Protect server tcpadminport and
adminonclientport options are configured. The server has a tcpadminport setting that indicates on
which port the server listens for administrative sessions, and the adminonclientport setting, which
can be either yes or no.
If tcpadminport is not set on the server, then administrative sessions are allowed on the same port as
client sessions.
If tcpadminport is set on the server, then administrative sessions are allowed on the port specified by
that setting. In this case, if adminonclientport yes is in effect, then administrative sessions can
connect on either the regular client port or the port specified by tcpadminport. If
adminonclientport no is in effect, then administrative sessions can connect only on the port specified
by tcpadminport.

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 dsm.sys file within a server stanza. You can set this option on the Communication
tab, in the Admin Port field in the Preferences editor.

Syntax
TCPADMINPort

admin_port_address

Parameters
admin_port_address
Specifies the port number of the server. The default value is the value of the tcpport option.

Examples
Options file:
tcpadminport 1502

Tcpbuffsize
The tcpbuffsize option specifies the size of the internal TCP/IP communication buffer used to transfer
data between the client node and server. Although it uses more memory, a larger buffer can improve
communication performance.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the Communication tab, in the Buffer Size field in the Preferences editor.

522 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Syntax
TCPBuffsize size

Parameters
size
Specifies the size, in kilobytes, that you want to use for the internal TCP/IP communication buffer. The
range of values is 1 through 512; the default is 32.
Depending on the operating system communication settings, your system might not accept all values
in the range of 1 through 512.

Examples
Options file:
tcpb 32
Command line:

-tcpbuffsize=32

This option is valid only on the initial command line. It is not valid in interactive mode.

Tcpcadaddress
The tcpcadaddress option specifies a TCP/IP address for dsmcad. Normally, this option is not needed.
Use this option only if your client node has more than one TCP/IP address, or if TCP/IP is not the default
communication method.

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 dsm.sys file within a server stanza.

Syntax
TCPCADAddress cad_address

Parameters
cad_address
Specifies a TCP/IP Internet domain name or a numeric IP address. If you specify an IPv6 addresses,
you must specify the commmethod V6Tcpip option.

Examples
Options file:
tcpcada dsmclnt.example.com
Command line:

-tcpcadaddress=192.0.2.0

-tcpcadaddress=mycompany.example.com

-tcpcadaddress=2001:0DB8:0:0:0:0:0:0

Chapter 10. Processing options 523

 This option is valid only on the initial command line of the dsmcad program. It is not valid with other dsm
modules.
Related information
See “Commmethod” on page 323 to determine if your client node has more than one TCP/IP address, or if
TCP/IP is not the default communication method.

Tcpclientaddress
The tcpclientaddress option 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.
Use this option only if you use the prompted parameter with the schedmode option.
If sessioninitiation is set to serveronly, the value for the tcpclientaddress client option
should be the same as the value for the HLAddress server setting.

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 dsm.sys file within a server stanza. You can set this option on the Scheduler tab,
Your TCP/IP address field of the Preferences editor.

Syntax
TCPCLIENTAddress client_address

Parameters
client_address
Specifies the TCP/IP address you want the server to use to contact your client node. Specify a TCP/IP
Internet domain name or a numeric IP address. The numeric IP address can be either a TCP/IPv4 or
TCP/IPv6 address. You can only use IPv6 addresses if you specified the commmethod V6Tcpip option.

Examples
Options file:

tcpclienta dsmclnt.example.com
or
tcplienta 192.0.2.21

This option is valid only on the initial command line. It is not valid in interactive mode.

Tcpclientport
The tcpclientport option specifies a TCP/IP port number for the server to contact the client when the
server begins the server prompted scheduled operation.
Use this option only if you specify the prompted parameter with the schedmode option.
If sessioninitiation is set to serveronly, the value for the tcpclientport client option should
be the same as the value for the LLAddress server option.

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

524 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Options File
Place this option in the dsm.sys file within a server stanza. You can set this option on the Scheduler tab,
in the Your TCP/IP port field in the Preferences editor.

Syntax
TCPCLIENTPort client_port_address

Parameters
client_port_address
Specifies the TCP/IP port address you want the server to use to contact your client node. The range of
values is 1 through 32767; the default is 1501.

Examples
Options file:
tcpclientp 1502
Command line:

-tcpclientport=1492

This option is valid only on the initial command line. It is not valid in interactive mode.

Tcpnodelay
The tcpnodelay option specifies whether the client disables the delay of sending successive small
packets on the network, per transaction.
Change the value from the default of yes only under one of the following conditions:
• You are directed to change the option by IBM technical support.
• You fully understand the effects of the TCP Nagle algorithm on network transmissions. Setting the
option to no enables the Nagle algorithm, which delays sending small successive packets.

Supported Clients
This option is valid for all UNIX and Linux clientst.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the Communication tab in the Preferences editor. Select Send transaction to the server
immediately.

Syntax
Yes
TCPNodelay
No

Parameters
No
Specifies that the server does not allow successive small packets to be sent immediately over the
network. Setting this option to no can degrade performance.
Yes
Specifies that the server or client allows successive small packets to be sent immediately over the
network. The default is yes.

Chapter 10. Processing options 525

 Examples
Options file:
tcpnodelay yes
Command line:
Does not apply.

Tcpport
The tcpport option specifies a TCP/IP port address for the IBM Spectrum Protect server. You can obtain
this address from your administrator.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the Communication tab, in the Server Port field in the Preferences editor.

Syntax
TCPPort port_address

Parameters
port_address
Specifies the TCP/IP port address that is used to communicate with a server. The range of values is 1
through 32767; the default is 1500.

Examples
Options file:
tcpp 1501
Command line:
Does not apply.

Tcpserveraddress
The tcpserveraddress option specifies the TCP/IP address for the IBM Spectrum Protect server. You
can obtain this server address from your administrator.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the Communication tab, in the Server Address field in the Preferences editor.
If this option is not specified, the client attempts to contact a server running on the same computer as the
backup-archive client.

Syntax
TCPServeraddress server_address

526 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Parameters
server_address
Specifies a 1 to 64 character TCP/IP address for a server. Specify a TCP/IP domain name or a numeric
IP address. The numeric IP address can be either a TCP/IP v4 or TCP/IP v6 address. You can only use
IPv6 addresses if you specified the commmethod V6Tcpip option.

Examples
Options file:
tcps dsmchost.example.com
Command line:
Does not apply.

Tcpwindowsize
Use the tcpwindowsize option to specify, in kilobytes, the size you want to use for the TCP/IP sliding
window for your client node.
The sending host cannot send more data until it receives an acknowledgment and a TCP receive window
update. Each TCP packet contains the advertised TCP receive window on the connection. A larger window
allows the sender to continue sending data and can improve communication performance.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the Communication tab, Window Size field of the Preferences editor.

Syntax
TCPWindowsize window_size

Parameters
window_size
Specifies the size, in kilobytes, to use for your client node TCP/IP sliding window. The range of values
is 0 through 2048. A value of 0 allows the client to use the operating system default TCP window size.
Values from 1 to 2048 indicate that the window size is in the range of 1KB to 2MB. If you specify a
value less than 1, the TCP window size defaults to 1. If you specify a value greater than 2048, the TCP
window size defaults to 2048.
For backup-archive clients, the default value for this parameter is 63 KB.
For IBM Spectrum Protect for Virtual Environments: Data Protection for VMware, the default value for
this parameter is 512 KB.
Notes:
• The TCP window acts as a buffer on the network. It is not related to the tcpbuffsize option, or to
the send and receive buffers allocated in client or server memory.
• A window size larger than the buffer space on the network adapter might degrade throughput due to
resending packets that were lost on the adapter.
• Depending on the operating system communication settings, your system might not accept all
values in the range of values.
• The tcpwindowsize option overrides the operating system's default TCP/IP session send and
receive window sizes.

Chapter 10. Processing options 527

 Examples
Options file:
tcpwindowsize 63
Command line:
-tcpw=63
This option is valid only on the initial command line. It is not valid in interactive mode.

Timeformat
The timeformat option specifies the format in which you want to display and enter system time.
By default, the backup-archive and administrative clients obtain format information from the locale
definition in effect at the time the client is called. Consult the documentation on your local system for
details about setting up your locale definition.
Note: The timeformat option does not affect the web client. The web client uses the time format for the
locale that the browser is running in. If the browser is not running in a locale that the client supports, the
web client uses the time format for US English.
You can use the timeformat option with the following commands:
• delete archive
• delete backup
• expire
• query archive
• query backup
• query filespace
• query image
• query nas
• restore
• restore image
• restore nas
• retrieve
• set event
When you include the timeformat option with a command, it must precede the fromtime, pittime,
and totime options.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client user-options file (dsm.opt). You can set this option on the Regional Settings
tab, Time Format field of the Preferences editor.

Syntax
TIMEformat format_number

528 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Parameters
format_number
Displays time in one of the formats listed here. Select the format number that corresponds to the
format you want to use. When you include the timeformat option in a command, it must precede the
fromtime, pittime, and totime options.
0
Use the locale-defined time format (does not apply to Mac OS X). This value is the default if the
locale-specified format consists of digits, separator characters, and, if applicable, the AM or PM
string.
1
23:00:00
This is the default if the locale-specified format does not consist of digits, separator characters,
and, if applicable, the AM or PM string.
2
23,00,00
3
23.00.00
4
12:00:00 A/P
5
A/P 12:00:00

Examples
Options file:
timeformat 4
Command line:
-time=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 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.

Configuring date and time formats in the system locale configuration file
You can specify date and time formats by configuring them in your system’s locale file. If you specify time
and date formats in the locale file, they must be defined by using a subset of number-producing format
specifiers that are supported by the C language strftime() function. You can use the following
specifiers to set date and time formats in configuration settings for your locale.
Date specifiers
• %Y - the year, in four digits. For example, 2011.
• %y - the year, last two digits only. For example, 11 not 2011.

Chapter 10. Processing options 529

 • %m - the month, as a decimal number (1-12).
• %d - the day of the month (1-31).
In the date specifiers, you can specify only one year specifier. Do not specify both %Y and %y. The E
modifier (a capital E) can precede the date specifiers to produce the locale's alternative form for the
year, month, or day. If no alternative form exists, the E modifier is ignored. Separate the specifiers
with a single 7-bit ASCII character. Commonly used separators include colons (:), commas (,), periods
(.), hyphens (-), or forward slash (/) characters. Do not use multibyte characters as separators.
Time specifiers
• %H - the hour, in 24-hour form (00-23).
• %I - the hour, in 12-hour form (00-12).
• %M - minutes after the hour (00-59).
• %S - seconds after the minute (00-59)
• %p - adds the AM (before noon) or PM (after noon) indicator.
In the time specifiers, you can specify only one hour specifier. Do not specify both %I and %H.
The O modifier (a capital O) can precede the time specifiers to produce the locale's alternative form
for the hour, minutes, or seconds. The O modifier cannot precede the %p specifier. Separate the
specifiers with a single 7-bit ASCII character. Commonly used separators include colons (:), commas
(,), or periods (.). Do not use multibyte characters as separators. Do not specify a separator between
the %p specifier and the separator that precedes or follows it.
Time format examples, configured in the locale settings
To set a particular time format, edit the configuration file for your locale and modify the t_fmt line to
support your needs. Whatever time format you select applies both to output and to input. After the
locale configuration file has been edited, the localedef command must be run to create the final
locale file.

Table 78. Sample time format settings in the locale configuration (t_fmt line)
Example Result
"%H:%M:%S" Displays time in the form hh:mm:ss with hh ranging
from 0 through 23.
"%H,%M,%S" Displays time in the form hh,mm,ss with hh ranging from
0 through 23.
"%I,%M,13p" Displays time in the form hh,mm,ssA/P with hh ranging
from 1 through 12 and A/P is the local abbreviation for
ante-meridian (AM in English) or post-meridian (PM in
English).

Date format examples, configured in the locale settings

To set a particular date format, edit the configuration file and modify the d_fmt line as needed to
support your needs. Whatever date format you select applies both to output and to input.

Table 79. Sample date format settings in the locale configuration (d_fmt line)
Example Result
"%m/%d/%y" Displays the date in the form MM/DD/YY.
"%d.%m.%Y" Displays the date in the form DD.MM.YYYY.

530 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Toc
Use the toc option with the backup nas command or the include.fs.nas option to specify whether
the backup-archive client saves table of contents (TOC) information for each file system backup.
You should consider the following when deciding whether you want to save TOC information:
• If you save TOC information, you can use the QUERY TOC server command to determine the contents of
a file system backup in conjunction with the RESTORE NODE server command to restore individual files
or directory trees.
• You can also use the Windows backup-archive client GUI 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.

Supported Clients
This option is only valid for AIX and Solaris clients. The IBM Spectrum Protect API does not support this
option.

Options File
Place the include.fs.nas statement containing the toc value in the dsm.sys file within a server
stanza.

Syntax
Preferred
TOC
Yes

No

Parameters
Yes
Specifies that the client saves TOC information during a NAS file system image backup. However, the
backup fails if an error occurs during creation of the TOC.
No
Specifies that the client does not save TOC information during a NAS file system image backup.
Preferred
Specifies that the client saves TOC information during a NAS file system image backup. The backup
does not fail if an error occurs during creation of the TOC. This is the default.
Note: If the mode option is set to differential and you set the toc option to preferred or yes, but
the last full image does not have a TOC, the client performs a full image backup and creates a TOC.

Examples
Options file:
include.fs.nas netappsj/vol/vol0 homemgmtclass toc=yes
Command line:
backup nas -nasnodename=netappsj /vol/vol0 -toc=yes

Chapter 10. Processing options 531

Todate
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
Use the todate and totime options with the fromtime and fromdate options to request a list of
backed up or archived files within a period of time. For example, you might request a list of files that were
backed up between 6:00 AM on July 1, 2002 and 11:59 PM on July 30, 2002.
Use the todate option with the following commands:
• delete backup
• query archive
• query backup
• restore
• restore group
• retrieve

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
TODate = date

Parameters
date
Specifies an ending date. Enter the date in the format you selected with the dateformat option.
When you include dateformat with a command, it must precede the fromdate, pitdate, and
todate options.

Examples
Command line:
dsmc restore "/Users/agordon/Documents/*" -todate=12/11/2003
Command line:
dsmc restore "/home/user1/*" -todate=12/11/2003

Totime
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. The backup-archive client
ignores this option if you do not specify the todate option.
Use the totime and todate options with the fromtime and fromdate options to request a list of files
that were backed up within a period of time. For example, you might request a list of files that were
backed up between 6:00 AM on July 1, 2003 and 11:59 PM on July 30, 2003.
Use the totime option with the following commands:
• delete backup
• query archive
• query backup
• restore
• restore group
• retrieve

532 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
TOTime = time

Parameters
time
Specifies an ending time. If you do not specify a time, the time defaults to 23:59:59. Specify the time
in the format you selected with the timeformat option.
When you include the timeformat option in a command, it must precede the fromtime, pittime,
and totime options.

Examples
Command line:
dsmc restore "/Users/van/Documents/myfiles/*" -todate=09/17/2003 -
totime=23:00:00
Command line:
dsmc restore "/home/user1/*" -todate=09/17/2003 -totime=23:00:00

Txnbytelimit
The txnbytelimit option specifies the number of kilobytes the client program buffers before it sends a
transaction to the server.
A transaction is the unit of work exchanged between the client and server. A transaction can contain more
than one file or directory, called a transaction group.
You can control the amount of data sent between the client and server, before the server commits the
data and changes to the server database, using the txnbytelimit option. Controlling the amount of
data sent changes the speed of the client to perform the transactions. The amount of data sent applies
when files are batched together during backup or when receiving files from the server during a restore
procedure.
After the txngroupmax number is reached, the client sends the files to the server, even if the transaction
byte limit is not reached.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza. You can set this option
on the General tab, in the Transaction Buffer Size field in the Preferences editor.

Syntax
TXNBytelimit number

Parameters
number
Specifies the number of kilobytes the client program sends to the server before committing the
transaction. The range of values is 300 through 34359738368 (32 GB). The default is 25600 KB. The
number can be specified as an integer or as an integer with one of the following unit qualifiers:

Chapter 10. Processing options 533

 K or k (kilobytes)
M or m (megabytes)
G or g (gigabytes)
If no unit qualifier is specified, the integer is in kilobytes.
Restriction: The txnbytelimit option does not support decimal numbers, and only one-unit letters
are allowed. For example: K, M, or G.

Examples
Options file:
txnb 25600
txnb 2097152
txnb 2097152k
txnb 2048m
txnb 2g
txnb 32G
Command line:
-txnb=25600
-txnb=16G
This option is valid only on the initial command line. It is not valid in interactive mode.

Type
Use the type option with the query node command to specify the type of node to query. Use this option
with the set event command to activate, hold, or release.
This option is also valid for the set password command with the TSM type on AIX clients.

Supported Clients
This option is only valid for AIX and Solaris clients. The IBM Spectrum Protect API does not support this
option.

Syntax
any
TYpe =
nas
server

client

Parameters
nas
Specifies all NAS nodes registered at the server.
server
Specifies client nodes that are other IBM Spectrum Protect servers.
client
Specifies client nodes that are backup-archive clients.

Examples
Command line:
query node -type=nas

534 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Updatectime
Use the updatectime option to check the change time (ctime) attribute during an incremental backup
operation.

Supported Clients
This option is valid for AIX and Linux clients on GPFS file systems only. The server can also define this
option.

Options File
Place this option in the client user options file (dsm.opt).

Syntax
no
UPDATECTime
yes

Parameters
no
The backup-archive client does not check the change time (ctime attribute) during a backup
operation. This value is the default.
yes
The backup-archive client checks the change time (ctime attribute) during a backup operation. If the
ctime attribute changed since the last backup operation, the ctime attribute is updated on the IBM
Spectrum Protect server. The object is not backed up unless it has either ACLs or extended attributes.
The client checks files and directories.

Examples
Options file:
updatect yes
Command line:
dsmc incr /proj/gpfs/test/ -updatectime=yes

Useexistingbase
The useexistingbase option is used when you back up snapshots that are on NetApp filer volumes.
The useexistingbase option indicates that the latest snapshot that exists on the volume being backed
up, is to be used as the base snapshot, during a snapshot differential backup operation.
If this option is not specified, a new snapshot is created on the volume that is being backed up. Because
target filer volumes are read only volumes, useexistingbase must be specified when performing
snapshot differential backups of target filer volumes. If useexistingbase is not specified, snapshot
differential backups of a target filer volume fail because the new snapshot cannot be created on the read
only volume.
When backing up target 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

Supported Clients
This option can be used with supported x86_64 Linux clients.

Chapter 10. Processing options 535

 Options File
This option is only valid on the command line.

Syntax
USEEXISTINGBase

Parameters
This option has no parameters

Examples
Options file:
Does not apply.
Command line:

dsmc incr \\DRFiler\UserDataVol_Mirror_Share -snapdiff

-useexistingbase -basenameshotname="nightly.?"

Related information
Basesnapshotname

Usereplicationfailover
The usereplicationfailover option specifies whether automated client failover occurs on a client
node.
Use this option to enable a client node for failover or to prevent it from failing over to the secondary
server. This option overrides the configuration that is provided by the IBM Spectrum Protect server
administrator settings on the primary server.

Supported Clients
This option is valid for all clients.

Options File
Place this option within a server stanza in the dsm.sys file.

Syntax
Yes
USEREPLICATIONFailover
No

Parameters
Yes
Specifies that you want the client to automatically fail over to the secondary server if the primary
server is unavailable. The client uses the configuration that is provided by the primary server to
connect to the secondary server. This value is the default.
No
Specifies that the client does not automatically fail over to the secondary server.

Examples
Options file:
USEREPLICATIONFailover no

536 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Command line:
Does not apply.
Related concepts
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
Configuring the client for automated failover
You can manually configure the client to automatically fail over to the secondary server.

Users (deprecated)
This option is deprecated.

V2archive
Use the v2archive option with the archive command to archive only files to the server.
The backup-archive client will not process directories that exist in the path of the source file specification.
This option differs from the filesonly option in that the filesonly option archives the directories that
exist in the path of the source file specification.
The v2archive and dirsonly options are mutually exclusive and an error message is displayed if you
use both options in the same archive command.
If you use this option, you might want to consider the following:
• You might experience performance problems when retrieving large amounts of data archived with this
option.
• You might want to use this option only if you are concerned about expiration performance on a server
that already contains extremely large amounts of archived data.
• If there are multiple files with the same name for the v2archive option, the files are archived multiple
times, with their directory structure. The v2archive option archives only the files.

Supported Clients
This option is valid for all clients. The IBM Spectrum Protect API does not support this option.

Syntax
V2archive

Parameters
There are no parameters for this option.

Examples
This command:
dsmc archive "/Users/user2/Documents/*" -v2archive -su=y.
Archives these files:

/Users/user2/Documents/file1
/Users/user2/Documents/file2
/Users/user2/Documents/file3
/Users/user2/Documents/dir2/file4
/Users/user2/Documents/dir2/file5

Chapter 10. Processing options 537

 Note: The client does not archive /Users/user2/Documents and /Users/user2/Documents/
dir2.
This command:
dsmc archive "/home/relx/dir1/*" -v2archive -su=y.
Archives these files:

/home/relx/dir1/file1
/home/relx/dir1/file2
/home/relx/dir1/file3
/home/relx/dir1/dir2/file4
/home/relx/dir1/dir2/file5

Note: The client does not archive /home/relx/dir1 and /home/relx/dir1/dir2.

Verbose
The verbose option specifies that you want to display detailed processing information on your screen.
This is the default.
When you run the incremental, selective, or archive commands, information is displayed about
each file that is backed up. Use the quiet option if you do not want to display this information.
The following behavior applies when using the verbose and quiet options:
• If the server specifies either the quiet or verbose option in the server client option set, the server
settings override the client values, even if force is set to no on the server.
• If you specify quiet in your dsm.opt file, and you specify -verbose on the command line, -verbose
prevails.
• If you specify both -quiet and -verbose on the same command, the last option encountered during
options processing prevails. If you specify -quiet -verbose, -verbose prevails. If you specify -
verbose -quiet, -quiet prevails.
The information is displayed on your screen in the Scheduler Status window. This option only applies
when you are running the scheduler and the client is performing scheduled work.

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 client user-options file (dsm.opt). You can set this option on the Command Line
tab, Do not display process information on screen checkbox of the Preferences editor.

Syntax
VErbose

Parameters
There are no parameters for this option.

Examples
Options file:
verbose
Command line:
-verbose
This option is valid only on the initial command line. It is not valid in interactive mode.

538 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Verifyimage
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 backup-archive client issues a warning message on
the console and in the error log.

Supported Clients
This option is valid only for AIX, Oracle Solaris, and all Linux clients. The IBM Spectrum Protect API does
not support this option.

Syntax
VERIFYImage

Parameters
There are no parameters for this option.

Examples
Command line:
dsmc restore image /usr -verifyimage

Virtualfsname
Use the virtualfsname option with the backup group command to specify the name of the virtual file
space for the group on which you want to perform the operation. The virtualfsname cannot be the
same as an existing file space name.

Supported Clients
This option is valid for all UNIX and Linux clients except for Mac OS X.

Syntax
VIRTUALFsname = fsname

Parameters
fsname
Specifies the name of the container for the group on which you want to perform the operation.

Examples
Command line:

backup group -filelist=/Users/van/Documents/filelist1 -groupname=group1

-virtualfsname=/virtfs -mode=full

backup group -filelist=/home/dir1/filelist1 -groupname=group1

-virtualfsname=/virtfs -mode=full

Virtualmountpoint
The virtualmountpoint option defines a virtual mount point for a file system if you want to consider
files for backup that begin with a specific directory within that file system.
Using the virtualmountpoint option to identify a directory within a file system provides a direct path
to the files you want to back up, saving processing time. It is more efficient to define a virtual mount point

Chapter 10. Processing options 539

 within a file system than it is to define that file system using the domain option, and then to use the
exclude option in your include-exclude options list to exclude the files that you do not want to back up.
Use the virtualmountpoint option to define virtual mount points for multiple file systems, for local
and remote file systems, and to define more than one virtual mount point within the same file system.
Virtual mount points cannot be used in a file system handled by automounter.
You can use the virtualmountpoint option to back up unsupported file systems, with certain
limitations. For information about using virtualmountpoint with unsupported file systems, see “File
system and ACL support” on page 151.
Note: If the directory that you want to specify as a virtual mount point is a symbolic link, set the
followsymbolic option to Yes. If that option is set to no (the default), you are not permitted to use a
symbolic link as a virtual mount point. Also, if you back up a file system, then add a virtual mount point,
and then do another incremental on the file system, the files and directories in the virtual mount point
directory are expired, because they are logically contained within the virtual mount point directory and
not the file system.
After you define a virtual mount point, you can specify the path and directory name with the domain
option in either the default client options file or on the incremental command to include it for
incremental backup services. When you perform a backup or archive using the virtualmountpoint
option, the query filespace command lists the virtual mount point in its response along with other file
systems. Generally, directories that you define as virtual mount points are treated as actual file systems
and require that the virtualmountpoint option is specified in the dsm.sys file to restore or retrieve
the data.
Note: When you specify a virtualmountpoint option, the path that it specifies is added to the default
backup domain (domain all-local). The virtualmountpoint path is always considered a local
"mount point" regardless of the real file system type it points to.

Supported Clients
This option is valid for all UNIX clients except Mac OS X. The IBM Spectrum Protect API does not support
this option.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax

VIRTUALMountpoint directory

Parameters
directory
Specifies the path and directory name for the directory you want to use as the virtual mount point for
a file system. You cannot use wildcard characters in either the path or directory names.
Define only one virtual mount point with each virtualmountpoint option that you include in your
client system-options file. Use the virtualmountpoint option as many times as necessary to
define all of the virtual mount points that you want to use.

Examples
Options file:

virtualmountpoint /afs/xyzcorp.com/home/ellen
virtualmountpoint /afs/xyzcorp.com/home/ellen/test/data

540 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Command line:
Does not apply.

Virtualnodename
The virtualnodename option specifies the node name of your workstation when you want to restore or
retrieve files to a different workstation.
When you use the virtualnodename option in your client options file, or with a command:
• You must specify the name you specified with the nodename option in your client system-options file
(dsm.sys). This name should be different from the name returned by the hostname command on your
workstation.
• The client prompts for the password assigned to the node that you specify, if a password is required
(even when the passwordaccess option is set to generate). If you enter the correct password, you
have access to all backups and archives that originated from the specified node.
When connecting to a server, the client must identity itself to the server. This login identification is
determined in the following ways:
• If the nodename and virtualnodename options are not specified, or a virtual node name is not
specified on the command line, the default login ID is the name returned by the hostname command.
• If the nodename option is specified, the name specified with the nodename option overrides the name
returned by the hostname command.
• If the virtualnodename option is specified, or a virtual node name is specified on a command line, it
cannot be the same name as the name returned by the hostname command.

Supported Clients
This option is valid for all clients.

Options File
Place this option in the client user-options file (dsm.opt).

Syntax
VIRTUALNodename nodename

Parameters
nodename
Specifies a 1- to 64-character name that identifies the node for which you want to request IBM
Spectrum Protect services. There is no default.

Examples
Options file:
virtualnodename cougar
Command line:
-virtualn=banshee
This option is valid only on the initial command line. It is not valid in interactive mode.

Vmbackdir
The vmbackdir option specifies the temporary disk location where the client saves control files that are
created during full VM backup and restore operations of virtual machines.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.

Chapter 10. Processing options 541

 When a client on a data mover node starts a full VM backup of a virtual machine, the client creates
metadata in files that are associated with the backed up virtual machine and its data. The files that
contain the metadata are referred to as control files.
During full VM backup operations, the metadata is saved on a disk in the data mover node until the
backup completes and both the virtual machine data and the control files are saved to server storage.
During a full VM restore operation, the control files are copied from the server and are temporarily stored
on the data mover disk, where they are used to restore the virtual machine and its data. After a backup or
a restore operation completes, the control files are no longer needed and the client deletes them from
their temporary disk location.
The directory that is specified by this option must be on a drive that contains sufficient free space to
contain the control information from a full VM backup.

Supported Data Movers

This option is valid for Linux and Windows data movers that are installed on a vStorage backup server.

Options File
Set this option in the client options file, or specify it on the command line as an option for the backup vm
or restore vm commands.

Syntax
VMBACKDir directory

Parameters
directory
Specifies the path where the control files are stored on the backup server.
The default is /tmp/tsmvmbackup/fullvm/

Examples
Options file:
VMBACKD /tmp/tmsvmbackup/
Command line:
dsmc backup vm -VMBACKUPT=fullvm -VMBACKD=/home/vmware/control_files
dsmc restore vm -VMBACKUPT=fullvm -VMBACKD=/home/mine/bkup_ctrl

Vmbackuplocation
Use the vmbackuplocation option with the backup vm or restore vm commands to specify the
backup location for virtual machine backup and restore operations.
This option is only valid for VMware virtual machines. To use this option, you must have a license
agreement to use IBM Spectrum Protect for Virtual Environments: Data Protection for VMware.
For restore operations, this option is ignored if the vmrestoretype option is set to mountcleanup or
mountcleanupall.

Supported Clients
This option can be used with supported x86_64 Linux clients.

Options file
This option must be specified on the command line of a backup vm or restore vm command. You
cannot set this option in the client options file.

542 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Syntax
SERVER

-VMBACKUPLOCation LOCAL

BOTH

Parameters
SERVER
For backup operations, specifies that virtual machines are backed up to the IBM Spectrum Protect
server.
For restore operations, specifies that virtual machines are restored from the IBM Spectrum Protect
server.
This value is the default.
LOCAL
For backup operations, specifies that virtual machines are backed up on the hardware storage. The
backup is a full virtual machine image snapshot, even if an incremental backup is specified.
To create a local backup, the virtual machine must be stored in a VMware virtual volume (VVOL)
datastore. If any virtual disk of the virtual machine is not in a VVOL datastore, the local backup is not
allowed.
For restore operations, specifies that virtual machines are restored from persisted snapshots that are
on the hardware storage.
By restoring from a local snapshot, you can only revert an existing virtual machine. You cannot restore
a deleted virtual machine, and you cannot restore a virtual machine to a different name or location.
Local restore is not valid if the following parameters are used for the restore vm command:
• VMNAME
• DATACENTER
• HOST
• DATASTORE
• :vmdk
This value is also not valid if the vmrestoretype option is set to one of the following values. If these
values are set, an error message is displayed.
• instantaccess
• instantrestore
• mount
Because no network data movement is needed for local snapshots, backup and restore operations
can be faster than server backup and restore operations.
BOTH
For backup operations, specifies that virtual machines are backed up to the IBM Spectrum Protect
server and are also backed up locally. The local backup is always a full image snapshot of the VMs,
even if incremental backups are configured for the server.
For restore operations, specifies that virtual machines are restored from the latest active version
regardless whether it is a local or a server backup. If both active backups have the same timestamp,
the local backup is used for the restore.
This value is not valid with the parameters and vmrestoretype option values that are listed above
for the LOCAL value.

Chapter 10. Processing options 543

 Examples
Command line:
Perform a full server and local backup for virtual machine vm1:

dsmc backup vm vm1 -vmbackuplocation=BOTH -vmbackuptype=FUllvm

Perform a local restore for virtual machine vm1:

dsmc restore vm vm1 -vmbackuplocation=LOCAL

Vmbackupmailboxhistory
The vmbackupmailboxhistory option specifies whether mailbox history is automatically uploaded
with the virtual machine (VM) backup if IBM Spectrum Protect for Mail: Data Protection for Microsoft
Exchange Server is detected on a VM.

Supported Clients
This option is valid on clients that act as a data mover for VMware guest 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.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax
Yes
VMBACKUPMAILBoxhistory
No

Parameters
Yes
The mailbox history is automatically uploaded with the VM backup if IBM Spectrum Protect for Mail:
Data Protection for Microsoft Exchange Server is detected on a VM.
No
The mailbox history is not automatically uploaded with the VM backup.

Examples
Options file:
vmbackupmailboxhistory yes

Vmbackuptype
Use the vmbackuptype option with the backup VM or restore VM command to specify to specify the
type of virtual machine backup or restore to complete. You can also use this option on query VM
commands to filter the query results to include only virtual machines that were backed up by a specific
backup type. For examples, see the query VM command description.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.
You can specify a VMware full VM backup.

544 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Supported Clients
This option is valid on Linux data movers that are installed on a vStorage backup server. The server can
also define this option.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax
FUllvm
VMBACKUPType

Parameters
FUllvm
Specify this value to run a traditional full VM backup of a VMware virtual machine. This is the default
backup type for Linux clients.

Examples
Options file:
VMBACKUPT full
Command line:
dsmc backup vm vm1 -VMBACKUPT=full -vmchost=virtctr -vmcuser=virctr_admin -
vmcpw=xxxxx
Performs a full virtual-machine backup of vm1.example.com using the VMware VirtualCenter
machine virtctr.example.com, to the IBM Spectrum Protect server, using machine name vm1.

Vmchost
Use the vmchost option with the backup VM, restore VM, or query VM commands to specify the host
name of the VMware VirtualCenter or ESX server that you want to backup, restore, or query.
Use the VirtualCenter if it is available. If you cannot use a VirtualCenter server and you need to perform
backups of multiple systems on multiple ESX servers, do not specify this option, but instead specify the
option with the command so that it can be varied for each ESX server.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Supported Clients
This command is valid for clients that are configured to perform an off-host backup of a VMware virtual
machine. The server can also define this option.

Options File
Place this option in the client options file (dsm.opt), the client system options file (dsm.sys), or on the
command line.

Syntax
VMCHost hostname

Chapter 10. Processing options 545

 Parameters
hostname
Specifies the host name of the VMware VirtualCenter or ESX server that you want to backup, restore,
or query.

Examples
Options file:
VMCH vcenter.storage.usca.example.com
Command line:

-VMCH=esx1.storage.usca.example.com

Vmcpw
Use the vmcpw option with the backup VM, restore VM, or query VM commands to specify the
password for the VMware VirtualCenter or the ESX user ID that is specified with the vmcuser option.
Use the VirtualCenter if it is available. If you cannot use a VirtualCenter server and you need to perform
backups of multiple systems on multiple ESX servers, do not specify this option, but instead specify the
option with the command so that it can be varied for each ESX server.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Supported Clients
This option is valid only on supported Linux clients that are installed on a vStorage backup server that is
used to backup a VMware virtual machine.

Options File
Place this option in the client system options file (dsm.sys), or on the command line.
1. Click Edit > Client Preferences > VM Backup. In the Password field, type the password that you want
to have saved.
2. Click OK.
As an alternative to the preferences editor, you can store the password locally by using the set
password command. For example:

dsmc SET PASSWORD -type=vm

vcenter.us.ibm.com Administrator secret

Syntax
VMCPw pwname

Parameters
pwname
Specifies the password for the VMware VirtualCenter or ESX server that you want to backup, restore,
or query.

Examples
Options file:
VMCPw SECRET
Command line:
-VMCPw=SECRET

546 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Related reference
“Set Password” on page 706
The set password command changes the IBM Spectrum Protect password for your workstation, or sets
the credentials that are used to access another server.

Vmctlmc
This option specifies the management class to use when backing up virtual machine control files.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.
By default, virtual machine control files are bound to the default management class. The vmmc option can
be used to specify a different management class to which virtual machine data and virtual machine
control files are bound. The vmctlmc option overrides the default management class and the vmmc option
for the virtual machine control files.
Under certain conditions, it might be desirable or necessary to bind the control files to a different
management class than the data files.
The vmctlmc option is required if virtual machine data files are backed up to tape. Virtual machine
control files must be backed up to a disk-based storage pool that does not migrate to tape. The storage
pool can be composed of random access volumes and sequential file volumes; the storage pool can also
be a deduplicated pool. Use the vmctlmc option to specify a management class that stores data in such a
storage pool.
Restriction: The management class that is specified by the vmctlmc option determines only the
destination storage pool for virtual machine control files. Retention of the control files is determined by
the vmmc option, if specified, or by the default management class. The retention for the virtual machine
control files always matches the retention of the virtual machine data files.

Supported Clients
This option is valid for clients that act as data mover nodes that protect VMware virtual machines.
The option can only be used for virtual machine backups that use an incremental-forever backup mode.
This option is available only if you have a license to use either IBM Spectrum Protect for Virtual
Environments: Data Protection for VMware or IBM Spectrum Protect for Virtual Environments: Data
Protection for Microsoft Hyper-V.

Options File
Place this option in the system options file dsm.sys.

Syntax
VMCTLmc class_name

Parameters
class_name
Specifies a management class that applies to backing up virtual machine control files. If you do not
set this option, the management class that is specified on the vmmc option is used. If you do not set
this option and the vmmc option is not set, the default management class of the node is used.

Examples
Options file:
vmctlmc diskonlymc

Chapter 10. Processing options 547

 Command line:
Does not apply.

Vmcuser
Use the vmcuser option with the backup VM, restore VM, or query VM commands to specify the user
name of the VMware VirtualCenter or ESX server that you want to backup, restore, or query.
Use the VirtualCenter if it is available. If you cannot use a VirtualCenter server and you need to perform
backups of multiple systems on multiple ESX servers, do not specify this option, but instead specify the
option with the command so that it can be varied for each ESX server.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Supported Clients
This option is valid for clients that are configured as to perform an off-host backup of VMware virtual
machines. The server can also define this option.

Options File
Place this option in the client options file (dsm.opt), the client system options file (dsm.sys), or on the
command line.

Syntax
VMCUser username

Parameters
username
Specifies the user name of the VMware VirtualCenter or ESX server that you want to backup, restore,
or query.
When working with a virtual center, a user id with access to the Windows system hosting the virtual
center is required. This user id must either have administrator privileges, or the minimum privileges
that are identified in technote 1659544.

Examples
Options file:
VMCUser administrator
Command line:

backup vm -VMCUser=domainname\administrator

Command line:
Example of connecting to an ESX server:

backup vm -VMCUser=root

Vmdatastorethreshold
Use the vmdatastorethreshold option to set the threshold percentage of space usage for each
VMware datastore of a virtual machine.
When you specify this option, space usage is checked before a virtual machine snapshot is created. If the
threshold is exceeded, the virtual machine is not backed up. By setting this option, you can prevent out-
of-space errors when you back up virtual machines.

548 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Supported clients
You can use this option with supported x86_64 Linux clients.

Options file
You can specify this option in the client system-options file (dsm.sys) or on the command line by using
the backup vm command. You can also include this option on the IBM Spectrum Protect Version 7.1.5 or
later server in a client option set. You cannot set this option in the Preferences Editor.

Syntax
VMDATASTORETHreshold percent

Parameters
percent
Specifies the threshold percentage of each VMware datastore of the virtual machine to be backed up.
You can specify an integer from 0 - 100. The default value is 100. If you do not set this option, the
client begins a virtual machine backup without first verifying the existing space usage.
Requirements:
• Ensure that the threshold is low enough so that the snapshot does not use up all the available space
in the VMware datastores. Otherwise, you will run out of space on the VMware datastores and the
snapshot will not be created.
• If you use multiple clients that act as data mover nodes, you must add this option to the options file
for each data mover.
• The client checks the data usage of the VMware datastore that contains the virtual machine disk
snapshots. By default, the snapshots are created in the same directory as that of the parent virtual
disk (.vmdk) file.
If you change the snapshot location to a new directory on the same datastore or on another
datastore with the workingDir option in the VM configuration file, ensure that the path of the
working directory is correct. If the path is incorrect, the client might validate the data usage of the
wrong datastore.
If you use the EXCLUDE.VMDISK option to exclude one or more disks from a backup, the threshold
check is still run on these disks. Even though these disks are not backed up, VMware still takes a
snapshot of these disks.
Independent disks are not checked during space verification processing because a snapshot of these
disks does not use any VMware datastore space.

Example 1
Virtual machine vm1 spans datastore1 and datastore2. Set the vmdatastorethreshold option to
90 to ensure that both VMware datastores are at most 90% full before the virtual machine is backed up.
Options file:
vmdatastorethreshold 90
Command line:
dsmc backup vm vm1 -vmdatastorethreshold=90

Chapter 10. Processing options 549

 Example 2
The datastore threshold of datastore2 is set to 85. The datastore threshold is exceeded during the
backup of virtual machine vm5. The following error message is displayed:

ANS14200E The virtual machine 'vm5' could not be backed up because the
data usage of datastore 'datastore2' exceeded the datastore threshold
of 85%.

Increase the value of the vmdatastorethreshold option to 95 and restart the backup.
Options file:
vmdatastorethreshold 95
Command line:
dsmc backup vm vm5 -vmdatastorethreshold=95
Related reference
“Backup VM” on page 608

Vmdefaultdvportgroup
Use this option to specify the port group for the NICs to use during restore vm operations for a virtual
machine that was connected to a distributed virtual port group when it was backed up, but the target host
for the restore operation does not contain a similar distributed virtual port group.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.
This option does not apply to backup or restore operations for Microsoft Hyper-V virtual machines.

Supported clients
This option is valid for Linux clients that are installed on a vStorage backup server.

Options file
Place this option in the client options file (dsm.opt), in the client system options file (dsm.sys), or
specify it as a command-line parameter on the restore vm command.

Syntax
VMDEFAULTDVPORTGROUP portgroup_name

Parameters
portgroup name
Specifies the name of the port group to use. The port group name is case sensitive.

Examples
Option file:

VMDEFAULTDVPORTGROUP dvPortGroup

Command line:

dsmc restore vm vm123 -VMDEFAULTDVPORTGROUP=dvPortGroup

Related reference
“Vmdefaultnetwork” on page 551

550 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Use this option to specify the network for NICs to use during a restore vm operation, for a virtual
machine that had been connected to a distributed virtual port group when it was backed up, but the target
host for the restore operation does not have any distributed switch port groups configured.
“Vmdefaultdvswitch” on page 551
Use this option to specify the distributed virtual switch (dvSwitch) that contains the port group that you
set on the vmdefaultdvportgroup option. The option has no effect unless you also specify the
vmdefaultdvportgroup option.

Vmdefaultdvswitch
Use this option to specify the distributed virtual switch (dvSwitch) that contains the port group that you
set on the vmdefaultdvportgroup option. The option has no effect unless you also specify the
vmdefaultdvportgroup option.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Supported clients
This option is valid for Linux clients that are installed on a vStorage backup server.

Options file
Place this option in the client options file (dsm.opt), in the client system options file (dsm.sys), or
specify it as a command-line parameter on the restore vm command.

Syntax
VMDEFAULTDVSWITCH dvSwitch

Parameters
dvSwitch
Specifies the name of the virtual switch to use. The virtual switch name is case sensitive.

Examples
Option file:

VMDEFAULTDVSWITCH dvSwitch

Command line:

dsmc restore vm vm123 -VMDEFAULTDVSWITCH=dvSwitch -VMDEFAULTDVPORTGROUP=dvPortGroup

Related reference
“Vmdefaultdvportgroup” on page 550
Use this option to specify the port group for the NICs to use during restore vm operations for a virtual
machine that was connected to a distributed virtual port group when it was backed up, but the target host
for the restore operation does not contain a similar distributed virtual port group.

Vmdefaultnetwork
Use this option to specify the network for NICs to use during a restore vm operation, for a virtual
machine that had been connected to a distributed virtual port group when it was backed up, but the target
host for the restore operation does not have any distributed switch port groups configured.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Chapter 10. Processing options 551

 Supported clients
This option is valid for Linux clients that are installed on a vStorage backup server.

Options file
Place this option in the client options file (dsm.opt), in the client system options file (dsm.sys), or
specify it as a command-line parameter on the restore vm command.

Syntax
VMDEFAULTNETWORK vm_network_name

Parameters
vm_network_name
Specifies the name of the virtual machine network to use. The network name is case sensitive. If the
name contains space characters, enclose it in quotation marks.

Examples
Option file:

VMDEFAULTNETWORK "VM Network"

Command line:

dsmc restore vm vm123 -VMDEFAULTNETWORK="VM Network"

Related reference
“Vmdefaultdvportgroup” on page 550
Use this option to specify the port group for the NICs to use during restore vm operations for a virtual
machine that was connected to a distributed virtual port group when it was backed up, but the target host
for the restore operation does not contain a similar distributed virtual port group.
“Vmdefaultdvswitch” on page 551
Use this option to specify the distributed virtual switch (dvSwitch) that contains the port group that you
set on the vmdefaultdvportgroup option. The option has no effect unless you also specify the
vmdefaultdvportgroup option.

Vmenabletemplatebackups
The vmenabletemplatebackups option specifies whether the client backs up VMware template virtual
machines when it protects virtual machines in a vCenter server. VMware templates virtual machines
cannot be backed up when they are in an ESXi host because ESXi does not support templates.
When this option is enabled, you can include VMware template machines in full VM backup operations.
You use the existing Backup VM command and the DOMAIN.VMFULL option to specify the virtual
machines to include in the backup 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.
Incremental backups are not supported and snapshots are not taken, so you must use MODE=IFFULL.
Use MODE=IFFULL to force a new backup of VMware template virtual machines, even if they were not
changed since the last backup.
When vmenabletemplatebackups is enabled, any backup process that is initiated by using
MODE=IFINCREMENTAL is processed by using MODE=IFFULL. VMware template VMs are included in a
backup only if they were changed since the last backup occurred.

552 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
With this option enabled, make sure that the vmvstortransport options include NBDSSL or NBD. Using
only the SAN or HOTADD transport modes with this option enabled causes backups of the template
machines to fail.

Supported clients
This option can be used with supported x86_64 Linux clients.

Options file
You can set this option on the command line, in the client system options file (dsm.sys), client options
file (dsm.opt), or on the server in a client options set.
You can also set it in the preferences editor on the VM Backup tab (select the Backup virtual machine
templates option).

Syntax
No
VMENABLETEMPlatebackups
Yes

Parameters
No
Specifies that template virtual machines are not included in full VM backup operations; this is the
default setting.
Yes
Specifies that template VMs are included in full VM backup operations.

Examples
Options file
vmenabletemplatebackups yes
Command line
Back up a VMware template VM

dsmc backup vm vmname -VMENABLETEMPLATEBACKUPS=YES

where vmname is the template machine name.

Command line
Restore a VMware template VM to the same location and name

dsmc restore vm vmname -VMENABLETEMPLATEBACKUPS=YES

where vmname is the template machine name.

Command line
Restore a template virtual machine to a new location

dsmc restore vm vmname -vmname=win7x64

-datastore=datastore22 -host=supersht.labx.com
-datacenter="Lab Center" -VMENABLETEMPLATEBACKUPS=YES

where vmname is the template machine name. "win7x64" is the new template VM name. The new
data center, host, and datastore are also included.
Related reference
“Backup VM” on page 608
“Restore VM” on page 681

Chapter 10. Processing options 553

 Use the restore vm command to restore a virtual machine (VM) that was previously backed up.
“Domain.vmfull” on page 355
The domain.vmfull option specifies the virtual machines (VMs) to include in your full virtual machine
image backup operations.

Vmlimitperdatastore
The vmlimitperdatastore option specifies the number of virtual machines (VMs) and virtual disks in a
datastore that can be processed in parallel during an optimized backup operation.
An optimized backup operation is one in which parallel backup capability is enabled at the VM, virtual
disk, or subdisk level.
The vmlimitperdatastore option works with the vmmaxparallel, vmmaxbackupsessions, and
vmlimitperhost options to optimize backup operations and to help control the amount of resources
that the backup can create on a host in the vSphere infrastructure. Adjust the values of these options to
find the values that provide optimal performance for the backups that are in your environment.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Supported clients
This option can be used with supported x86_64 Linux clients.

Options file
This option is valid in the client system options file (dsm.sys), in the client options file (dsm.opt) or on
the command line for Backup VM. It can also be included on the server in a client options set. It cannot
be set in the Preferences Editor.

Syntax
0
VMLIMITPERDatastore
integer

Parameters
integer
Specifies the maximum number of VMs in any one datastore that are included during an optimized
backup operation. The maximum that you can specify is 50 VMs. The default is 0 (zero).
Specifying 0 means that you are not concerned about how many VMs can be backed up in parallel
from a datastore. Instead, you want to limit the maximum number of VMs to include in a backup by
using the value that you specify on the vmmaxparallel option. The vmlimitperdatastore option
is enforced even when VM data exists in two or more datastores.

Examples
Options file
VMLIMITPERD 5
Command line:
dsmc backup vm -VMLIMITPERD=5
Related reference
“Backup VM” on page 608
“Domain.vmfull” on page 355

554 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 The domain.vmfull option specifies the virtual machines (VMs) to include in your full virtual machine
image backup operations.
“Vmmaxbackupsessions” on page 556
The vmmaxbackupsessions option specifies the maximum number IBM Spectrum Protect server
sessions that move virtual machine (VM) data to the server that can be included in an optimized backup
operation.
“Vmmaxparallel” on page 558
The vmmaxparallel option is used to configure optimized backups of several virtual machines by using
a single instance of the backup-archive client. This option specifies the maximum number of virtual
machines that can be backed up to the IBM Spectrum Protect server at any one time.
“Vmlimitperhost” on page 555
The vmlimitperhost option specifies the number of virtual machines (VMs) and virtual disks in a host
that can be processed in parallel during an optimized backup operation.
Related information
Backing up multiple virtual machines in parallel

Vmlimitperhost
The vmlimitperhost option specifies the number of virtual machines (VMs) and virtual disks in a host
that can be processed in parallel during an optimized backup operation.
An optimized backup operation is one in which parallel backup capability is enabled at the VM, virtual
disk, or subdisk level.
The vmlimitperhost option works with the vmmaxparallel, vmmaxbackupsessions, and
vmlimitperdatastore options to optimize backup operations and to help control the amount of
resources that the backup can create on a host in the vSphere infrastructure. Adjust the values of these
options to find the values that provide optimal performance for the backups that are in your environment.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Supported clients
This option can be used with supported x86_64 Linux clients.

Options file
This option is valid in the client system options file (dsm.sys), in the client options file (dsm.opt) or on
the command line for Backup VM. It can also be included on the server in a client options set. It cannot
be set in the Preferences Editor.

Syntax
0
VMLIMITPERHost
integer

Parameters
integer
Specifies the maximum number of VMs in any one ESX server that can be included in an optimized
backup operation. The maximum that you can specify is 50 VMs. The default is 0 (zero).
Specifying 0 means that you are not concerned about how many VMs can be backed up in parallel
from an ESX server. Instead, you want to limit the maximum number of VMs to include in a backup by
using the limit that you specify on the vmmaxparallel option.

Chapter 10. Processing options 555

 Examples
Options file
VMLIMITPERH 5
Command line:
dsmc backup vm -VMLIMITPERH=5
Related reference
“Backup VM” on page 608
“Domain.vmfull” on page 355
The domain.vmfull option specifies the virtual machines (VMs) to include in your full virtual machine
image backup operations.
“Vmmaxparallel” on page 558
The vmmaxparallel option is used to configure optimized backups of several virtual machines by using
a single instance of the backup-archive client. This option specifies the maximum number of virtual
machines that can be backed up to the IBM Spectrum Protect server at any one time.
“Vmlimitperhost” on page 555
The vmlimitperhost option specifies the number of virtual machines (VMs) and virtual disks in a host
that can be processed in parallel during an optimized backup operation.
Related information
Backing up multiple virtual machines in parallel

Vmmaxbackupsessions
The vmmaxbackupsessions option specifies the maximum number IBM Spectrum Protect server
sessions that move virtual machine (VM) data to the server that can be included in an optimized backup
operation.
An optimized backup operation is one in which parallel backup capability is enabled at the VM, virtual
disk, or subdisk level.
For VMware VMs, the vmmaxbackupsessions option works with the vmmaxparallel,
vmlimitperdatastore, and vmlimitperhost options to optimize backup operations and to help
control the amount of resources that the backup can create on a host in the vSphere infrastructure. Adjust
the values of these options to find the values that provide optimal performance for the backups that are in
your environment.

Supported clients

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.
For VMware VMs, this option can be used with supported x86_64 Linux clients.

Options file
This option is valid in the client system options file (dsm.sys), in the client options file (dsm.opt), or on
the command line for Backup VM. It can also be included on the server in a client options set. It cannot
be set in the Preferences Editor.

Syntax
4
VMMAXBACKUPSEssions
integer

556 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Parameters
integer
Specifies the maximum number of IBM Spectrum Protect server sessions that can be created during
the backup operation.
The default is 4. The maximum is 100.
Review the following information for using the vmmaxbackupsessions option along with the
vmmaxparallel option or the maxnummp server parameter:
vmmaxparallel
The vmmaxparallel option specifies the maximum number of virtual machines that can be
backed up to the IBM Spectrum Protect server at any one time. The value of the
vmmaxbackupsessions option must be equal to or greater than the value of the
vmmaxparallel option.
If the value is less than the value of the vmmaxparallel option, the following message is
returned and the value is changed to the same value as the vmmaxparallel option:
ANS9995W The value of the VMMAXBACKUPSESSIONS option is number_value.
This value must be greater than or equal to the value of the
VMMAXPARALLEL option, which is number_value. The value will be set to the
value of the VMMAXPARALLEL option.
maxnummp
The maxnummp server parameter specifies the maximum number of mount points a node is
allowed to use on the server when the copy destination of the storage pool is FILE or TAPE. The
maxnummp parameter must be equal to or greater than the vmmaxparallel and
vmmaxbackupsessions option settings. When multiple instances of the client are backing up
files, or when a single client performs parallel backup operations, more mount points might be
required.
If the values for vmmaxparallel or vmmaxbackupsessions exceed the value for maxnummp,
ANS0266I and other messages are displayed. Depending on the message, the client reduces the
value of the vmmaxparallel option to match the number that is specified by maxnummp
parameter or prohibits additional sessions from being opened for the specified VM. In either
situation, the backup operation continues.
If additional ANS0266I errors are detected, the client reduces the vmmaxparallel value by 1
and attempts to continue the backup. If vmmaxparallel is decremented to 1 and the client
receives more ANS0266I errors, the client ends the backup and issues the following error:
ANS5228E A backup VM operation failed because VMMAXPARALLEL was reduced
to 1 and the client still cannot obtain a server mount point.
Contact your server administrator if you want the value that is currently set for maxnummp
increased so that a node can support additional parallel backup sessions.
The maximum that you can specify is 100 sessions. The default is the value that is set for the
vmmaxparallel option.

Examples
Options file
VMMAXBACKUPS 10
Command line:
dsmc backup vm -VMMAXBACKUPS=10
Related reference
“Backup VM” on page 608
“Domain.vmfull” on page 355

Chapter 10. Processing options 557

 The domain.vmfull option specifies the virtual machines (VMs) to include in your full virtual machine
image backup operations.
“Vmmaxparallel” on page 558
The vmmaxparallel option is used to configure optimized backups of several virtual machines by using
a single instance of the backup-archive client. This option specifies the maximum number of virtual
machines that can be backed up to the IBM Spectrum Protect server at any one time.
“Vmlimitperdatastore” on page 554
The vmlimitperdatastore option specifies the number of virtual machines (VMs) and virtual disks in a
datastore that can be processed in parallel during an optimized backup operation.
“Vmlimitperhost” on page 555
The vmlimitperhost option specifies the number of virtual machines (VMs) and virtual disks in a host
that can be processed in parallel during an optimized backup operation.
Related information
Backing up multiple virtual machines in parallel

Vmmaxparallel
The vmmaxparallel option is used to configure optimized backups of several virtual machines by using
a single instance of the backup-archive client. This option specifies the maximum number of virtual
machines that can be backed up to the IBM Spectrum Protect server at any one time.
An optimized backup operation is one in which parallel backup capability is enabled at the VM, virtual
disk, or subdisk level.
The vmmaxparallel option works with the vmmaxbackupsessions, vmlimitperhost, and
vmlimitperdatastore options to optimize backup operations and to help control the amount of
resources that the backup can create on a host in the vSphere infrastructure. Adjust the values of these
options to find the values that provide optimal performance for the backups that are in your environment.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.

Supported clients
This option can be used with supported x86_64 Linux clients.

Options file
This option is valid in the client system options file (dsm.sys) or on the command line for the Backup VM
command. It can also be included on the server in a client options set. It cannot be set in the Preferences
Editor.

Syntax
4
VMMAXParallel
integer

Parameters
integer
Specifies the maximum number of virtual machines that can be backed up at any one time during an
optimized backup operation.
The default is 4. The maximum is 50.

Tip: When you use client-side data deduplication, a data deduplication session is started for each VM.
This data deduplication session is not counted as one of the vmmaxparallel sessions.

558 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Review the following information for using the vmmaxparallel option in conjunction with the
vmmaxbackupsessions option or the maxnummp server parameter:
vmmaxbackupsessions
For Data Protection for VMware, the vmmaxbackupsessions specifies the maximum number of
sessions that move virtual machine data to the server that can be included in an optimized backup
operation. The value of the vmmaxbackupsessions option must be equal to or greater than the
value of the vmmaxparallel option.
maxnummp
The maxnummp server parameter specifies the maximum number of mount points a node is
allowed to use on the server when the copy destination of the storage pool is FILE or TAPE. The
maxnummp parameter must be equal to or greater than the vmmaxparallel and
vmmaxbackupsessions option settings. When multiple instances of the client are backing up
files, or when a single client performs parallel backup operations, more mount points might be
required.
If the values for vmmaxparallel or vmmaxbackupsessions exceed the value for maxnummp,
ANS0266I and other messages are displayed. Depending on the message, the client reduces the
value of the vmmaxparallel option to match the number that is specified by maxnummp
parameter or prohibits additional sessions from being opened for the specified VM. In either
situation, the backup operation continues.
If additional ANS0266I errors are detected, the client reduces the vmmaxparallel value by 1
and attempts to continue the backup. If vmmaxparallel is decremented to 1 and the client
receives more ANS0266I errors, the client ends the backup and issues the following error:
ANS5228E A backup VM operation failed because VMMAXPARALLEL was reduced
to 1 and the client still cannot obtain a server mount point.
Contact your server administrator if you want the value that is currently set for maxnummp
increased so that a node can support additional parallel backup sessions.

Examples
Options file
VMMAXP 10
Related reference
“Backup VM” on page 608
“Domain.vmfull” on page 355
The domain.vmfull option specifies the virtual machines (VMs) to include in your full virtual machine
image backup operations.
“Vmlimitperhost” on page 555
The vmlimitperhost option specifies the number of virtual machines (VMs) and virtual disks in a host
that can be processed in parallel during an optimized backup operation.
“Vmlimitperdatastore” on page 554
The vmlimitperdatastore option specifies the number of virtual machines (VMs) and virtual disks in a
datastore that can be processed in parallel during an optimized backup operation.
Related information
Backing up multiple virtual machines in parallel

Vmmaxrestoresessions
The vmmaxrestoresessions option defines the aggregate number of sessions which will be allocated
for the IBM Spectrum Protect server optimized restore operation.
A optimized restore operation is one in which parallel restore capability is enabled at the subdisk level of
a virtual disk.
Note: At least one session must be allocated for each disk that is being restored.

Chapter 10. Processing options 559

 Note: If the value of vmmaxrestoresessions is less than the value of vmmaxrestoreparalleldisks
multiplied by vmmaxrestoreparallelvms, the value will automatically be adjusted to the value of
vmmaxrestoreparalleldisks multiplied by vmmaxrestoreparallelvms at runtime.

Supported clients
This option can be used with supported x86_64 Linux clients.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.

Options file
This option is valid in the client system options file (dsm.sys), in the client options file (dsm.opt), or on
the command line for Restore VM. It can also be included on the server in a client options set. It cannot
be set in the Preferences Editor.

Syntax
8
VMMAXRESTORESessions
integer

Parameters
integer
Specifies the number of IBM Spectrum Protect server sessions that are created during the restore
operation. The default is 8. The maximum is 100.

Examples
Options file
VMMAXRESTORES 5
Command line:
dsmc restore vm webserver1 -VMMAXRESTORES=5
Note: This command line example for this option is valid in both Windows and Linux supported clients.
Related reference
“Restore VM” on page 681
Use the restore vm command to restore a virtual machine (VM) that was previously backed up.

Vmmaxrestoreparalleldisks
The vmmaxrestoreparalleldisks option enables an IBM Spectrum Protect client to restore specific
multiple virtual disks at the same time per virtual machine.
You can specify the number of disk sessions to be opened, up to a maximum of 10. Sessions are allocated
per disk based on the transport type from the option vmvstortransport. Available sessions are
allocated across the number of disk sessions specified by vmmaxrestoreparalleldisks, by rounding
down the number of sessions per disk to the nearest whole number.

Supported clients
This option can be used with supported x86_64 Linux clients.
Note:
You must ensure the total number of restore operations from all sources to the same ESXi host does not
exceed 26. Due to an ESXi host issue, exceeding this number of parallel restores may cause the operation

560 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 to fail. For example, if you have 3 different restore instances to the same ESXi host, each with
VMMAXRESTOREPARALLELDISKS 10, the restores may fail because the total number of connections is 30

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Options file
This option is valid in the client system options file (dsm.sys), or on the command line for Restore VM.
It can also be included on the server in a client options set. It cannot be set in the Preferences Editor.

Syntax
2
VMMAXRESTOREPARALLELDisks
integer

Parameters
integer
Specifies the number of virtual hard disks that can be restored simultaneously. The default is 2. The
maximum is 10.

Examples
Task
Set a maximum of 2 simultaneous restore operations for virtual disks in the restore operation of the
virtual machine vm1:

dsmc restore vm vm1 -vmmaxrestoreparalleldisks=2 -vmmaxrestoresessions=8

This will assign 4 simultaneous restore sessions per virtual disk.

Related reference
“Restore VM” on page 681
Use the restore vm command to restore a virtual machine (VM) that was previously backed up.

Vmmaxrestoreparallelvms
The vmmaxrestoreparallelvms option controls the number of virtual machines an IBM Spectrum
Protect client can restore at the same time.
Use this option to increase restore performance by increasing the number of virtual machines to restore
in parallel.
You can specify the number of virtual machines to be restored simultaneously, up to a maximum of 10.
The default value is 2.

Supported clients
This option can be used with supported x86_64 Linux 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.

Options file
This option is valid in the client system options file (dsm.sys), or on the command line for Restore VM.
It can also be included on the server in a client options set. It cannot be set in the Preferences Editor.

Chapter 10. Processing options 561

 Syntax
2
VMMAXRESTOREPARALLELVms
integer

Parameters
integer
Specifies the maximum number of virtual machines that can be restored simultaneously. The default
is 2. The maximum is 10.
Note: If you are using the Vmmaxrestoresessions option to limit the number of restore sessions, the
number of sessions has to be greater than or equal to the number of virtual machines. This ensures at
least one session is available per VM.
Note: If you are using the option Vmmaxparalleldisks to restore multiple virtual disks at same time,
the number of virtual disks must be less than or equal to the number of sessions.

Examples
Task
Set a maximum of 5 simultaneous virtual machine restores for machines vm1, vm2, vm3, vm4, and
vm5:

dsmc restore vm1,vm2,vm3,vm4,vm5 -VMMAXRESTOREPARALLELVms=5

VMMAXRESTORESessions=10 -VMMAXRESTOREPARALLELDisks=2

This will assign 5 simultaneous virtual machines restores that can restore up to 2 virtual disks in
parallel per virtual machine at a time and assign 2 sessions per virtual machine.
Task
Set a maximum of 2 simultaneous virtual machine restores for machines vm1 and vm2:

dsmc restore vm1,vm2 -VMMAXRESTOREPARALLELVms=2

VMMAXRESTORESessions=10 -VMMAXRESTOREPARALLELDisks=1

This will assign 2 simultaneous virtual machines restores with at least one disk per virtual machine at
a time and 5 sessions per virtual machine.
Task
Set a maximum of 2 simultaneous virtual machine restores for machines vm1, vm2, vm3, and vm4:

dsmc restore vm1,vm2,vm3,vm4 -VMMAXRESTOREPARALLELVms=2

VMMAXRESTORESessions=16 -VMMAXRESTOREPARALLELDisks=2

This will assign 2 simultaneous virtual machines restores with 2 disks per virtual machines at a time
and 8 sessions per virtual machine.
Related reference
“Restore VM” on page 681
Use the restore vm command to restore a virtual machine (VM) that was previously backed up.
“Vmmaxrestoresessions” on page 559
The vmmaxrestoresessions option defines the aggregate number of sessions which will be allocated
for the IBM Spectrum Protect server optimized restore operation.
“Vmmaxrestoreparalleldisks” on page 560

562 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 The vmmaxrestoreparalleldisks option enables an IBM Spectrum Protect client to restore specific
multiple virtual disks at the same time per virtual machine.

Vmmaxvirtualdisks
The vmmaxvirtualdisks option specifies the maximum size of VMware virtual machine disks (VMDK) to
include in a backup operation. The vmmaxvirtualdisks option specifies the maximum size of virtual
machine disks to include in a backup operation.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.
Use the vmmaxvirtualdisks option with the vmskipmaxvirtualdisks option to specify how the
data mover processes large virtual machine (VM) disks during a backup operation:
• Set the vmmaxvirtualdisks option to specify the maximum size of the VM disks to include.
• Set the vmskipmaxvirtualdisks option to back up the VM disks that do not exceed the maximum
size (and exclude any VM disks that exceed the size), or fail the operation.

Supported clients
This option is valid for 64-bit Linux clients that are configured as data movers that back up VMware virtual
machines.

Options file
Set the vmmaxvirtualdisks option in the client system options file (dsm.sys). You can also specify
this option as a command-line parameter on the backup vm command.

Syntax
2

VMMAXVIRTUALDisks size

2...8, 999

Parameters
size
Specifies the maximum size, in terabytes (TB), of the VM disks to include in a backup operation. The
range is an integer 2 - 8; the default is 2. The maximum is 8 TB (equivalent to 8192 GB).
To ensure that the VM disk size that is included in backup operations is always the maximum size,
specify 999. Use this value as the most effective method to ensure that the maximum value is always
set. This value prevents the need to continuously modify the option files.
When you also specify the vmskipmaxvirtualdisks yes option, VM disks that are the specified
maximum size or smaller are backed up and VM disks that are larger than the specified maximum size
are excluded.
When you also specify the vmskipmaxvirtualdisks no option, backup operations fail if a VM disk
is larger than the specified maximum size.

Examples
Options file:
vmmaxvirtualdisks 3
Command line:
Back up VM disks that are 5 TB or smaller and exclude VM disks that are larger than 5 TB:

backup vm VM1 -vmmaxvirtualdisks=5 -vmskipmaxvirtualdisks=yes

Chapter 10. Processing options 563

 Back up VM disks that are 3 TB or smaller and fail the backup operation if a VM disk is larger than 3
TB:

backup vm VM1 -vmmaxvirtualdisks=3 -vmskipmaxvirtualdisks=no

Back up VM disks that are 8 TB or smaller and exclude VM disks that are larger than 8 TB:

backup vm VM1 -vmmaxvirtualdisks=8 -vmskipmaxvirtualdisks=yes

Or:

backup vm VM1 -vmmaxvirtualdisks=999 -vmskipmaxvirtualdisks=yes

Vmmc
Use the vmmc option to store virtual machine backups by using a management class other than the
default management class. For VMware VM backups, the vmmc option is valid only if the
vmbackuptype=fullvm option is set.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.

Supported Clients
This option is valid for clients that are configured to back up VMware virtual machines. The server can also
define this option.

Options File
Place this option in the client options file dsm.opt, in the client system options file dsm.sys, or on the
command line.

Syntax
VMMC management_class_name

Parameters
management_class_name
Specifies a management class that applies to the backed up virtual machine data. If you do not set
this option, the default management class of the node is used.

Examples
Task:
Run a backup of the virtual machine that is named myVirtualMachine and save the backup
according to the management class that is named myManagmentClass.
dsmc backup vm "myVirtualMachine" -vmmc=myManagmentClass

Vmnocbtcontinue
Use the vmnocbtcontinue option to specify whether to back up a virtual machine (VM) without using
the change block tracking function when one or more snapshots already exist on the VM and change block
tracking must be enabled or reset.
If you run an incremental-forever backup on a VM and change block tracking needs to be enabled or re-
enabled, and one or more snapshots exist on the VM, change block tracking cannot be enabled. VMware
does not support enabling change block tracking when a snapshot exists for the VM.
Ensure that you remove any existing snapshots before you run an incremental-forever backup for the first
time so that change block tracking can be enabled. To proceed with the backup operation without

564 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 enabling change block tracking, the vmnocbtcontinue yes option can be specified. However, running a
backup operation with this option setting will cause each backup of the VM to be a full backup, which will
include both used and unused blocks for each disk of the VM. After the backup operation is completed,
when no snapshots exist on the VM, change block tracking is enabled and an incremental-forever backup
is taken.
If you want to reset change block tracking for a VM or group of VMs, use the include.vmresetcbt
vmname option. For more information, see “Include.vmresetcbt” on page 414.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Supported Clients

Options file
Place this option in the client options file (dsm.opt).

Syntax
No
VMNOCBTcontinue
Yes

Parameters
No
Fail the backup operation because change block tracking cannot be enabled. This value is the default.
Yes
Continue the backup operation without using change block tracking.
Specifying this value causes each backup of the VM to be a full backup that includes both used and
unused blocks for each disk of the VM.

Vmnoprdmdisks
This option enables the client to restore configuration information for the pRDM volumes that are
associated with a VMware virtual machine, even if the LUNs that were associated with the volumes cannot
be found. Because pRDM volumes are not included in virtual machine snapshot, only the configuration
information can be restored, and not the data that was on the volumes.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.
This option does not apply to backups of Microsoft Hyper-V virtual machines.

Supported Clients
This option is valid for Windows and Linux clients that are installed on a vStorage backup server.

Options File
Place this option in the client options file (dsm.opt), in the client system options file (dsm.sys), or
specify it as a command-line parameter on the restore vm command.

Chapter 10. Processing options 565

 Syntax
NO
VMNOPRDmdisks
YES

Parameters
YES
Specify this value if you must restore a virtual machine that you backed up with -
vmprocesswithprdm=yes, and the original LUNs that were mapped by the raw device mappings file
cannot be located. This setting causes the client to skip attempts to locate the missing LUNs used by
the pRDM volumes, and restore the configuration information (disk labels) that were associated with
them. The pRDM volumes are restored as thin-provisioned VMFS VMDKs. You can then use the
vSphere client to create the necessary pRDM mappings.
NO
Setting -vmnoprdmdisk=no causes restore operations for virtual machines that were backed up with
-processvmwithprdm=yes to fail if the original LUNs that were mapped to by the raw device
mappings file cannot be located. This value is the default value.

Examples
Option file:

VMNOPRDMDISKS YES

Command line:

dsmc restore vm vm123 -vmnoprdmdisks=yes

Vmnovrdmdisks
This option enables the client to restore configuration information and data for vRDM volumes that are
associated with a VMware virtual machine, even if the LUNs that were associated with the volumes cannot
be found.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.
This option does not apply to backups of Microsoft Hyper-V virtual machines.

Supported Clients
This option is valid for Windows and Linux clients that are installed on a vStorage backup server.

Options File
Place this option in the client options file (dsm.opt), in the client system options file (dsm.sys), or
specify it as a command-line parameter on the restore vm command.

Syntax
NO
VMNOVRDmdisks
YES

566 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Parameters
YES
Specify this value if you must restore a virtual machine that you backed up, and the original LUNs that
were mapped by the raw device mappings file cannot be located. This setting causes the client to skip
attempts to locate the missing LUNs used by the vRDM volumes, and restore the configuration
information (disk labels) and the data that was backed up. The vRDM volumes are restored as thin-
provisioned VMFS VMDKs.
NO
Setting -vmnovrdmdisk=no causes restore operations for virtual machines that had vRDM volume to
fail, if the original LUNs that were mapped to by the raw device mappings file cannot be located. This
value is the default value.

Examples
Option file:

VMNOVRDMDISKS YES

Command line:

dsmc restore vm vm123 -vmnovrdmdisks=yes

Vmpreferdagpassive
The vmpreferdagpassive option specifies whether to back up an active copy or passive copy of a
database that is part of a Microsoft Exchange Server Database Availability Group (DAG).
This option applies to Microsoft Exchange Server workloads that run inside virtual machine guests that
are protected by IBM Spectrum Protect for Virtual Environments.
Use the vmpreferdagpassive option with the backup vm command.

Supported Clients
This option is valid on clients that act as a data mover for VMware guest backups.

Options File
Place this option in the client system-options file (dsm.sys) within a server stanza.

Syntax
No
VMPREFERDAGPassive
Yes

Parameters
No
Back up the Microsoft Exchange Server database in a DAG regardless of whether it is an active copy or
passive copy. This value is the default.
Yes
Skip the backup for an active database copy in a DAG if a valid passive copy is available on another
server. If no valid passive copy is available, the active database copy is backed up.

Examples
Options file:
vmpreferdagpassive yes

Chapter 10. Processing options 567

Vmprocessvmwithindependent
Use this option to specify whether VMware virtual machines (VMs) that are provisioned with one or more
independent disks are backed up. By default, VMs with independent disks are not backed up.
Independent disks cannot be backed up because they do not support snapshots. Therefore, review the
following considerations before setting the vmprocessvmswithindependent option to yes:
• Only normal disk volumes are backed up. The data on independent disks is not backed up.
• Configuration information for independent disks is not backed up. Independent disks must be manually
recreated on a restored machine.
• If a volume is striped across both normal and independent disks, then only the portions of the volume
data on the normal disks can be restored. Therefore, after the VM is restored, the volume is corrupted
because the stripes on the independent disks are missing.
• File level restore is supported for VMs that have normal and independent disks if no volume is striped
across both normal and independent disks. Only files on the normal disks can be restored.
• File level restore is not supported for VMs that have one or more volumes striped across both normal
and independent disks. Use full VM restore for such VMs.
If the virtual machine contains one or more raw device mapping (RDM) volumes that are provisioned in
physical compatibility mode (pRDM), use the vmprocessvmwithprdm option to specify whether the
client backs up the virtual machine if a pRDM disk is present.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.
This option is only valid for VMware backups and does not pertain to Microsoft Hyper-V backups.

Supported Clients
This option is valid for Windows and Linux clients that are configured as a VMware backup data mover.
The server can also define this option.

Options File
Place this option in the client options file (dsm.opt), in the client system options file (dsm.sys), or on the
command-line.

Syntax
No
VMPROCESSVMWITHINDependent
Yes

Parameters
No
The backup of the VM fails if one or more independent disk volumes are detected. No is the default.
Yes
The backup of the VM continues if one or more independent disk volumes are detected. Review the
preceding considerations before using Yes.

Examples
Option file:

VMPROCESSVMWITHINDEPENDENT Yes

Command line:

568 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 dsmc backup vm vmlocal -vmbackuptype=fullvm -vmprocessvmwithindependent=yes

Vmprocessvmwithprdm
Use this option to control whether full VMware virtual machine backups are processed if the virtual
machine has one or more raw device mapping (RDM) volumes provisioned in physical-compatibility mode
(pRDM).
pRDM volumes do not support snapshots. Any pRDM volumes found on a virtual machine are not
processed as part of the backup operation. When the virtual machine is restored, the backup-archive
client recovers the virtual machine, and only the volumes that participated in snapshot operations are
restored. Configuration information and content of the pRDM volumes is not preserved in the information
stored on the IBM Spectrum Protect server. Users must re-create the pRDM volumes on the restored
machine.
This option does not apply to virtual machines that have one or more RDM volumes that are provisioned in
virtual-compatibility mode (vRDM). Because vRDM volumes do support snapshot operations, they are
included in a full VMware virtual machine backup.
If the virtual machine also contains one or more independent disks, use the
vmprocessvmwithindependent option to control whether the client backs up any files on the virtual
machine if an independent disk is present.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.
This option is only valid for VMware backups and does not pertain to Microsoft Hyper-V backups.

Supported Clients
This option is valid for Windows and Linux clients that are configured as a VMware backup server. The
server can also define this option.

Options File
Place this option in the client options file (dsm.opt), in the client system options file (dsm.sys), or on the
command line.

Syntax
NO
VMPROCESSVMWITHPRDM
YES

Parameters
No
The backup of the virtual machine fails if one or more pRDM volumes are detected. No is the default.
Yes
Virtual machines that contain one or more raw device mapping (RDM) volumes that are provisioned in
physical-compatibility mode (pRDM) are backed up. However, the pRDM volumes are not processed
as part of the virtual machine backup operation.
If the virtual machine also contains one or more independent disks, the
vmprocessvmwithindependentdisk option must also be specified.

Examples
Option file:

Chapter 10. Processing options 569

 VMPROCESSVMWITHPRDM Yes

Command line:

dsmc backup vm vmlocal -vmbackuptype=fullvm -vmprocessvmwithprdm=yes

Vmskipctlcompression
Use the vmskipctlcompression option for VM backups to specify whether control files (*.ctl) are
compressed during VM backup. The option does not affect the compression of data files (*.dat)
You can compress virtual machine control files and data files only when the files are stored in a storage
pool that is enabled for client-side deduplication. Use the following options configuration to compress
data files and not compress control files:

compression yes
vmskipctlcompression yes

You must direct the data files to a storage pool that is enabled for client-side deduplication. You can
direct the control files to a storage pool that is not enabled for client-side deduplication
You must be licensed to use IBM Spectrum Protect for Virtual Environments to use this option.

Supported Clients

Options file
Place this option in the client options file (dsm.opt), or on the command line.

Syntax
Yes
VMSKIPCTLCOMPRESSION
No

Parameters
Yes
Do not compress control files (*.ctl) during VM backup. The option does not affect compression of
data files (*.dat).
No
Control files (*.ctl) can be compressed during VM backup. Whether control files are compressed
depends on the value of the compression option.

Vmskipmaxvirtualdisks
The vmskipmaxvirtualdisks option specifies how backup operations process virtual machine (VM)
disks that exceed the maximum disk size.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.
Use the vmskipmaxvirtualdisks option with the vmmaxvirtualdisks option to specify how the
data mover processes large VM disks during a backup operation:
• Set the vmskipmaxvirtualdisks option to back up the VM disks that do not exceed the maximum
size (and exclude any VM disks that exceed the size), or fail the operation.
• Set the vmmaxvirtualdisks option to specify the maximum size of the VM disks to include.

570 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 In Data Protection for VMware V7.1.3 and earlier, the vmskipmaxvirtualdisks option was named
vmskipmaxvmdks. In V7.1.4 and later, vmskipmaxvirtualdisks is the preferred option name.
However, the client still processes backup operations with the vmskipmaxvmdks name.

Supported clients
This option is valid for 64-bit Linux clients that are configured as data movers that back up VMware virtual
machines.

Options file
Set the vmskipmaxvirtualdisks option in the client system options file (dsm.sys). You can also
specify this option as a command-line parameter on the backup vm command.

Syntax
No
VMSKIPMAXVIRTUALDISKS
Yes

Parameters
No
Specifies that backup operations fail if a virtual machine has one or more VM disks that are larger than
the maximum size. This setting is the default value.
Yes
Specifies that backup operations include VM disks that are the maximum size (or smaller) and exclude
any VM disks that are larger than the maximum size.

Examples
Options file:
vmskipmaxvirtualdisks yes
Command line:
Fail a backup operation if a VM disk is larger than 2 TB:

backup vm VM1 -vmskipmaxvirtualdisks=no

Fail a backup operation if a VM disk is larger than 5 TB:

backup vm VM1 -vmskipmaxvirtualdisks=no -vmmaxvirtualdisks=5

Back up VM disks that are 8 TB or smaller and exclude VM disks that are larger than 8 TB:

backup vm VM1 -vmskipvirtualdisks=yes -vmmaxvirtualdisks=8

Vmskipmaxvmdks
The vmskipmaxvmdks option specifies how the backup operation processes VMware virtual machine
disks (VMDKs) that exceed the maximum disk size.
In V7.1.4 and later, vmskipmaxvmdks is renamed vmskipmaxvirtualdisks. Although
vmskipmaxvirtualdisks is the preferred name, the client still processes backup operations with the
vmskipmaxvmdks name.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Chapter 10. Processing options 571

Vmtagdatamover
Use the vmtagdatamover option to enable tagging support in the backup-archive client (data mover).
When this option is enabled, the client manages backups of virtual machines in VMware inventory objects
according to the data protection tags that are set by the IBM Spectrum Protect vSphere Client plug-in of
the vSphere Web Client, or set with tools such as VMware vSphere PowerCLI Version 5.5 R2 or later.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.
For more information about data protection tags, see "Data protection tagging overview" .
The data mover processes data protection tags when the vmtagdatamover option is set to yes. Ensure
that the following requirements are met.
Requirements:
• For the data mover:
– VMware vCenter Server must be at Version 6.0 Update 1 or later.
– Extra permissions are required for the account that is used for backup or restore operations. These
new vCenter permissions are required to perform category and tagging operations. Ensure that the
following user permissions are set on the root vCenter Server:

Inventory Service > vSphere Tagging > Assign or Unassign vSphere Tag
Inventory Service > vSphere Tagging > Create vSphere Tag
Inventory Service > vSphere Tagging > Create vSphere Tag Category
Inventory Service > vSphere Tagging > Delete vSphere Tag
Inventory Service > vSphere Tagging > Delete vSphere Tag Category
Inventory Service > vSphere Tagging > Modify UsedBy Field For Tag
Inventory Service > vSphere Tagging > Modify UsedBy Field For Category
Inventory Service > vSphere Tagging > Edit vSphere Tag
Inventory Service > vSphere Tagging > Edit vSphere Tag Category

For more information about setting vCenter permissions for backup and restore operations, see
technote 7047438.
• In order for the Data Protection for VMware vSphere GUI to function correctly with tagging support,
ensure that the following requirements are met during the installation of the GUI:
– At least one data mover and the Data Protection for VMware vSphere GUI must be installed on the
same server. This data mover node must be configured so that the vCenter server credentials are
saved. You can save the credentials by running the configuration wizard to save the data mover node
password, or by using the dsmc set password command in the data mover command line.
If you use other data movers, running on virtual machines or physical machines as additional data
movers, you can install them on other servers. For tagging support, all these data movers must also
be configured with the vmtagdatamover=yes option. These additional data movers do not require
the Data Protection for VMware vSphere GUI to be installed on the same server in order for them to
work correctly as tag-based data movers.
– For Linux data movers, ensure that you specify the data mover installation directory and the Java™
shared library libjvm.so in the LD_LIBRARY_PATH environment variable. The path to libjvm.so
is used for tagging support when you enable the vmtagdatamover option on the data mover. For
instructions, see "Setting up the data mover nodes in a vSphere environment".
– On Linux operating systems, the Data Protection for VMware vSphere GUI must be installed by using
the default user name (tdpvmware).
– On Linux data mover nodes, the default password file (/etc/adsm/TSM.sth) must be used.

Supported clients
This option can be used with supported x86_64 Linux clients.

572 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Options file
You can specify this option in the client system-options file (dsm.sys) or on the command line for the
backup vm command. You can also include this option on the IBM Spectrum Protect server in a client
option set. You cannot set this option in the Preferences Editor.

Syntax
No
VMTAGDATamover
Yes

Parameters
No
The client ignores any data protection settings or tags that are attributed to the VMware asset. This
value is the default.
Yes
The client manages backups based on the data protection settings in the IBM Spectrum Protect
vSphere Client plug-in or based on the tag values that are attributed to the VMware asset.
When tagging support is enabled, some client options might be affected by the data protection
settings. For information about which options are affected, see "Supported data protection tags".
The following examples show how client options can be affected by data protection tags:
• When you use data protection settings or tags to control which VMware virtual machines are backed
up, the tag values might overlap the domain.vmfull client option setting. While the
domain.vmfull option defines what virtual machines the client protects, the Excluded and
Included tags override what is defined by the domain.vmfull option.
For example, the following options file statement specifies what is backed up during full virtual
machine backup operations:

DOMAIN.VMFULL VMHOSTCLUSTER=cluster01,cluster02;VM=Dept20*

If you use data protection settings or tags to exclude virtual machine Dept204, the Dept204 virtual
machine is not backed up.
• The retention policy setting in the IBM Spectrum Protect vSphere Client plug-in or the tag setting for
the Management Class (IBM Spectrum Protect) category overrides the include.vm and
vmmc client options, but does not override the vmctlmc option.
Tip: If you want to set up a data mover as the default data mover, use the Vmtagdefaultdatamover
option.

Examples
Options file:
vmtagdat yes
Command line:
-vmtagdat=yes
Related concepts
“Data protection tagging overview” on page 712
To manage data protection of virtual machines, you can assign IBM Spectrum Protect tags to VMware
inventory objects. You can assign tags to VMware objects by specifying data protection settings in the
IBM Spectrum Protect vSphere Client plug-in of the vSphere Web Client. If you do not use the IBM
Spectrum Protect vSphere Client plug-in, you can assign tags by using scripting tools such as VMware
Power CLI.

Chapter 10. Processing options 573

 Related reference
“Supported data protection tags” on page 713
IBM Spectrum Protect data protection tags can be assigned to VMware inventory objects to control how
virtual machine backups are managed.
“Vmtagdefaultdatamover” on page 574
Use the vmtagdefaultdatamover option to protect virtual machines, defined in a schedule, that do not
have an assigned or inherited Data Mover category and tag.
“Domain.vmfull” on page 355
The domain.vmfull option specifies the virtual machines (VMs) to include in your full virtual machine
image backup operations.
“Include.vm” on page 410
For virtual machine operations, this option overrides the management class that is specified on the vmmc
option.
“Vmmc” on page 564
Use the vmmc option to store virtual machine backups by using a management class other than the
default management class. For VMware VM backups, the vmmc option is valid only if the
vmbackuptype=fullvm option is set.
“Vmctlmc” on page 547
This option specifies the management class to use when backing up virtual machine control files.
“Set Vmtags” on page 711
The set vmtags command creates data protection tags and categories that can be added to VMware
inventory objects. You can manage IBM Spectrum Protect backups of virtual machines in these VMware
objects by specifying the tags with tools such as VMware vSphere PowerCLI Version 5.5 R2 or later.
Related information
Enabling tagging support

Vmtagdefaultdatamover
Use the vmtagdefaultdatamover option to protect virtual machines, defined in a schedule, that do not
have an assigned or inherited Data Mover category and tag.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.
When you specify a data mover node with the vmtagdefaultdatamover option and the
vmtagdatamover yes option, the data mover backs up any new virtual machines that are added to any
container in the datacenter, if the container is already in a protection set. A protection set consists of the
virtual machines in a container that is assigned the Schedule (IBM Spectrum Protect) category
and tag. The default data mover also backs up any virtual machines in the protection set that are not
assigned the Data Mover tag.
When more than one data mover is associated with a schedule, define one data mover as the default data
mover with the vmtagdefaultdatamover option. If only one data mover is associated with a schedule,
assign that data mover as the default.
Tip: For each schedule, specify only one data mover in its associated data mover list as the default.
Otherwise, any new virtual machines and virtual machines that are not assigned the Data Mover tag will
be backed up more than once.
Data protection tags can be assigned to the vSphere inventory to manage the protection of virtual
machines. For the list of supported categories and tags, see "Supported data protection tags".

Supported clients
This option can be used with supported x86_64 Linux data movers.

574 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Options file
You can specify this option in the client system-options file (dsm.sys) or on the command line for the
backup vm command. You can also include this option on the IBM Spectrum Protect server in a client
option set. You cannot set this option in the Preferences Editor.

Syntax
No
VMTAGDEFAULTdatamover
Yes

dm_name

Parameters
No
The local data mover does not function as a default data mover. Virtual machines that are not
assigned the Data Mover tag are not protected by this data mover. This value is the default.
Yes
Specifies that the local data mover (the data mover where you are specifying this option) functions as
the default data mover.
You must also enable the data mover for tagging support by specifying the vmtagdatamover yes
option.
dm_name
The name of the data mover that you want to use as the default data mover. This option is necessary
only if you want to set this option in the options file for the default data mover. This option is ignored
for any data mover that is not the default data mover.
It is possible to pass this option down to all data movers on the server schedule command or to
include it all data mover option files. Only the default data mover uses this option. Therefore, define
only one default data mover.
You must also specify the vmtagdatamover yes option in the options file on the data mover that
you want to designate as the default data mover.

Example
Your Windows Data Protection for VMware configuration uses two data movers, VC1_DC1_DM1 and
VC1_DC1_DM2. To designate data mover VC1_DC1_DM1 as the default data mover, complete the
following steps:
1. In the options file for data mover VC1_DC1_DM1 (dsm.VC1_DC1_DM1.opt), add the following
statements:

vmtagdatamover yes
vmtagdefaultdatamover yes

or

vmtagdatamover yes
vmtagdefaultdatamover VC1_DC1_DM1

2. In the options file for data mover VC1_DC1_DM2 (dsm.VC1_DC1_DM2.opt), add the following
statements:

vmtagdatamover yes
vmtagdefaultdatamover VC1_DC1_DM1

Chapter 10. Processing options 575

 The vmtagdefaultdatamover option can also be passed to a schedule definition or command to assign
the default data mover. If the default data mover is defined in the schedule definition, all data movers
that are associated with the schedule will be able to identify the default data mover for the protection set.
For example: dsmc backup vm -vmtagdefaultdatamover=VC1_DC1_DM1
Related reference
“Domain.vmfull” on page 355
The domain.vmfull option specifies the virtual machines (VMs) to include in your full virtual machine
image backup operations.
“Vmtagdatamover” on page 572
Use the vmtagdatamover option to enable tagging support in the backup-archive client (data mover).
When this option is enabled, the client manages backups of virtual machines in VMware inventory objects
according to the data protection tags that are set by the IBM Spectrum Protect vSphere Client plug-in of
the vSphere Web Client, or set with tools such as VMware vSphere PowerCLI Version 5.5 R2 or later.
“Set Vmtags” on page 711
The set vmtags command creates data protection tags and categories that can be added to VMware
inventory objects. You can manage IBM Spectrum Protect backups of virtual machines in these VMware
objects by specifying the tags with tools such as VMware vSphere PowerCLI Version 5.5 R2 or later.
Related information
Enabling tagging support

Vmverifyifaction
Use this option to specify the action to perform if the data mover detects integrity problems with the
latest CTL and bitmap files for a virtual machine.
This option affects backup processing for a VM guest only when all of the following conditions are true:
• The previous backup operation for the VM guest was an incremental-forever-incremental backup
(mode=ifincremental)
• The current backup operation for the VM guest is an incremental-forever-incremental backup
• The data mover detected an integrity problem with the CTL and bitmap data from the previous
incremental-forever-incremental backup operation
• The vmverifyiflatest option is set to yes
If all of these conditions are not true for a virtual machine, the backup occurs as it normally would; the
action that is specified by this option is not initiated.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Supported clients
This option is valid for Linux clients that act as a data mover for VMware guest backups.

Options file
Set this option in the client options file (dsm.opt) or the client system options file (dsm.sys).
This option can also be included in a client options set, as a parameter on a backup vm command, or on
the options parameter in a schedule definition.

576 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Syntax
FAILbackup
VMVERIFYIFAction
FORCEfull

PREview

Parameters
FAILbackup
This action fails the backup operation. The following messages are written to the data mover error log
file (dsmerror.log):
ANS9921E Virtual machine disk, vm_name (disk_label),
verification check failed (xxx/yyy).
The xxx/yyy in the message indicate the size of the bitmap (xxx) and CTL files (yyy).
ANS9919E Failed to find the expected control files for vm_name

Perform a full VM backup (set -mode=IFFull for the affected virtual machines at a time of your
choosing. An alternative is to use the -vmverifyifaction=forcefull on the next scheduled
incremental-forever-incremental operation to force a full backup of those VMs, if you determine that
your scheduled backup window can contain the full VM backups for these VMs. This value is the
default action value.
FORCEfull
This action changes the backup mode from -mode=ifincremental to -mode=iffull; the current
backup becomes a full VM backup. The full VM backup is initiated for you. The following messages are
written to the data mover error log file (dsmerror.log):
ANS9921E Virtual machine disk, vm_name (disk_label),
verification check failed (xxx/yyy)
The xxx/yyy in the message indicate the size of the bitmap (xxx) and CTL files (yyy).
ANS9919E Failed to find the expected control files for vm_name

ANS9922I VMVERIFYIFlatest is enabled for vm_name (action: FORCEFULL).

ANS9920W Forcing a full vm backup for vm_name

Use this option if your current backup window can contain a full VM backup of the affected virtual
machines.
PREview
This action does not perform any backups. Instead, the CTL and bitmap data for each VM guest that is
processed by the backup vm command is restored to a temporary location, where it is checked for
integrity. If the integrity check fails, the following messages are written to the data mover error log file
(dsmerror.log):
ANS9921E Virtual machine disk, vm_name (disk_label),
verification check failed (xxx/yyy)
The xxx/yyy in the message indicate the size of the bitmap (xxx) and CTL files (yyy).
ANS9919E Failed to find the expected control files for vm_name
ANS9922I VMVERIFYIFlatest is enabled for vm_name (action: PREVIEW)

Use this option to validate the integrity of the incremental-forever-incremental backups (-

mode=ifincremental) that you previously created for one or more a virtual machines.
If the messages indicate that some VMs failed the integrity checks, start a full VM backup (-
mode=iffull) at a time of your choosing. Alternatively, set -vmverifyifaction=forcefull on
the next scheduled incremental-forever-incremental operation to force a full backup of those VMs.
The backup window must be large enough to accommodate one or more full VM backups.

Chapter 10. Processing options 577

Vmverifyiflatest
This option applies only to VMware virtual machine (VM) backup operations that use the incremental-
forever-incremental backup mode (that is, a backup vm command with -mode=IFIncremental
specified). If this vmverifyiflatest option is enabled, the data mover runs an integrity check on the
CTL and bitmap files that were created on the server during the last backup, if the last backup was an
incremental-forever-incremental backup.
If the files pass the integrity tests, the virtual machine is restorable. The current backup proceeds and
adds another snapshot to the chain of snapshots for the virtual machine.
If the files fail the integrity tests, the virtual machine is not restorable. The data mover then performs
another action, which you specified on the vmverifyifaction option. You can set vmverifyifaction
to create a full VM backup immediately, or you can fail the backup completely, and run a full VM backup at
another time. A third parameter can be set to just verify the CTL and bitmap files for a virtual machine,
without creating a new backup snapshot.
Verification can be performed only if the previous backup operation for the VM used mode=IFIncr, and if
the current backup operation also uses mode=IFIncr. This option has no effect on the other virtual
machine backup modes.
Important:
If this option is set to no, VM backup processing continues without any verification tests. The processing
resources that are involved in performing the integrity checks is negligible. To ensure the continued
integrity of your incremental-forever-incremental backup chain, set or use the default value
(vmverifyiflatest yes). Do not set this option to no, unless you are directed to do so, by IBM
support.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.

Supported clients
This option is valid for Linux clients that act as a data mover for VMware guest backups.

Options file
Set this option in the client options file (dsm.opt) or the client system options file (dsm.sys).
This option can also be included in a client options set, as a parameter on a backup vm command, or on
the options parameter in a schedule definition.

Syntax
YES
VMVERIFYIFlatest
NO

Parameters
YES
This setting specifies that validation of the CTL and the bitmap data is performed for each VM that is
processed by the current incremental-forever-incremental (mode=IFIncr) backup operation, if the
previous backup operation for that VM was also an incremental-forever-incremental backup. This
value is the default value.
NO
This setting specifies that validation of CTL and bitmap data does not occur during incremental-
forever-incremental backup processing. Do not set this value unless directed to do so by IBM support.

578 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Examples
Options file:
vmverifyiflatest yes
Command line:
dsmc backup vm vm1 -mode=ifincremental –vmverifyiflatest=yes

Vmvstorcompr
The vmvstorcompr option controls the use of compression by IBM Spectrum Protect client during
backup and restore operations.
Use this option to increase transport performance by using the NBD (Network Block Device) protocol.
Three types of compression are available: ZLIB, FASTLZ, and SKIPZ. To use compression, you must set
the transport option to NBDSSL with the Vmvstortransport option.
NBDSSL compression is available with vSphere 6.5 and above.

Supported clients
This option can be used with supported x86_64 Linux 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.

Options file
This option is valid in the client system options file (dsm.sys), or on the command line for Backup VM. It
can also be included on the server in a client option set. It cannot be set in the Preferences Editor.

Syntax
VMVSTORCOMPR
ZLIB

FASTLZ

SKIPZ

Parameters
ZLIB
Sets the type of compression to ZLIB with NBDSSL transport.
FASTLZ
Sets the type of compression to FASTLZ with NBDSSL transport.
SKIPZ
Sets the type of compression to SKIPZ with NBDSSL transport.

Examples
Command line:
To set the type of compression and transport mode for VM backup and restore operations with
NBDSSL transport, issue the following command:

dsmc backup vm myVM -VMVSTORCOMPR=SKIPZ -VMVSTORTRANSPORT=NBDSSL

This example backs up the VM myVM using the SKIPZ compression protocol with the required
transport setting of NBDSSL.

Chapter 10. Processing options 579

 Options file:

VMVSTORCOMPR SKIPZ

Related reference
“Backup VM” on page 608
“Vmvstortransport” on page 580
The vmvstortransport option specifies the preferred transports order (hierarchy) to use when backing
up or restoring VMware virtual machines. If you do not include a given transport using this option, that
transport is excluded and is not used to transfer data.

Vmvstortransport
The vmvstortransport option specifies the preferred transports order (hierarchy) to use when backing
up or restoring VMware virtual machines. If you do not include a given transport using this option, that
transport is excluded and is not used to transfer data.
The transport order that you specify determines how the VMware API for Data Protection (VADP)
accesses virtual disk data, but it does not influence the data path that is used between the backup-
archive client and the IBM Spectrum Protect server. Valid transports include any order or combination of
the following options:
nbd
Network based data transfer. Access virtual disk data using the LAN. This transport path is generally
available in all configurations.
nbdssl
Same as nbd, but the data is encrypted before being sent over the LAN. Encryption can decrease
performance.
san
Storage Area Network transfer: Access virtual disk data using the SAN.
hotadd
If you use the backup-archive client in a virtual machine, the hotadd transport allows the transport of
backed up data to dynamically added storage.
Separate each transport option from the others with a colon, for example, san:nbd:nbdssl:hotadd.
If you do not specify a transport hierarchy, the default transport selection order is
san:hotadd:nbdssl:nbd.
The first transport that is available is used to transfer the data. If you want to prevent data transport over
a particular path, do not include it in the transport list. For example, if it is important to not disrupt LAN
traffic, omit the nbd transports from the hierarchy.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.
Set this option in dsm.sys.

Supported clients
This option is valid for Linux clients that are configured to back up or restore virtual machine files using
VADP.

580 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Syntax
,

VMVSTORTransport ---
NBD

NBDSSL

SAN

HOTADD

Examples
If the SAN is available, do not transport backups or restores over the LAN
VMVSTORTRANSPORT san
The backup-archive client is running in a virtual machine, but do not use the hotadd transport
VMVSTORTRANSPORT nbdssl:nbd
Use the LAN transport, even if nbdssl is available, to obtain better performance
VMVSTORTRANSPORT nbd
The SAN transport is preferred, but use nbd when the SAN is not available, and do not use nbdssl or
hotadd
VMVSTORTRANSPORT san:nbd
Related reference
“Vmvstorcompr” on page 579
The vmvstorcompr option controls the use of compression by IBM Spectrum Protect client during
backup and restore operations.

Vmtimeout
VMTIMEOut specifies the maximum time, in seconds, to wait before abandoning a backup vm operation,
when the INCLUDE.VMTSMVSS option is used to provide application protection. To use this option, the
IBM Spectrum Protect for Virtual Environments license must be installed.
Each backup vm operation that is performed on a virtual machine that is protected by a
INCLUDE.VMTSMVSS option is subject to a timer. The timer value determines how many seconds the
client should wait for the application to quiesce activity and truncate its logs so the backup can be
performed. The default time out value is sufficient for most environments. However, if your application
data cannot be backed up because the application needs additional time to prepare for the snapshot, you
can increase the time out value. This timer applies only to backup vm operations when the
INCLUDE.VMTSMVSS option is set for a virtual machine.

Supported clients
This option can be used with supported x86_64 Linux clients.

Options file
Place this option in the client options file. It cannot be set on the command line or in the Preferences
editor.

Syntax
180
VMTIMEout
time_out

Chapter 10. Processing options 581

 Parameters
time_out
Specifies the time to allow, in seconds, for backup operations to complete when a virtual machine is
protected by the application protection option, INCLUDE.VMTSMVSS. The value specified must be an
integer between 180 and 500. The default is 180 seconds.

Examples
Options file
VMTIMEout 500
Command line
Not applicable; this option cannot be set on the command line.
Related reference
“INCLUDE.VMTSMVSS” on page 418
The INCLUDE.VMTSMVSS option notifies virtual machine applications that a backup is about to occur.
This option allows the application to truncate transaction logs and commit transactions so that the
application can resume from a consistent state when the backup completes. An optional parameter can
be specified to suppress truncation of the transaction logs.

Webports
The webports option enables the use of the web client outside a firewall.
The webports option enables the use of the web client outside a firewall by specifying the TCP/IP port
number used by the IBM Spectrum Protect client acceptor service and web client agent service for
communications with the web client.
Values for both the client acceptor and the web client agent service are required.
If you do not specify this option, the default value, zero (0), is used for both ports. This causes TCP/IP to
randomly assign a free port number for the client acceptor and the web client agent service.

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 dsm.sys file within a server stanza. To set this option in the Client Preferences
editor, click Edit > Client Preferences > Web Client , and specify the ports in the Web Agent Port and
Web Client Acceptor Port fields.

Syntax
WEBPorts cadport agentport

Parameters
cadport
Specifies the required client acceptor port number. The range of values is 1000 through 32767. If a
value is not specified, the default, zero (0), causes TCP/IP to randomly assign a free port number.
agentport
Specifies the required web client agent service port number. The range of values is 1000 through
32767. If a value is not specified, the default, zero (0), causes TCP/IP to randomly assign a free port
number.

582 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Examples
Options file:
webports 2123 2124
Command line:
Does not apply.

Wildcardsareliteral
The wildcardsareliteral option specifies whether question marks (?) and asterisks (*) are
interpreted literally, when they are included in a file list specification on a filelist option.
Ordinarily, the client does not accept wildcard characters (?) and (*) in a file list specification that is
included on a filelist option. Some file systems, such as the IBM Spectrum Scale (formerly GPFS) file
system, allow single and double quotation marks in file and directory names. To prevent errors that would
otherwise occur, when file specifications are included on a filelist option and they contain wildcard
characters, set wildcardsareliteral yes. When wildcardsareliteral is set to yes, question
marks (?) and asterisks (*) that are included in a file list specification on the filelist option are
interpreted literally, and not as wildcard characters.
This option applies to any command that accepts a filelist option as command parameter.

Supported Clients
This option is valid for all supported UNIX and Linux platforms. The option is applied to any command that
takes a file list specification as a parameter.

Options File
Place this option in the client user options file (dsm.opt).

Syntax
no
WILDCARDSareliteral
yes

Parameters
no
Specifies that question marks and asterisks are interpreted as wildcards when used in a file list
specification that is included on a filelist option. The default section is No. If a file list
specification on a filelist option includes a question mark or asterisk, an error occurs and the file
specification cannot be processed.
yes
Specifies that asterisks and question marks in a file list specification that is included on a filelist
option are interpreted literally, and not as wildcard characters. Specify this value if you are backing up
files from a file system that allows wildcard characters in file or directory names.

Examples
Options file:
WILDCARDSARELITERAL YES
Command line:
Assuming that the file system allows wildcard characters in paths, the following are examples of files
in a file list specification that can be successfully processed if WILDCARDSARELITERAL is set to YES.
Assume that the command issued is dsmc sel -filelist=/home/user1/important_files,
where important_files.txt contains the list of files to process.

Chapter 10. Processing options 583

 important_files.txt contains the following list of files:

/home/user1/myfiles/file?9000
/home/user1/myfiles/?file
/home/user1/myfiles/**README**version2
/home/user1/myfiles/ABC?file*

If both WILDCARDSARELITERAL and QUOTESARELITERAL are set to YES, the following backups can
be successfully processed:

/home/user1/myfiles/"file?
/home/user1/myfiles/?file'
/home/user1/myfiles/**"README Tomorrow"**
/home/user1/myfiles/file*

Related information
For information about the filelist option, see “Filelist” on page 387.
For information about syntax for file specifications, see “Specifying input strings that contain blank
spaces or quotation marks” on page 135.
“Quotesareliteral” on page 465

584 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Chapter 11. Using commands
The backup-archive client provides a command-line interface (CLI) that you can use as an alternative to
the graphical user interface (GUI). This topic describes how to start or end a client command session and
how to enter commands.
The following is a list of tasks related to entering commands.
• “Start and end a client command session” on page 588
• “Enter client command names, options, and parameters” on page 589
• “Wildcard characters” on page 592
The following table provides an alphabetical list of the commands and a brief description.

Table 80. Commands

Command Description
archive “Archive” on page 593 Archives files from a workstation to IBM Spectrum Protect storage.
backup fastback “Backup Backs up volumes specified by the fbpolicyname,
FastBack” on page 597 fbclientname and fbvolumename options for long term
retention.
backup group “Backup Group” on Creates and backs up a group containing a list of files from one or
page 600 more file space origins to a virtual file space on the IBM Spectrum
Protect server.
backup image “Backup Image” Creates an image backup of one or more file systems or logical
on page 602 volumes that you specify.
backup nas “Backup NAS” on Creates an image backup of one or more file systems belonging to
page 606 a Network Attached Storage (NAS) file server.
backup vm “Backup VM” on page Backs up virtual machines specified in the vmlist option.
608
cancel process “Cancel Displays a list of current NAS (if NDMP support is enabled) image
Process” on page 615 backup and restore processes for which the administrative user
has authority.
cancel restore “Cancel Displays a list of restartable restore sessions from which you can
Restore” on page 615 select one to cancel.
delete access “Delete Access” Deletes authorization rules for files that are stored on the server.
on page 616
On those clients that support image backup, this command deletes
authorization rules for images that are stored on the server.

delete archive “Delete Archive” Deletes archived files from IBM Spectrum Protect server storage.
on page 616
delete backup “Delete Backup” Deletes active and inactive backup files from IBM Spectrum
on page 618 Protect server storage.
delete filespace “Delete Deletes file spaces in IBM Spectrum Protect server storage.
Filespace” on page 622
delete group “Delete Group” on Deletes a group backup on the IBM Spectrum Protect server.
page 623

© Copyright IBM Corp. 1993, 2019 585

 Table 80. Commands (continued)
Command Description
expire “Expire” on page 624 Inactivates backup objects that you specify in the file specification
or with the filelist option.
help “Help” on page 626 Displays a Table of Contents of help topics for the command-line
client.
incremental “Incremental” on Backs up all new or changed files or directories in the default client
page 627 domain or from file systems, directories, or files you specify,
unless you exclude them from backup services.

loop “Loop” on page 633 Starts an interactive command session.

macro “Macro” on page 634 Executes commands within a macro file that you specify.
monitor process “Monitor Displays a list of current NAS image backup and restore processes
Process” on page 635 from which you can select one to cancel.
preview archive “Preview Simulates an archive command without sending data to the server.
Archive” on page 635
preview backup “Preview Simulates a backup command without sending data to the server.
Backup” on page 636
query access “Query Access” on Displays a list of current authorization rules.
page 637
query archive “Query Archive” Displays a list of archived files.
on page 638
query backup “Query Backup” on Displays a list of backup versions.
page 640
query backupset “Query Queries a backup set from a local file or the IBM Spectrum Protect
Backupset” on page 643 server. On those clients that support tape devices, this command
can query a backup set from a tape device.
query filespace “Query Displays a list of file spaces in IBM Spectrum Protect storage. You
Filespace” on page 646 can also specify a single file space name to query.
query group “Query Group” on Displays information about group backups and their members.
page 648
query image “Query Image” on Displays information about image backups.
page 650
query inclexcl “Query Inclexcl” Displays a list of include-exclude statements in the order in which
on page 652 they are processed during backup and archive operations.
query mgmtclass “Query Displays information about available management classes.
Mgmtclass” on page 653
query node “Query Node” on Displays all the nodes for which an administrative user ID has
page 654 authority to perform operations.
query options “Query Options” Displays all or part of your options and their current settings.
on page 655
query restore “Query Restore” Displays a list of your restartable restore sessions in the server
on page 656 database.
query schedule “Query Displays information about scheduled events for your node.
Schedule” on page 657

586 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 80. Commands (continued)
Command Description
query session “Query Session” Displays information about your session, including the current
on page 657 node name, when the session was established, server information,
and server connection information.
query systeminfo “Query Gathers IBM Spectrum Protect system information and outputs
Systeminfo” on page 658 this information to a file or the console.
query vm “Query VM” on page Verifies the successful backups of the virtual machines from the
659 vStorage backup server.
restart restore “Restart Displays a list of restartable restore sessions from which you can
Restore” on page 663 one to restart.
restore “Restore” on page 664 Restores copies of backup versions of your files from the IBM
Spectrum Protect server.
restore backupset “Restore Restores a backup set from the IBM Spectrum Protect server or a
Backupset” on page 668 local file. On those clients that support tape devices, this
command can restore a backup set from a tape device.
restore group “Restore Group” Restores specific members or all members of a group backup.
on page 675
restore image “Restore Image” Restores a file system or raw volume image backup.
on page 677
restore nas “Restore NAS” on Restores the image of a file system belonging to a Network
page 679 Attached Storage (NAS) file server.
restore vm “Restore VM” on Restores a full VM backup, and returns the full VM backup files to
page 681 the vmbackdir directory on the vStorage backup server.
retrieve “Retrieve” on page Retrieves copies of archived files from the IBM Spectrum Protect
693 server.
schedule “Schedule” on page Starts the client scheduler on the workstation.
696
selective “Selective” on page Backs up selected files.
698
set access “Set Access” on page Authorizes another user to access your backup versions or
701 archived copies.
On those clients that support image backup, this command can set
authorization rules for images that are stored on the server.

set event “Set Event” on page Allows you to specify the circumstances for when archived data is
703 deleted.
set netappsvm Set Netappsvm Associates the login credentials for a cluster management server
with a NetApp storage virtual machine and the data SVM name
(data Vserver). This command must be entered before you can
create a snapshot difference incremental backup of a clustered
NetApp volume.
set password “Set Password” on Changes the IBM Spectrum Protect password for your workstation.
page 706

For proper operation, the was node must be restored to the same location and under the same name.

Chapter 11. Using commands 587

 Important: To avoid problems, restore your data at the Network Deployment Manager node or
Application Server node level only.
Related reference
“Reading syntax diagrams” on page xxii
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.

Start and end a client command session

You can start or end a client command session in either batch mode or interactive mode.
Use batch mode when you want to enter a single client command. The backup-archive client processes
the command and returns to the command prompt.
Use interactive mode when you want to enter a series of commands. Since the client establishes
connection to the server only once for interactive mode, a series of commands can be processed more
quickly. The client processes the commands and returns to the Protect> prompt.

Process commands in batch mode

Some options are valid only on the initial command line and not in interactive mode. These options
generally affect the operation of the entire session.
For example, the command dsmc query session -errorlogname=myerror.log is accepted and it does
name the error log. However, it is accepted simply because it appears in the initial command, even though
the option is not valid for the query command.
There are also some options that are always valid on the initial command line as well as on individual
commands in interactive mode. Therefore, certain options are accepted on the initial command line even
though they have no effect on the command being entered. For example, dsmc query session -
subdir=yes is a valid command, but in this case the -subdir option has no effect on the command that
was entered.
When you enter a single command in batch mode, precede it with the executable program name, dsmc.
For example, to process the incremental command in batch mode, you would enter:

dsmc incremental

The backup-archive client prompts you each time you enter a command if the passwordaccess option is
set to prompt and authentication on the server is set to On. Type your password and press Enter.
You can also enter your password using the password option with a command, but your password
appears on the screen. For example, if your password is secret, enter:

dsmc incremental –password=secret

If you set the passwordaccess option to generate in your dsm.opt file, you do not need to specify the
password with the command. The client only prompts you for your password if you are registering your
workstation with a server or manually changing your password.
Related concepts
“Processing options” on page 277
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.

Process commands in interactive mode

Use the interactive mode (or loop mode) to enter a series of commands.
Enter dsmc on the command line and press Enter. When the Protect> command prompt appears, type
the command name and press Enter. Do not precede each command with the executable program name,

588 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 dsmc. Alternatively, you can enter dsmc loop on the command line to start a client command session in
interactive mode. Loop is the default command for dsmc.
If a password is required, the backup-archive client prompts you before you enter the first command.
Type your user ID and password and press Enter.
You can also enter your password using the password option with the loop command, but your
password appears on the screen. For example, if your password is secret, enter:

dsmc loop –password=secret

To end an interactive session, enter quit at the prompt.

Note for UNIX and Linux clients:
In loop mode, following a restore operation directly from tape, the mount point is not released in case
additional restore requests are made to that volume. If you request a backup operation in the same
session and that mount point is the only one available, the backup operation will stop with the following
message:

Waiting for mount of offline media

In this case, the mount point is not released until one of the following conditions is met:
• The device class MOUNTRETENTION limit is satisfied.
• The client idletimeout period is satisfied.
• The dsmc loop session is closed after the restore operation completes, allowing you to start a
subsequent loop mode session to perform the backup operation.

Enter client command names, options, and parameters

A client command can include one or more of these components: Command name, options, and
parameters. The topics that follow describe each of these components.

Command name
The first part of a command is the command name. The command name consists of a single word, such as
help or schedule, or an action word and an object for that action, such as query archive.
Enter the full command name, or its minimum abbreviation.
For example, you can enter any of the following versions of the query schedule command:

query schedule
q sc
q sched
query sc

Options
When you enter options with a command, always precede the option with a dash (–). Do not put a space
between the dash and the option name.
Enter more than one option in any order in a command before or after the file specification. Separate
multiple options with a blank space.
There are two groups of options that you can use with commands: Client options (set in your options file),
or client command options (used on the command line).
• Client options: The group of options that are set in your client options file. You can override an option in
the client options file when you enter the option with a command on the command line.
• Client command options: Use a client command option only when you enter the option with a
command on the command line. You cannot set these options in an options file.

Chapter 11. Using commands 589

 Related concepts
“Client options reference” on page 306
The following sections contain detailed information about each of the IBM Spectrum Protect processing
options.

Options in interactive mode

In interactive mode, options that you enter on the initial command line override the value that you
specified in your options file.
This value remains in effect for the entire interactive session unless overridden by a different value on a
given interactive command.
For example, if you set the subdir option to yes in your dsm.opt or dsm.sys file, and you specify
subdir=no on the initial command line, the subdir=no setting remains in effect for the entire interactive
session unless overridden by the subdir=yes value on a given interactive command. However, the
subdir=yes value specified within the interactive session only affects the command on which it is
entered. When that command completes, the value reverts back to subdir=no, the value at the
beginning of the interactive session.

Parameters
Commands can have required parameters, optional parameters, or no parameters at all.
Required parameters provide information to perform a task. The most commonly required parameter is a
file specification.
For example, if you want to archive a file named budget.fin from the project directory, you would
enter the following:

dsmc archive /project/budget.fin

Some commands have optional parameters. If you do not enter a value for an optional parameter, the
backup-archvie client uses the default value. For example, the restore command includes a required
parameter, sourcefilespec, that specifies the path and file name in storage that you want to restore.
The optional parameter, destinationfilespec, specifies the path where you want to place the
restored files. If you do not specify the destinationfilespec, by default, the client restores the files
to the original source path. If you want to restore the files to a different directory, enter a value for
destinationfilespec.
Example: Restore the file /project/budget.fin to the new path /newproj/newbudg.fin

dsmc restore /project/budget.fin /newproj/

Enter parameters in the order indicated in the command syntax diagram.

File specification syntax

There are some syntax rules that you need to know about when entering file specification parameters
such as filespec, sourcefilespec, and destinationfilespec.
The following are the syntax rules:
• Do not use wildcards as part of the file space name or anywhere in the destinationfilespec. The
one exception to this rule is the set access command where wildcards are permitted in the two
lowest levels of the file spec.
Example: Allow access to all files in all directories in and subordinate to the /home directory:

set access backup /home/* * *

set access backup /home/*/* * *

With UNIX clients, do not use wildcards in a directory path name, for example:

/home/j*asler/file1.c

590 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
• There is a maximum number of file specifications per command:
– The Query commands can accept only one file specification.
– The restore and retrieve commands can accept a source file specification and a destination file
specification.
– There is a limit of 20 operands on some commands. This limit is to prevent excessive sessions that
are caused when wildcards are expanded by the UNIX shell command processor.
You can prevent shell expansion from causing you to go over the 20-operand limit by placing
quotation marks around your source filespec expansion characters for restore commands.
Note: Using quotation marks has the side affect of causing a no-query restore.
You can use the removeoperandlimit option to specify that the backup-archive client removes the
20-operand limit. If you specify the removeoperandlimit option with the incremental,
selective, archive, or backup image command, the 20-operand limit is not enforced and is
restricted only by available resources or other operating system limits.
• The length of a file specification is limited.
– On AIX, Solaris, and Mac: The maximum number of characters for a file name is 255. The maximum
combined length of the file name and path name is 1024 characters. The Unicode representation of a
character can occupy several bytes, so the maximum number of characters that a file name might
contain can vary.
– On Linux: The maximum length for a file name is 255 bytes. The maximum combined length of both
the file name and path name is 4096 bytes. This length matches the PATH_MAX that is supported by
the operating system. The Unicode representation of a character can occupy several bytes, so the
maximum number of characters that comprises a path and file name can vary. The actual limitation is
the number of bytes in the path and file components, which might correspond to an equal number of
characters.
On Linux: For archive or retrieve operations, the maximum length that you can specify for a path and
file name (combined) remains at 1024 bytes.
• When you enter the sourcefilespec, if the directory name ends with /, then /* is implied.
When you enter a destinationfilespec, if the name ends with /, then it is considered a directory,
otherwise it is considered a file.
The following example illustrates these two rules. Even though mydir and yourdir are directories, the
command will fail because /* is implied after mydir, and yourdir is considered a file.

restore /home/mydir/ /away/yourdir

restore c:\home\mydir\ c:\away\yourdir

• If a file specification does not begin with a directory delimiter, the file specification is assumed to be a
subdirectory of the current working directory. The client appends the file specification to the working
directory to build the complete path.
For example, if the current working directory is /home/me and the command is dsmc res "/fs/
dir1/*" mydir/, the complete restore path is this: /home/me/mydir
• The only command that accepts a simple file space name is the incremental command. The following
example is valid:

dsmc i /Users

The following example is not valid, because the command is the selective command:

dsmc sel /Users

Related reference
“Filelist” on page 387

Chapter 11. Using commands 591

 Use the filelist option to process a list of files.
“Removeoperandlimit” on page 466
The removeoperandlimit option specifies that the client removes the 20-operand limit.

Wildcard characters
Use wildcard characters when you want to specify multiple files with similar names in one command.
Without wildcard characters, you must repeat the command for each file.
In a command, you can use wildcard characters in the file name or file extension only. You cannot use
them to specify destination files, file systems, or server names. You cannot specify a directory whose
name contains an asterisk (*) or a question mark (?).
Valid wildcard characters that you can use include:
*
Asterisk. Matches zero or more characters.
?
Question mark. Matches any single character at the present position.
The following table shows examples of each wildcard.

Table 81. Wildcard characters

Pattern Matches Does not match
Asterisk (*)
ab* ab, abb, abxxx a, b, aa, bb
ab*rs abrs, abtrs, abrsrs ars, aabrs, abrss
ab*ef*rs abefrs, abefghrs abefr, abers
abcd.* abcd.c, abcd.txt abcd, abcdc, abcdtxt
Question Mark (?)
ab? abc ab, abab, abzzz
ab?rs abfrs abrs, abllrs
ab?ef?rs abdefjrs abefrs, abdefrs, abefjrs
ab??rs abcdrs, abzzrs abrs, abjrs, abkkkrs

Important: Use an asterisk (*) instead of a question mark (?) as a wildcard character when trying to
match a pattern on a multibyte code page, to avoid unexpected results.
Note: In batch mode, enclose values containing wildcards in quotation marks. Otherwise, UNIX shells
expand unquoted wildcards, and it is easy to exceed the 20 operand limit. It is more efficient to let the
client process wildcard file specifications because many fewer server interactions are needed to
complete the task. For example:

dsmc selective "/home/me/*.c"

Client commands reference

The following sections contain detailed information about each of the backup-archive client commands.
Information for each command includes the following information:
• A description of the command.

592 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • A syntax diagram of the command.
• Detailed descriptions of the command parameters. If the parameter is a constant (a value that does not
change), the minimum abbreviation appears in uppercase letters.
• Examples of using the command.

Archive
The archive command archives a single file, selected files, or all files in a directory and its
subdirectories on a server.
Archive files that you want to preserve in their current condition. To release storage space on your
workstation, delete files as you archive them using the deletefiles option. Retrieve the archived files
to your workstation whenever you need them again.
Use the snapshotroot option with the archive command along 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. The snapshotroot option
does not provide any facilities to take a volume snapshot, only to manage data that is created by a volume
snapshot.
AIX only: You can enable snapshot-based file archive by using the option snapshotproviderfs=JFS2.

Supported Clients
This command is valid for all clients.

Syntax

Archive filespec
options

Parameters
filespec
Specifies the path and name of the file you want to archive. Use wildcard characters to include a
group of files or to include all files in a directory.
To include multiple file specifications, separate eachfilespec parameter with a space character. If
multiple file specifications are included, and two or more of the specifications have common parent
directories, then it is possible for the common directory objects to be archived more than once. The
conditions under which this behavior occurs are runtime-dependent, but the behavior itself has no
adverse effects.
For example, if the filespec is /home/amr/ice.doc /home/amr/fire.doc, then /home and /
home/amr might be archived twice. The file objects ice.doc, and fire.doc, are archived only once.
If you want to avoid including the shared parent directory more than once, use separate, non-
overlapping archive commands to archive each file specification.
If you archive a file system, include a trailing slash (/home/).
There is a limit of 20 operands. This limit prevents excessive sessions that are caused when wildcards
are expanded by the UNIX shell command processor. You can prevent shell expansion from causing
you to go over the 20-operand limit by placing quotation marks around file specifications that contain
wildcards ("home/docs/*").
You can use the removeoperandlimit option to specify that the 20-operand limit is removed. If you
specify the removeoperandlimit option, the 20-operand limit is not enforced and is restricted only

Chapter 11. Using commands 593

 by available resources or other operating system limits. For example, remove the 20 operand limit to
archive 21 file specifications:

selective -removeoperandlimit filespec1 filespec2 ... filespec21

You can use the filelist option, instead of file specifications, to identify which files to include in
this operation. However, these two methods are mutually exclusive. You cannot include file
specification parameters and use the filelist option. If the filelist option is specified, any file
specifications that are included are ignored.

Table 82. Archive command: Related options

Option Where to use
archmc Command line only.
archsymlinkasfile Client user-options file (dsm.opt) or command line.
autofsrename Client options file (dsm.opt) only.
changingretries Client system options file or command line.
compressalways Client user-options file (dsm.opt) or command line.
compression dsm.sys file within a server stanza or command line.
deletefiles Command line only.
description Command line only.
dirsonly Command line only.
encryptiontype dsm.sys file within a server stanza.
encryptkey dsm.sys file within a server stanza.
filelist Command line only.
filesonly Command line only.
preservelastaccessdate Client user-options file (dsm.opt) or command line.
removeoperandlimit Command line only.
snapshotcachesize Client options file (dsm.opt) or include.fs option.
snapshotroot Command line only.
subdir Client options file (dsm.opt) or command line.
tapeprompt Client options file (dsm.opt) or command line.
v2archive Command line only.

Examples
Task
Archive a single file that is named budget in the /home/proj1 directory.
Command: archive /home/proj1/budget
Task
Archive all files in the /home/proj1 directory with a file extension of .txt.
Command: archive "/home/proj1/*.txt"
Task
Archive all files in the directory tree that is headed by the /home directory.
Command: archive -subdir=yes "/home/*"

594 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Task
Assuming that you initiated a snapshot of the /usr file system and mounted the snapshot as /
snapshot/day1, archive the /usr/dir1/sub1 directory tree from the local snapshot and manage it
on the IBM Spectrum Protect server under the file space name /usr.
Command: dsmc archive /usr/dir1/sub1/ -subdir=yes -snapshotroot=/snapshot/
day1
Related concepts
“File system and ACL support” on page 151
Special file systems contain dynamic information that is generated by the operating system; they contain
no data or files. The UNIX and Linux clients ignore special file systems and their contents.
Related reference
“Snapshotproviderfs” on page 503
Use the snapshotproviderfs option to enable snapshot-based file backup and archive operations, and
to specify a snapshot provider.

Archive FastBack
Use the archive fastback command to archive Tivoli Storage Manager FastBack volumes specified by
the fbpolicyname, fbclientname and fbvolumename options for long-term retention.
Before using this command, configure the client to back up and archive Tivoli Storage Manager FastBack
data. Also, before you issue this command, at least one snapshot should exist in the FastBack repository
for the FastBack policy being archived or backed up.
If a policy specification contains both Windows and Linux FastBack clients, only the Linux volumes will be
backed up or archived to the IBM Spectrum Protect server by the Linux backup-archive client.
You can use Tivoli Storage Manager FastBack options to archive the latest snapshots of the following
volumes:
• All clients and volumes associated with a specific FastBack policy or a list of FastBack policies.
• All volumes associated with a specific FastBack client or a list of FastBack clients for a given FastBack
policy.
• A specific volume or volumes associated with a specific FastBack client for a given FastBack policy.

Supported Clients
This option is valid for Linux x86_64 clients.

Chapter 11. Using commands 595

 Syntax
,

ARCHIVE FASTBack FBPolicyname = name FBServer = name

FBClientname = name

FBVolumename = name

FBReposlocation = name FBBranch = name

ARCHMc = name

Important:
1. At least one FBpolicyName is always required.
2. You can specify up to 10 values for FBPolicyName, if no values are specified for both FBClientName
and FBVolumeName.
3. When you specify a FBClientName value, there must be only one value for FBPolicyName.
4. You can specify up to 10 values for FBClientName if only one PolicyName is specified, and no values
for FBVolumeName are specified.
5. When you specify the FBVolumeName option, you can have only one FBPolicy, and only one
FBCLientName specified.
6. You can specify multiple FBVolumeNames if condition 5 is satisfied.
7. You must always specify the FBReposLocation option for Linux.

Parameters

Table 83. Archive FastBack command: Related options

Option Where to use
fbpolicyname Command line and scheduler.
“Fbpolicyname” on page 383
fbserver “Fbserver” on Command line and scheduler.
page 385
fbclientname Command line and scheduler.
“Fbclientname” on page 382
fbvolumename Command line and scheduler.
“Fbvolumename” on page
386
fbreposlocation Command line and scheduler.
“Fbreposlocation” on page
384

596 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 83. Archive FastBack command: Related options (continued)
Option Where to use
fbbranch “Fbbranch” on Command line and scheduler.
page 381
archmc “Archmc” on page Command line and scheduler.
308

Examples
Command line:
The backup-archive client is installed on a Linux proxy client machine. Use this command to archive
all FastBack volumes for all Linux FastBack clients that are defined for FastBack policy1:

dsmc archive fastback -fbpolicyname=Policy1

-fbserver=myfbserver -fbreposlocation=myfbserver@WORKGROUP

The FastBack server name, -myFbDrHub is the short host name of the FastBack Disaster Recovery
Hub server where the repository is located.
The -fbreposlocation parameter specifies the location of the repository. The repository location is
required. If you do not provide the repository location, the command fails.
FBServer should point to the short host name of the FastBack DR hub in this case.
Command line:
The repository, rep_server1, is located on the FastBack DR hub, myFbDrHub.

dsmc archive fastback -fbpolicyname="Policy 1"

-fbserver=myFbDrHub -fbreposlocation=\\myFbDrHub\rep_server1

The repository location is required. If you do not provide the repository location, the command fails.
The FastBack server name, -myFbDrHub, is the short host name of the FastBack Disaster Recovery
Hub where the repository is located.
FBServer should point to the short host name of the FastBack DR hub in this case.
Command line:
Archive all volumes protected by FastBack policy named policy1 from the FastBack server named
basil:

dsmc archive fastback -Fbpolicyname=policy1

-FBServer=basil -ARCHMC="my_tsm_mgmt_class"
-fbreposlocation=basil@WORKGROUP

Related concepts
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.

Backup FastBack
Use the backup fastback command to back up Tivoli Storage Manager FastBack volumes specified by
the fbpolicyname, fbclientname and fbvolumename options for long-term retention.
Before using this command, configure the client to back up and archive Tivoli Storage Manager FastBack
data. Also, before you issue this command, at least one snapshot should exist in the Tivoli Storage
Manager FastBack repository for the Tivoli Storage Manager FastBack policy being archived or backed up.
If a policy specification contains both Windows and Linux FastBack clients, only the Linux volumes will be
backed up or archived to the IBM Spectrum Protect server by the Linux backup-archive client.

Chapter 11. Using commands 597

 Tivoli Storage Manager FastBack options are supported for the incremental backup of the latest
snapshots, depending on the option specified:
• All clients and volumes associated with the FastBack policy or a list of FastBack policies.
• All volumes associated with a specific FastBack client or a list of FastBack clients for a given FastBack
policy.
• A specific volume or volumes associated with a specific FastBack client for a given FastBack policy.

Supported Clients
This command is valid for Linux x86_64 clients that are configured as Tivoli Storage Manager FastBack
dedicated proxies.

Syntax
,

BACKUP FASTBack FBPolicyname = name FBServer = name

FBClientname = name

FBReposlocation = name
,

FBVolumename = name

FBBranch = name BACKMc = name

Important:
1. At least one FBpolicyName is always required.
2. You can specify up to 10 values for FBPolicyName, if no values are specified for both FBClientName
and FBVolumeName.
3. When you specify a FBClientName value, there must be only one value for FBPolicyName.
4. You can specify up to 10 values for FBClientName if only one PolicyName is specified, and no values
for FBVolumeName are specified.
5. When you specify the FBVolumeName option, you can have only one FBPolicy, and only one
FBCLientName specified.
6. You can specify multiple FBVolumeNames if condition 5 is satisfied.
7. You must specify the FBReposLocation option.

Table 84. Backup FastBack command: Related options

Option Where to use
fbpolicyname Command line and scheduler.
“Fbpolicyname” on page 383
fbserver “Fbserver” on Command line and scheduler.
page 385
fbclientname Command line and scheduler.
“Fbclientname” on page 382

598 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 84. Backup FastBack command: Related options (continued)
Option Where to use
fbvolumename Command line and scheduler.
“Fbvolumename” on page
386
fbreposlocation Command line and scheduler.
“Fbreposlocation” on page
384
fbbranch “Fbbranch” on Command line and scheduler.
page 381
backmc “Backmc” on page Command line and scheduler.
317

Examples
Command line:
The backup-archive client is installed on a Linux proxy client machine. Use this command to back up
all FastBack volumes for all Linux FastBack clients that are defined for FastBack policy1:

dsmc backup fastback -fbpolicyname=Policy1

-fbserver=myfbserver
-fbreposlocation=myfbserver@WORKGROUP

The repository location is required. If you do not provide the repository location, the command will
fail.
The FastBack server name, -myfbserver, is the short host name of the FastBack server where the
repository is located.
Command line:
The repository, rep_server1, is located on the FastBack Disaster Recovery Hub, myFbDrHub

dsmc backup fastback -fbpolicyname="Policy 1"

-fbserver=myFbDrHub -fbreposlocation=\\myFbDrHub\rep_server1

The FastBack server name, -myFbDrHub, is the short host name of the FastBack Disaster Recovery
Hub server where the repository is located.
The -fbreposlocation option specifies the location of the repository. The repository location is
required. If you do not provide the repository location, the command fails.
The FBServer option should point to the short host name of the FastBack DR hub in this case.
Command line:
Back up all volumes protected by FastBack policy named policy1 from the FastBack server named
basil:

dsmc backup fastback -Fbpolicyname=policy1

-FBServer=basil -BACKMC="my_tsm_mgmt_class"
-fbreposlocation=basil@WORKGROUP

Related concepts
Configuring the client to back up and archive Tivoli Storage Manager FastBack data

Chapter 11. Using commands 599

 Before you can back up or archive Tivoli Storage Manager FastBack client data, you must complete
configuration tasks.

Backup Group
Use the backup group command to create and back up a group containing a list of files from one or
more file space origins to a virtual file space on the IBM Spectrum Protect server.
AIX only: You can enable snapshot-based group backup by using the option
snapshotproviderfs=JFS2.
A group backup allows you to create a consistent point-in-time backup of a group of files that is managed
as a single logical entity. Objects in the group are subject to the following processing rules:
• Management class rebinding for grouped objects:
– During full backups, all objects in a backup group are assigned to the same management class.
– During differential backups, if a new management class is specified on an include statement for an
existing backup group, the following behavior occurs:
- Any new and changed objects in the backup group are bound to the new management class.
- Any member objects of the group that are not changed appear as though they have not been bound
to the new management class. These unchanged objects are not included in the Total number of
objects rebound statistics that are displayed when the Backup Group command completes.
- The unchanged objects are reassigned to a newly created backup group, and the new backup group
is bound to the new management class. However, the original management class name is still
displayed for the unchanged group objects.
Even though the original management class name is still displayed for the unchanged objects, they
are effectively bound to the new management class of the backup group.
• Existing exclude statements for any files in the group are ignored.
• All objects in the group are exported together.
• 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.
• If you are performing full and differential group backups to a sequential device, during a restore the
data is in no more than two locations. To optimize restore time, perform periodic full backups to back up
the data to one location on the sequential media.
• During a full group backup, all objects in the filelist are sent to the server. During a differential group
backup, only data that has changed since the last full backup is sent to the server. Objects in the filelist
that have not changed since the last full backups are assigned as members of the differential group
backup. This data is not resent to the server, reducing backup time.
The backup group command requires the following options:
filelist
Specifies a list of files to add to a new group.
groupname
Specifies the fully qualified name of the group containing a list of files.
virtualfsname
Specifies the name of the virtual file space for the group on which you want to perform the operation.
The virtualfsname option cannot be the same as an existing file space name.
mode
Specifies whether you want to back up all of the files in the filelist or only files that have changed
since the last full backup.
Note:

600 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
1. If any file in the group backup fails, the entire group backup fails.
2. Use the query group command to query members of a group backup on the IBM Spectrum Protect
server.
3. Use the restore group command to restore specific members or all members of a group backup on
the server.
4. Unless you are running Mac OS X, use the delete group command to delete a specific group backup
from the server.
5. Use the query filespace command to display virtual file space names for your node that are stored
on the server.
6. A group backup can be added to a backup set.

Supported Clients
This command is valid for all UNIX and Linux clients except Mac OS X.

Syntax
Backup GRoup options

Parameters

Table 85. Backup Group command: Related options

Option Where to use
filelist “Filelist” on page Command line only.
387
groupname “Groupname” on Command line only.
page 396
mode “Mode” on page 435 Command line only.
snapshotproviderfs System-options file (dsm.sys) within a server stanza or with the
“Snapshotproviderfs” on include.fs option.
page 503
virtualfsname Command line only.
“Virtualfsname” on page 539

Examples
Task
Perform a full backup of all the files in the /home/dir1/filelist1 file to the virtual file space name
accounting containing the group leader /home/group1 file.
Command:

backup group -filelist=/home/dir1/filelist1 -groupname=group1

-virtualfsname=/virtfs -mode=full

Related information
“Include options” on page 403
“Query Group” on page 648
“Restore Group” on page 675
“Delete Group” on page 623
“Query Filespace” on page 646

Chapter 11. Using commands 601

Backup Image
The backup image command creates an image backup of one or more volumes on your system.
You can use the backup image command to back up NTFS or ReFS, or unformatted RAW volumes. If a
volume is NTFS-formatted, only those blocks that are used by the file system are backed up. On ReFS
volumes, all blocks are backed up.
If you set the imagegapsize option to 0, all blocks, including unused blocks at the end of the volume,
are backed up.
If you specify an AIX JFS2 file system for image backup, only those blocks that are used by the file
system are backed up. If you set the imagegapsize option to zero, all blocks, including blocks at the end
of the volume, are backed up.
Note:
1. AIX only: By default, snapshot-based image backup is enabled for JFS2 volumes. To turn off snapshot-
based image backups, set -snapshotproviderimage=NONE on this command.
2. For the Linux clients, image backup is only supported on partitions with id 0x83 or logical volumes that
are created with the Linux Logical Volume Manager. Backing up other partitions, such as extended
partitions that contain mounted file systems or database data, can produce inconsistent backup data if
the data changes during the image backup operation.
3. For the Linux client, image backup of DASD devices with raw-track access mode on Linux on z Systems
is not supported.
4. Backup image is not supported on any GPFS file system.
5. The IBM Spectrum Protect API must be installed to use the backup image command.
6. When you change the attribute of a JFS2 file system to an HSM-managed file system, an image backup
is not done for that file system.
7. The image backup operation is not supported on any partition that resides on a multipath device.
Important: The last incremental backup time refers to the server time and the file modification time
refers to the client time. If the client and server time are not synchronized, or the client and server are in
different time zones, this affects incremental-by-date backup and image backup where
mode=incremental.
The client backs up the files that have modification dates and times (on the client) that are later than the
date and time of the last incremental backup of the file system on which the file is stored (on the server).
If the server time is ahead of the client time, incremental-by-date backups, or image backup with
mode=incremental, skip the files, which had been created or modified after the last incremental or
image backup with a modification date earlier than the last incremental backup time stamp.
If the client time is ahead of the server time, all files that had been created or modified before the last
incremental or image backup and have a modification time stamp later than the last incremental backup
time stamp, are backed up again. Typically, these files would not get backed up because they had already
been backed up.
The backup date can be checked by the query filespace command.
The backup-archive client must support the raw device type on the specific platform to perform an image
backup of a raw device. You can perform an image backup only on local devices. Clustered devices or file
systems as well as devices or file systems that are shared between two or more systems are not
supported. If you want to perform an image backup for a file system that is mounted on a raw device, the
raw device must be supported.
Use the include.image option to include a file system or logical volume for image backup, or to specify
volume-specific options for image backup.
The backup image command uses the compression option.

602 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Supported Clients
This option is valid for AIX, Linux, and Oracle Solaris clients.

Syntax

Backup Image
options filespec

Parameters
filespec
Specifies the name of one or more logical volumes. If you want to back up more than one file system,
separate their names with spaces. Do not use pattern matching characters. If you do not specify a
volume name, the logical volumes that are specified with the domain.image option are processed. If
you do not use the domain.image option to specify file systems to process, an error message is
displayed and no image backup occurs.
Specify the file space over which the logical volume is mounted or the logical volume name. If there is
a file system that is configured in the system for a given volume, you cannot back up the volume with
the device name.
For example, if the /dev/lv01 file space is mounted on the /home volume, you can issue backup
image /home, but backup image /dev/lv01 fails with an error:
ANS1063E Invalid path specified

There is a limit of 20 operands. This limit prevents excessive sessions that are caused when wildcards
are expanded by the UNIX shell command processor. You can prevent shell expansion from causing
you to go over the 20-operand limit by placing quotation marks around file specifications that contain
wildcards ("home/docs/*").
You can use the removeoperandlimit option to specify that the 20-operand limit is removed. If you
specify the removeoperandlimit option, the 20-operand limit is not enforced and is restricted only
by available resources or other operating system limits. For example, remove the 20 operand limit to
backup 21 file specifications:
backup image -removeoperandlimit filespec1 filespec2 ... filespec21

Note: For Sun systems, specify either a file system name or a raw device name (block device type).

Table 86. Backup Image command: Related options

Option Where to use
asnodename “Asnodename” Client system options file (dsm.sys) or command line.
on page 309
compressalways Client system options file (dsm.sys) or command line.
“Compressalways” on page
325
compression Client options file or command line.
“Compression” on page 326
dynamicimage Use with the backup image command or the include.image option
“Dynamicimage” on page in the options file.
362
imagegapsize Use with the backup image command, the include.image option, or
“Imagegapsize” on page 400 in the options file.
mode “Mode” on page 435 Command line only.

Chapter 11. Using commands 603

 Table 86. Backup Image command: Related options (continued)
Option Where to use
postsnapshotcmd Use with the backup image command, the include.image option, or
“Postsnapshotcmd” on page in the options file.
455
presnapshotcmd Use with the backup image command, the include.image option, or
“Presnapshotcmd” on page in the options file.
461
removeoperandlimit Command line only.
snapshotcachesize Use with the backup image command, the include.image option, or
“Snapshotcachesize” on in the options file.
page 502
snapshotproviderimage Client options file or with include.image option.
“Snapshotproviderimage” on
page 504

Examples
Task
Back up the /home/test file space over which the logical volume is mounted and perform an image
incremental backup that backs up only new and changed files after the last full image backup.

dsmc backup image /home/test -mode=incremental

Task
Perform a static image backup of the logical volume that is mounted at the /home directory.
dsmc backup image /home -snapshotproviderimage=none
Task
Perform a dynamic image backup of the logical volume that is mounted at the /home directory.
Command: dsmc backup image /home -dynamicimage=yes
Task
Perform a snapshot image backup of the /home directory.

AIX client: dsmc backup image /home

-snapshotproviderimage=JFS2
LINUX client: dsmc backup image /home
-snapshotproviderimage=LINUX_LVM

Task
Back up the /dev/lv01 raw logical volume.
dsmc backup image /dev/lv01
Related information
“Imagegapsize” on page 400
“Snapshotproviderimage” on page 504
“Snapshotcachesize” on page 502
“Mode” on page 435
“Comparing methods 1 and 2” on page 183 To decide which method is appropriate for your environment.

604 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Static, dynamic, and snapshot image backup
The traditional image backup prevents write access to the volume by other system applications during the
operation.
Use the dynamicimage option to back up the volume as is without remounting it read-only. Corruption of
the backup can occur if applications write to the volume while the backup is in progress. In this case, run
fsck after a restore.
The dynamicimage option is not supported for JFS2 volumes.
For Linux x86_64 clients only: By default, the backup-archive client runs a snapshot image backup of file
systems residing on a logical volume created by the Linux Logical Volume Manager during which the
volume is available to other system applications. Snapshot image backup requires a Version 5.1 IBM
Spectrum Protect server.
For AIX clients only: By default, backup-archive client runs a snapshot image backup of JFS2 volumes
during which the volume is available to other system applications. AIX allows the creation of a snapshot
of a JFS2 volume while it is still online. The snapshot is created inside the same volume group as the
source volume. You must ensure that the volume group provides enough free disk space to create the
snapshot. The snapshot contains the old data blocks while the modified data is stored in the source
volume. Use the snapshotcachesize option with the backup image command, in the dsm.sys file, or
with the include.image option to specify an appropriate snapshot size so that all old data blocks can
be stored while the image backup occurs.
The Linux Logical Volume Manager allows the creation of a snapshot of a logical volume while the logical
volume itself is still online. The snapshot is created inside the same volume group as the source logical
volume. You must ensure that the volume group provides enough free disk space to create the snapshot.
The snapshot contains the old data blocks while the modified data is stored in the source logical volume.
Use the snapshotcachesize option with the backup image command, in the dsm.sys file, or with the
include.image option to specify an appropriate snapshot size so that all old data blocks can be stored
while the image backup occurs. A snapshot size of 100 percent will ensure a valid snapshot.

Utilizing image backup to perform file system incremental backup

There are two methods of utilizing image backups to perform efficient incremental backups of your file
system. These backup methods allow you to perform 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 either use
image backup with file system incremental or you can use image backup with image incremental mode to
perform image backups of volumes with mounted file systems.
The following are some examples of using image backup with file system incremental.
• To perform a full incremental backup of the file system: dsmc incremental /myfilesystem
• To perform an image backup of the same file system: dsmc backup image /myfilesystem
• To periodically perform incremental backups: dsmc incremental /myfilesystem
You must follow the next steps in the order shown to ensure that the server records additions and
deletions accurately.
Use this command to restore the file system to its exact state as of the last incremental backup: dsmc
restore image /myfilesystem -incremental -deletefiles.
During the restore, the client does the following:
• Restores the most recent image on the server.
• 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.
• Restores new and changed files from the incremental backups.
If you do not follow the steps exactly, two things can occur:

Chapter 11. Using commands 605

 1. After the original image is restored, all files backed up with the incremental command are restored
individually.
2. If you perform a backup image before performing an incremental, files deleted from the original
image are not deleted from the final restored file system.
The following are some examples of using image backup with image incremental mode.
• To perform an image backup of the same file system: dsmc backup image /myfilesystem
• To perform an incremental image backup of the file system: dsmc backup image /myfilesystem
-mode=incremental
This sends only those files that were added or changed since the last image backup to the server.
• To periodically perform full image backups: dsmc backup image /myfilesystem
• To restore the image: dsmc restore image /myfilesystem -incremental
On restore, the backup-archive client ignores the deletefiles option when the image+image
incremental technique of backing up has been used. The restore will include files that were deleted
after the last full image backup plus the latest versions of files added or changed after the last image
backup.
Note: You should perform full image backups periodically in the following cases. This will improve restore
time because fewer changes are applied from incrementals.
• When a file system changes substantially (more than 40%).
• Once each month.
• As appropriate for your environment.
The following restrictions apply when using the image backup with image incremental mode:
• The file system can have no previous full incremental backups produced by the incremental
command.
• Incremental-by-date image backup does not inactivate files on the server; therefore, when files are
restored, none can be deleted.
• If this is the first image backup for the file system, a full image backup is performed.
• Using mode=incremental backs up only files with a changed date, not files with changed permissions.
• If file systems are running at or near capacity, an out-of-space condition could result during the restore.

Backup NAS
The backup nas command creates an image backup of one or more file systems that belong to a
Network Attached Storage (NAS) file server, otherwise known as NDMP Backup. You are prompted for the
IBM Spectrum Protect administrator ID.
The NAS file server performs the outboard data movement. A server process starts in order to perform the
backup.
Use the nasnodename option to specify the node name for the NAS file server. The NAS node name
identifies the NAS file server to the IBM Spectrum Protect server; the NAS node name must be registered
at the server. Place the nasnodename option in your client options file (dsm.opt). The value in the client
options file is the default, but can be overridden on the command line.
Use the toc option with the backup nas command or the include.fs.nas option to specify whether
the IBM Spectrum Protect server 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 IBM Spectrum Protect 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. TOC creation

606 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
requires more 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, if you know the fully qualified name of each file or
directory and the image in which that object was backed up.
The toc option is only supported for images that are backed up by Version 5.2 or later client and server.
Specifying mode =differential on the BACKUP NODE server command or the backup nas command
where no full image exists, shows that a full backup was started. Using the QUERY PROCESS server
command shows that a full backup is in process.
Use the mode option to specify whether to perform a full or differential NAS image backup. A full image
backup backs up the entire file system. The default is a differential NAS image backup on files that change
after the last full image backup. If an eligible full image backup does not exist, a full image backup is
performed. If a full image exists, whether it is restorable, or expired and being maintained because of
dependent differential images, specifying mode =differential sends a differential image backup. If a full
image is sent during a differential backup, it is reflected as a full image using the QUERY NASBACKUP
server command. The QUERY NASBACKUP server command also displays NAS images that are restorable
and displays full image or differential image as the object type.
Use the monitor option to specify whether you want to monitor a NAS file system image backup and
display processing information on your screen.
Use the monitor process command to display a list of all processes for which an administrative user
ID has authority. 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.
Use the cancel process command to stop NAS backup processing.
Regardless of client platform, NAS file system specifications use the forward slash (/) separator, as in this
example: /vol/vol0.

Supported Clients
This command is valid for AIX, and Solaris clients only.

Syntax

Backup NAS filespec

options

Parameters
filespec
Specifies the name of one or more file systems on the NAS file server. If you do not specify this
parameter, the backup-archive client processes all of the file systems that are defined by the
domain.nas option.
If you do not specify the filespec or the domain.nas option, the default all-nas value is used for
domain.nas and all file systems on the NAS file server are backed up.

Table 87. Backup NAS command: Related options

Option Where to use
mode “Mode” on page 435 Command line only.
monitor “Monitor” on page Command line only.
438

Chapter 11. Using commands 607

 Table 87. Backup NAS command: Related options (continued)
Option Where to use
nasnodename Client options file (dsm.sys) or command line.
“Nasnodename” on page 440
toc “Toc” on page 531 Command line or with the include.fs.nas option in your client
options file (dsm.sys).

Examples
Task
Perform the NAS image backup of the entire file system.
Command: backup nas -mode=full -nasnodename=nas1 /vol/vol0 /vol/vol2
Task
Perform the NAS image backup of the entire file server.
Command: backup nas -nasnodename=nas1
Task
Perform the NAS image backup of the entire file system and save Table of Contents (TOC) information
for the file system backup.
Command: backup nas -mode=full -nasnodename=netappsj /vol/vol0 -toc=yes
Related information
“Nasnodename” on page 440
“Toc” on page 531
“Mode” on page 435
“Monitor” on page 438
“Cancel Process” on page 615
“Domain.nas” on page 354

Backup VM
Use the backup vm command to start a full backup of a virtual machine.

Backing up VMware virtual machines

Use the backup vm command to back up VMware virtual machines.
One or more virtual machines are backed up by the IBM Spectrum Protect data mover node. Data mover
node is the name that is given to a configuration where the backup-archive client runs on a vStorage
backup server and is configured to protect the virtual machines in a Virtual Center or ESX/ESXi server. You
must configure the VMware virtual machine before you use this command. For information about
configuring the VMware virtual machine, see “Preparing the environment for full backups of VMware
virtual machines” on page 199.
A full VM backup stores a backup copy of all virtual disk images and configuration information for a virtual
machine. Full VM backups enable a complete restore of a virtual machine, but they take more time and
more server space than an incremental backup.
If you set vmenabletemplatebackups option to yes, a backup vm operation includes the template
VMs, but only if the vStorage backup server is connected to a vCenter Server, and not to an ESX or ESXi
host.

608 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
If a snapshot fails during backup processing, the client attempts to back up the VMware virtual machine
one more time. To control the number of total snapshot attempts, set the
INCLUDE.VMSNAPSHOTATTEMPTS option in the client options file.
Data protection tags are used to configure the backup policy of virtual machines in VMware objects. The
tags and categories are created when you use one of the following methods:
• Enable tagging support on the data mover node with the vmtagdatamover option and run the backup
vm command.
• Use the IBM Spectrum Protect vSphere Client plug-in to manage IBM Spectrum Protect backups.
• Run the set vmtags command on any data mover node.
When the vmtagdatamover option is set to yes, all tags that are assigned to a virtual machine are backed
up during backup vm operations. The tags are restored when the restore vm command is run. Tags
that are assigned to other inventory objects are not backed up and cannot be restored.
For more information about data protection tags, see “Data protection tagging overview” on page 712.
A Full VM backup uses VMware Changed Block Tracking (CBT) to create content-aware (used-block only)
backups. The client enables changed block tracking (CBT) on an ESX or ESXi server when a backup
begins. VMware CBT requires an ESX 4.1 (or later) host, with virtual hardware 7 (or later). You cannot
perform incremental or full VM content-aware backups on virtual machines that do not support CBT.
When CBT is enabled, it tracks disk changes when I/O operations are processed by the ESX or ESXi server
storage stack on the following disks:
• A virtual disk that is stored on VMFS; the disk can be an iSCSI disk, a local disk, or a disk that is on a
SAN.
• A virtual disk that is stored on NFS.
• An RDM that is in virtual compatibility mode.
When I/O operations are not processed by the ESX or ESXi storage stack, changed block tracking cannot
be used to track disk changes. The following disks cannot use CBT:
• An RDM that is in physical compatibility mode.
• A disk that is accessed directly from inside a VM. For example, vSphere cannot track changes that are
made to an iSCSI LUN that is accessed by an iSCSI initiator in the virtual machine.
Complete information about changed block tracking requirements is described in the VMware Virtual Disk
API Programming Guide in the VMware product documentation. In the guide, search for "Low Level
Backup Procedures" and read the "Changed Block Tracking on Virtual Disks" section.
For VMware servers that do not support CBT, both the used and the unused areas of the disk are backed
up and an informational message is logged in the dsmerror.log file. Use the -preview option on the
backup vm command to view the current CBT status. CBT status has three values:
Off
Indicates the CBT configuration parameter (ctkEnabled) is not enabled in the virtual machine's
configuration parameters. Off is the default state.
Not Supported
Indicates that the virtual machine does not support CBT. Changed-block only backups are not
possible.
On
Indicates the virtual machine supports CBT and that CBT is enabled in the virtual machine's
configuration parameters (ctkEnabled=true).
The client turns on CBT (it sets ctkEnable=true) with each backup attempt. After the client turns
on CBT, it remains on, even if the virtual machine is deleted from the IBM Spectrum Protect server.
With CBT enabled, after the first full VM backup is performed, only the changed blocks on the disk are
backed up or restored.
If you are no longer performing IBM Spectrum Protect backups of a virtual machine, you can turn off
CBT. To turn off CBT, right-click the virtual machine that you want to turn off CBT for in the vSphere

Chapter 11. Using commands 609

 client. Click Edit Settings > Options > General > Configuration Parameters. Then, set the
ctkEnabled configuration parameter to false.
Tip: You can use the compression option with backups only if the backup is being saved to a storage pool
that was enabled for client-side deduplication.
You specify the -vmbackuptype and -mode options to indicate how the backups are to be performed.
For full VM backups, use -vmbackuptype=fullvm, and specify any of the following mode options:
IFFull
Incremental-forever-full mode. In this mode, a snapshot of all used blocks on a virtual machine’s
disks are backed up to the server. You must be licensed to use IBM Spectrum Protect for Virtual
Environments: Data Protection for VMware, or IBM Spectrum Protect for Virtual Environments: Data
Protection for Microsoft Hyper-V to use this option.
IFIncremental
Incremental-forever-incremental. In this mode, a snapshot is created of the blocks that changed
since the last backup. You must be licensed to use IBM Spectrum Protect for Virtual Environments:
Data Protection for VMware, or IBM Spectrum Protect for Virtual Environments: Data Protection for
Microsoft Hyper-V to use this option.
For information about the incremental-forever backup strategy, see Backup and restore types.

Supported Clients
This command is valid only on supported Linux clients that are installed on a vStorage backup server that
protects VMware virtual machines.

Syntax
,

vmname
Backup VM
,

vmname :vmdk= disk_label

-VMBACKUPUPDATEGUID -PREView options

Parameters
vmname
Specify the name of one or more virtual machines that you want to back up. The name is the virtual
machine display name. Separate multiple virtual machine names with commas. If you set the
vmenabletemplatebackups option to yes, vmname can specify the name of a template VM to back
up.
VMware vCenter allows for two or more virtual machines to have the same display name. However,
the backup-archive client requires that all virtual machine names in a vCenter server configuration be
unique. To prevent errors during processing, ensure that all virtual machines have a unique display
name.
Wildcard characters can be used in virtual machine names that are specified as this parameter.
However, wildcard processing differs, depending on which backup mode is used.
• For backups that use mode=iffull or mode=ifincremental, wildcards can be used to match VM
name patterns. For example:
– backup vm VM_TEST* includes all virtual machines that have names that begin with VM_TEST

610 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 – backup vm VM?? includes any virtual machine that has a name that begins with the letters
"VM", followed by 2 characters
Restriction: Do not use the word "aggregate" as a VM name. The word "aggregate" is reserved for the
VM name field in an IBM Spectrum Protect message. Messages that contain the word "aggregate" as
the VM name show statistics that represent the total value of all VM guests that are backed up per
data mover.
If you do not specify vmname, you can identify the virtual machine with the domain.vmfull option.
:vmdk=disk_label
This keyword is an extension to the vmname. It specifies the label (name) of the virtual machine disk
to include in the backup operation. You can exclude a disk by preceding the keyword with the
exclusion operator (-). For more ways to include or exclude disks from processing, see
Domain.vmfull, Exclude.vmdisk, Include.vmdisk.
-VMBACKUPUPDATEGUID
To use this option, you must have a license agreement to use IBM Spectrum Protect for Virtual
Environments: Data Protection for VMware.
This option updates the globally unique identifier (GUID) for the virtual machine that you are backing
up. This parameter is intended for use only in the following scenario:
You want to restore a previously backed up virtual machine named ORION. But, before you shut down
and replace the copy of ORION that is running in your production environment, you want to verify the
configuration of the restored virtual machine before you use it to replace the existing ORION.
1. You restore the ORION virtual machine and give it a new name: dsmc restore vm Orion -
vmname=Orion2
2. You update and verify the ORION2 virtual machine and determine that it is ready to replace the
existing virtual machine that is named ORION.
3. You power down and delete ORION.
4. You rename ORION2 so that it is now named ORION.
5. The next time that you backup ORION, by using either an incremental-forever full, or incremental-
forever-incremental backup, you add the -VMBACKUPUPDATEGUID parameter to the backup vm
command. This option updates the GUID, on the IBM Spectrum Protect server, so the new GUID is
associated with the stored backups for the ORION virtual machine. The chain of incremental
backups is preserved; there is no need to delete existing backups and replace them with new
backups.
-PREView
This option displays information about a virtual machine, including the labels of the hard disks in the
virtual machine, and the management class information for a virtual machine.
You can use the disk labels with the :vmdk= or :-vmdk= keywords to include or exclude disks from a
backup operation. The following text is sample output from the -preview parameter:

backup vm vm1 -preview

Full BACKUP VM of virtual machines 'VM1'

vmName:vm1
VMDK[1]Label: Hard disk 1
VMDK[1]Name: [ds5k_svt_1] tsmcetlnx14/tsmcetlnx14.vmdk
VMDK[1]Status: Included
VMDK[2]Label: Hard disk 2
VMDK[2]Name: [ds5k_svt_1] tsmcetlnx14/tsmcetlnx14_1.vmdk
VMDK[2]Status: Excluded - user,Independent,pRDM

This example output from -preview shows that VMDK 2 was excluded by the previous backup. Disks
that were included in a backup have a status of Included. Disks that were excluded from the backup
have a status of Excluded, followed by a reason code. The reason codes can be any of the following:
user
Indicates that the disk was skipped because it was excluded on a domain.vmfull statement, on
the command line, or in the client options file.

Chapter 11. Using commands 611

 Independent
Indicates that the disk is an independent disk. Independent disks cannot be part of a snapshot, so
they are excluded from backup vm operations. Ensure that the
vmprocessvmwithindependent option is set to yes or the entire virtual machine is bypassed by
a backup operation if it contains one or more independent disks.
pRDM
Indicates that the disk is a physical Raw Device Mapped (pRDM) disk. pRDM disks cannot be part
of a snapshot, so they are excluded from backup vm operations. Ensure that the
vmprocessvmwithprdm option is set to yes or the entire virtual machine is bypassed by a
backup operation if it contains one or more raw device mapping (RDM) volumes that are
provisioned in physical-compatibility mode (pRDM).
The output from the -preview parameter also shows the management class name that is associated
with the virtual machine, along with information about where the management class was set. This
information can help you verify whether the domain and tag values are set correctly for the
management class. For example:

backup vm -preview
Full BACKUP VM of virtual machines specified in DOMAIN.VMFULL option.

1. vmName: tag_vm_2
DomainKeyword: all-vm
toolsRunningStatus: guestToolsNotRunning
toolsVersionStatus: guestToolsNotInstalled
consolidationNeeded: No
Change Block Tracking: On
managementClassName: STANDARD
managementClassLocation: Node Default

VMDK[1]Label: 'Hard disk 1' (Hard Disk 1)

VMDK[1]Name: '[Raid1-lannds2] tag_vm_2/tag_vm_2.vmdk'
VMDK[1]Status: Included
...

12. vmName: vm-jean

DomainKeyword: all-vm
toolsRunningStatus: guestToolsNotRunning
toolsVersionStatus: guestToolsNotInstalled
consolidationNeeded: No
Change Block Tracking: On
managementClassName: MGMTCLASS1 (invalid)
managementClassLocation: VM Tag Management Class (IBM Spectrum Protect)

VMDK[1]Label: 'Hard disk 1' (Hard Disk 1)

VMDK[1]Name: '[Raid1-lannds2] vm-jean/vm-jean.vmdk'
VMDK[1]Status: Included

where:
managementClassName
Displays the name of the management class that the virtual machine is bound to.
If the "(invalid)" label is shown next to the management class name, either the name was
incorrectly specified, the management class was removed on the IBM Spectrum Protect server, or
no backup copy group was found in the management class on the server. When the management
class name is invalid, the virtual machine backup operation fails.
managementClassLocation
Displays where the management class was set. The following locations are possible:
Node Default
The management class is set on the default domain of the VMware datacenter node.
VMMC option
The management class is set with the vmmc option.

612 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 VMCTLMC option
The management class is set with the vmctlmc option.
INCLUDE.VM option
The management class is set with the include.vm option.
VM Tag Management Class (IBM Spectrum Protect)
The management class is set as a tag value of the Management Class (IBM Spectrum
Protect) tag category. Tag values can be set with data protection settings in the IBM
Spectrum Protect vSphere Client plug-in in the vSphere Web Client, or by using tools such as
VMware vSphere PowerCLI version 5.5 R2 or later.
Important: In order to display the management class information that is set by tags, you must set the
vmtagdatamover yes option in the client options file, or you must include the -
vmtagdatamover=yes parameter when you run the dsmc backup vm command. If you did not set
the vmtagdatamover option or if it is set to no, the client ignores any management class tag values,
and displays the management class definition that is set in the default domain of the datacenter node,
the vmmc option, or the include.vm option.

Return codes for virtual machine backup operations

Backup operations for virtual machines can complete with the return codes that are shown in the
following table.

Return code Description

0 A command to back up one or more virtual machines completed successfully.
8 A command to back up multiple virtual machines succeeded for only some of the
virtual machines that were targeted by the command. Examine the log file to
determine the processing status for each of the targeted virtual machines.
12 Indicates that either of the following error conditions occurred:
• The backup command could not back up any of the virtual machines that were
targets of the backup operation.
• The backup command failed and it stopped before all virtual machines that were
specified were inspected.
Examine the log file to determine the reason for the failure.

Tip about the final statistics: If you are running multiple backup sessions, the value that is displayed in
the Data transfer time field in the final statistics can be higher than the value in the Elapsed processing
time field. The data transfer time is the sum of the times that each backup takes to send data across the
network. This number does not include the time for the data mover to read the data from disk before
sending it, nor the time to wait for server transactions to complete. This number can be greater than the
elapsed processing time if the operation uses multiple concurrent sessions to move data, such as multi-
session backup operations. This value includes the time that it takes to send data more than once due to
retries, such as when a file changes during a backup operation.

vStorage API for data protection example commands

Perform an IFIncremental backup of two VMs named vm3 and vm4.

dsmc backup vm vm3,vm4 -vmbackuptype=fullvm -mode=ifincremental

Perform an IFFull backup of a VM named vm1.

dsmc backup vm vm1 -vmbackuptype=fullvm -mode=iffull

Perform an IFFull VM backup of a VM named vm1, but include only Hard Disk 1 in the backup operation.

dsmc backup vm "vm1:vmdk=Hard Disk 1" -vmbackuptype=fullvm -mode=iffull

Chapter 11. Using commands 613

 Perform an incremental-forever backup of a virtual machine that is named vm1, but exclude Hard Disk 1
and Hard Disk 4 from the backup operation.

dcmc backup vm "vm1:-vmdk=Hard Disk 1:-vmdk=Hard Disk 4"

-vmbackuptype=fullvm -mode=iffull

Perform an incremental-forever-full backup of two virtual machines that are named vm1 and vm2. On
vm1, back up only Hard Disk 2 and Hard Disk 3. On vm2, back up all virtual disks.

dsmc backup vm "vm1:vmdk=Hard Disk 2:vmdk=Hard Disk 3",

vm2 -vmbackuptype=fullvm -mode=iffull

Perform parallel incremental-forever-full backups of the VMware virtual machines that are selected for
backup by using the selection criteria (domain parameters) on the domain.vmfull statement. Set the
maximum number of parallel backups to 5 virtual machines and 10 sessions and limit the backups to 5
VMs per host and 5 VMs per datastore.

dsmc backup vm –vmbackuptype=fullvm –mode=iffull –vmmaxparallel=5

–vmmaxbackupsessions=10 –vmlimitperhost=5 –vmlimitperdatastore=5

Related links for backing up VMware virtual machines

• “Query VM” on page 659
• “Restore VM” on page 681
• “Domain.vmfull” on page 355
• “Include.vm” on page 410
• “Mbobjrefreshthresh” on page 432
• “Mbpctrefreshthresh” on page 433
• “Mode” on page 435
• “Vmbackdir” on page 541
• “Vmbackuplocation” on page 542
• “Vmbackupmailboxhistory” on page 544
• “Vmbackuptype” on page 544
• “Vmchost” on page 545
• “Vmctlmc” on page 547
• “Vmcpw” on page 546
• “Vmcuser” on page 548
• “Vmdatastorethreshold” on page 548
• “Vmenabletemplatebackups” on page 552
• “Vmlimitperdatastore” on page 554
• “Vmlimitperhost” on page 555
• “Vmmaxbackupsessions” on page 556
• “Vmmaxparallel” on page 558
• “Vmmaxvirtualdisks” on page 563
• “Vmmc” on page 564
• “Vmpreferdagpassive” on page 567
• “Vmprocessvmwithindependent” on page 568
• “Vmprocessvmwithprdm” on page 569
• “Vmskipctlcompression” on page 570
• “Vmskipmaxvirtualdisks” on page 570
• “Vmtagdatamover” on page 572

614 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • “Vmtagdefaultdatamover” on page 574
• “Vmverifyifaction” on page 576
• “Vmverifyiflatest” on page 578
• “Vmvstortransport” on page 580
• “Vmvstorcompr” on page 579
• “Vmtimeout” on page 581
• “Set Vmtags” on page 711
• Virtual machine exclude options
• Virtual machine include options

Cancel Process
The cancel process command displays a list of current NAS (if NDMP support is enabled) image
backup and restore processes for which the administrative user has authority. You are prompted for the
IBM Spectrum Protect administrator ID.
From the list, the administrative user can select one process to cancel. Client owner privilege is sufficient
authority to cancel the selected NAS image backup or restore processes.

Supported Clients
This command is valid for AIX, Linux, and Solaris clients only.

Syntax
Cancel Process

Parameters
There are no parameters for this command.

Examples
Task
Cancel current NAS image backup or restore processes.
Command: cancel process

Cancel Restore
The cancel restore command displays a list of your restartable restore sessions in the server
database.
You can cancel only one restartable restore session at a time. Run the cancel restore command again
to cancel more restores. To restart restartable restore sessions, use the restart restore command.
Use the cancel restore command under the following circumstances:
• You cannot back up files that are affected by the restartable restore.
• Restartable restore sessions lock the file space so that files cannot be moved off of the sequential
volumes of the server.

Supported Clients
This command is valid for all clients.

Chapter 11. Using commands 615

 Syntax
Cancel Restore

Parameters
There are no parameters for this command.

Examples
Task
Cancel a restore operation.
cancel restore

Delete Access
The delete access command deletes authorization rules for files that are stored on the server.
When you delete an authorization rule, you revoke user access to any files or images that are specified by
that rule.

Supported Clients
This command is valid for all clients.

Syntax
Delete ACcess

Parameters
There are no parameters for this command.

Examples
Task
Display a list of current authorization rules and select the rules that you want to delete.
delete access
See the following screen example:

Index Type Node Owner Path

_____ _______ ____________________________________
1 Backup NODE1 USER1 home/dev/proja/list/
2 Archive NODE3 LUIE home/fin/budg/depta/
3 Backup NODE4 USER2 home/plan/exp/deptc/
4 Archive NODE5 USER2S home/mfg/invn/parta/
Enter Index of rule(s) to delete, or quit to cancel:

To delete the authorization rules that allow luie and user2s to access your files or images, type 2 4
or 2,4 and press Enter.

Delete Archive
The delete archive command deletes archived files from IBM Spectrum Protect server storage. Your
administrator must give you the authority to delete archived files.
Important: When you delete archived files, you cannot retrieve them. Verify that the files are obsolete
before you delete them.

616 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Supported Clients
This command is valid for all clients.

Syntax
Delete ARchive filespec
options { filespacename } filespec

Parameters
filespec
Specifies the path and file name that you want to delete from storage. Use wildcard characters to
specify a group of files or all files in a directory. You can also use the filelist option to process a
list of files. The backup-archive client opens the file that you specify with this option and processes
the list of files within according to the specific command.
Note: If you indicate filespacename, do not include a drive letter in the file specification.
{filespacename}
Specifies the file space (enclosed in braces) on the server that contains the file you want to delete.
This is the name on the workstation drive from which the file was archived.
Use the filespacename if the name was changed, or if you are deleting files that are archived from
another node with drive labels that are different from yours.

Table 88. Delete Archive command: Related options

Option Where to use
dateformat “Dateformat” Client options file (dsm.opt) or command line.
on page 334
description “Description” Command line only.
on page 341
filelist “Filelist” on page Command line only.
387
noprompt “Noprompt” on Command line only.
page 443
numberformat Client options file (dsm.opt) or command line.
“Numberformat” on page
445
pick “Pick” on page 451 Command line only.
subdir “Subdir” on page Client options file (dsm.opt) or command line.
515
tapeprompt “Tapeprompt” Client options file (dsm.opt) or command line.
on page 520
timeformat “Timeformat” Client options file (dsm.opt) or command line.
on page 528

Examples
Task
Delete a file that is named budget.
dsmc delete archive /user/home/proj1/budget

Chapter 11. Using commands 617

 Task
Delete all files that are archived from the /user/home/proj1 directory with a file extension of .txt.
dsmc del arch "/user/home/proj1/*.txt"
Task
Delete files that are archived from the /user/project directory by using the pick option to display
a list of archive copies that match the file specification. From the list, you can select the versions to
process.
dsmc delete archive "/user/project/*" -pick
Task
Delete selected files from the group of files that are archived with the description "Monthly Budgets
2010" located in /user/projects and its subdirectories.
dsmc delete ar "/user/projects/*" -description="Monthly Budgets 2010" -pick
-subdir=yes
Related information

Delete Backup
The delete backup command deletes files, images, and virtual machines that were backed up to IBM
Spectrum Protect server storage. Your administrator must give you authority to delete objects.
When you delete files, the IBM Spectrum Protect server takes all of the backed up files that meet the
filespec and deltype options that are specified and deactivates them. The server also assigns a
deactivation date of infinite-minus so that the files are no longer available for restore and are purged,
immediately on the subsequent run of file expiration. The file is not physically removed until the
expiration process runs.
Important: After you delete backup files, you cannot restore them; verify that the backup files are no
longer needed before you delete them. You are prompted to choose whether you want to continue with
the delete. If you specify yes, the specified backup files are scheduled for deletion and removed from
server storage.
Restriction: Files that are contained in a retention set are not deleted when you issue the delete
backup command. These files are retained in server storage to satisfy long-term data retention
requirements and expire according to the retention set's own expiration date after which they are eligible
for deletion. Therefore, they are still available for normal file processing operations, such as query or
restore operations, until the retention set expires.

Supported Clients
This command is valid for all clients.

618 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Syntax
Delete BAckup
filespec

{ filespacename } filespec

objtype=FILE

objtype=IMAGE

objtype=VM vmname
BOTH

-FROM SERVER

LOCAL

deltype=ACTIVE

options
deltype=INACTIVE

deltype=ALL

Parameters
filespace/filespec
filespec
Specifies the path and file name that you want to delete from storage. To specify a file in another file
space, precede the file name with the file space name. Use wildcard characters to specify a group of
files or all files in a directory. 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 that is specified
with this option and processes the list of files within according to the specific command.
Note: If you indicate filespacename, do not include a drive letter in the file specification.
When you use -deltype=inactive or -deltype=active, use wildcard characters to specify a
group of files or all files in a directory.
When you use -deltype=all, specify a fully wildcarded directory.
objtype
Specifies the type of object that you want to delete. You can specify either of the following values:
FILE
Specifies that you want to delete directories and files. This value is the default object type.
IMAGE
Specifies that you want to delete an image backup. Specifies that you want to delete an image
backup. Objtype=image is not supported on Mac OS X.
VM vmname
Specifies that you want to delete one or more versions of a virtual machine backup; the virtual
machine is identified by the vmname variable parameter. The virtual machine name cannot
contain wildcard characters.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect
for Virtual Environments.

Chapter 11. Using commands 619

 When objtype=VM is specified, the filelist option cannot be used. Specifying objtype=VM
changes the behavior of the -deltype option. When objtype=vm is specified, you can use either
-deltype=active or -deltype=inactive. You cannot use -deltype=all. Specifying -
deltype=inactive displays a list of both inactive and active backups. You can use this list to
specify which virtual machine backups that you want to delete. To delete only active virtual
machine backups, use -deltype=active.
When you specify -objtype=VM, this command deletes only virtual machine backups that were
created with any of the following modes: IFINCR, and IFFULL.
For backups that were created with the version 7.1 or earlier clients: Individual incremental
backups (backups that were created by using MODE=INCR) that were created after a full backup
was run cannot be deleted with this command. However, if you delete a full virtual machine image
backup (created by using MODE=FULL), and if the server has any incremental backups
(MODE=INCR) that were created for this VM after the full backup, then deleting the full VM backup
also deletes the files that were created by a MODE=INCR backup.
If you delete an active backup for a virtual machine, the most recent inactive copy becomes the
active backup. If you specify the -pick or -inactive option, only the backup that you specify is
deleted. If you select a backup that is created by MODE=IFINCR, only the selected incremental
backup is deleted; other incremental backups for the virtual machine are not deleted.
-FROM
Specify the backup location or locations where virtual machine backups are deleted. You can
specify one of the following values:
SERVER
Backups of virtual machines are deleted from the IBM Spectrum Protect server.
LOCAL
Persisted snapshots of virtual machines are deleted from the hardware storage.
BOTH
Backups of virtual machines that are on the IBM Spectrum Protect server and snapshots
that are on the hardware storage are deleted. This value is the default.
Specifying this value displays a list of backup locations. From the list, you can select the
location from which to delete virtual machine backups.
deltype
Specifies the deletion type. Specify one of the following values:
ACTIVE
Delete only active file objects. Directory objects are not deleted. This value is the default deletion
type.
Note: If there are any inactive objects, then after the active object is deleted, the most current
inactive object is changed from inactive to active.
To delete all versions of a file, first issue the delete backup command with -
deltype=inactive, then enter the command again with -deltype=active.
INACTIVE
Delete only inactive file objects. Directory objects are not deleted.
ALL
Delete all active and inactive objects below a particular directory, including all subdirectories and
their files.
Note: The parent directory of the deleted files and subdirectories is not deleted. If you specify
deltype=ALL, you cannot use the pick option because deltype=ALL and the pick option are
mutually exclusive.

620 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 89. Delete Backup command: Related options
Option Where to use
description “Description” Command line only.
on page 341
filelist “Filelist” on page Command line only.
387
fromdate “Fromdate” on Command line, and in the GUI find function.
page 393
fromtime “Fromtime” on Command line, and in the GUI find function.
page 395
noprompt “Noprompt” on Command line only.
page 443
pick “Pick” on page 451 Command line only.
pitdate “Pitdate” on page Command line, and in the GUI find function.
452
pittime “Pittime” on page Command line, and in the GUI find function.
453
subdir “Subdir” on page Client options file (dsm.opt) or command line.
515
tapeprompt “Tapeprompt” Client options file (dsm.opt) or command line.
on page 520
timeformat “Timeformat” Client options file (dsm.opt) or command line.
on page 528
todate “Todate” on page Command line, and in the GUI find function.
532
totime “Totime” on page Command line, and in the GUI find function.
532

Examples
Task
Delete all active and inactive file objects that are named budget in directory /data/plan/proj1.
Commands:

delete backup /data/plan/proj1/budget.jan

-deltype=inactive
delete backup /data/plan/proj1/budget.jan
-deltype=active

Task
Delete all inactive files that have a .txt extension that were backed up from the /data/plan/
proj1 directory and its subdirectories.
Command: delete backup "/data/plan/proj1/*.txt" -deltype=inactive -
subdir=yes
Task
Delete selected active files that are backed up from the /home/marymb/project directory. Use the
-pick option to display a list of backup copies that match the file specification. From the list, you can
select which versions to delete.

Chapter 11. Using commands 621

 Command: delete backup "/home/marymb/project/*" -pick
Task
Delete all active and inactive versions of files and subdirectories in the /home/storman/myproject
directory. Then, delete all active and inactive versions of the /user/myproject directory.
Command:

delete backup "/home/storman/myproject*"

-deltype=all

Related reference
“Filelist” on page 387
Use the filelist option to process a list of files.

Delete Filespace
The delete filespace command deletes file spaces in IBM Spectrum Protect server storage. A file
space is a logical space on the server that contains files you backed up or archived.
You must be an authorized user to use this command.
IBM Spectrum Protect assigns a separate file space on the server for each workstation file system from
which you back up or archive files. The file space name is the same as the file system name.
When you enter the delete filespace command, a list of your file spaces is displayed. From this list,
select the file space that you want to delete.
Your IBM Spectrum Protect administrator must give you authority to delete a file space. You need
BACKDEL authority if the file space you want to delete contains backup versions, or ARCHDEL authority if
the file space contains archive copies. If the file space contains both backup versions and archive copies,
you need both types of authority.
Important: When you delete a file space, you delete all backup versions and archive copies within that
file space. When you delete a file space, you cannot restore the files. Verify that the files are obsolete
before you delete them.
You can use the delete filespace command to interactively delete NAS file spaces from server
storage. Use the nasnodename option to identify the NAS file server. Use the class option to specify the
class of the file space to delete.

Supported Clients
This command is valid for all clients.

Syntax
Delete Filespace
options

Parameters

Table 90. Delete Filespace command: Related options

Option Where to use
class “Class” on page 321 Command line only.
detail “Detail” on page 342 Command line only.
nasnodename “Nasnodename” on page 440 Client system options file or command line.
scrolllines “Scrolllines” on page 487 Client system options file or command line.

622 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 90. Delete Filespace command: Related options (continued)
Option Where to use
scrollprompt “Scrollprompt” on page 488 Client system options file or command line.

Examples
Task
Delete a file space.
Command: delete filespace
Task
Delete NAS file spaces from the dagordon NAS file server stored on the server.
Command: delete filespace -nasnodename=dagordon -class=nas
Related information
“Nasnodename” on page 440
“Class” on page 321

Delete Group
Use the delete group command to delete a group backup on the IBM Spectrum Protect server.
After you delete a group, the group leader (virtualfsname) remains on the IBM Spectrum Protect server. It
contains no members (file or directories) but is reported in a subsequent query filespace command.
No files are listed if the showmembers option is added. Deleting a group does not remove the file space
that it resides in because there might be other groups in it. Use delete filespace if you want to
remove the file space and all the data it contains.
Note:
1. Use the inactive option to display both active and inactive group backup versions. By default, the
client displays active versions.
2. Use the pick option to select a specific group to delete from the IBM Spectrum Protect server.
3. Use the noprompt option if you want to suppress the confirmation prompt that normally appears
before you delete a group backup version. By default, the client prompts you for confirmation before
you delete the group backup. Using this option can speed up the delete procedure. However, it also
increases the danger of accidentally deleting a group backup version that you want to save. Use this
option with caution.
4. Use the query filespace command to display virtual file space names for your node that are stored
on the server.

Supported Clients
This command is valid for all UNIX and Linux clients, except for Mac OS X.

Syntax
Delete GRoup filespec
options

Parameters
filespec
Specifies the virtual file space name and the group name that you want to delete from the server
storage.

Chapter 11. Using commands 623

 Table 91. Delete Group command: Related options
Option Where to use
inactive “Inactive” on Command line only.
page 401
noprompt “Noprompt” on Command line only.
page 443
pick “Pick” on page 451 Command line only.
pitdate “Pitdate” on page Command line only.
452
pittime “Pittime” on page Command line only.
453

Examples
Task
Delete the current active version of the /virtfs/group1 group.
Command:

delete group /virtfs/group1

Task
Delete a backup version of the /virtfs/group1 group from a list of active and inactive versions.
Command:

delete group /virtfs/group1 -inactive -pick

Related information
“Inactive” on page 401
“Pick” on page 451
“Noprompt” on page 443
“Query Filespace” on page 646

Expire
The expire command deactivates the backup objects that you specify in the file specification or with the
filelist option. You can specify an individual file to expire, or a file that contains a list of files to expire.
If OBJTYPE=VM, this command deactivates the current backup for a virtual machine.
When you are working in interactive mode, a prompt notifies you before files are expired.
The expire command does not remove workstation files. If you expire a file or directory that still exists
on your workstation, the file or directory is backed up again during the next incremental backup, unless
you exclude the object from backup processing.
If you expire a directory that contains active files, those files are not displayed in a subsequent query from
the GUI. However, these files are displayed on the command line, if you specify the correct query with a
wildcard character for the directory.
Note: Because the expire command changes the server picture of the client file system without
changing the client file system, the expire command is not allowed on files that are on a file system that
is monitored by the IBM Spectrum Protect journal daemon.

624 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Supported Clients
This command is valid for all clients.

Syntax
OBJTYPE=FILE filespec
EXPire

OBJTYPE=VM vmname options

Parameters
OBJTYPE=FILE filespec
Specifies a path and a file name that you want to expire. You can enter only one file specification on
this command. However, you can use wildcards to select a group of files or all the files in a directory.
If you specify the filelist option, the filespec designation is ignored.
OBJTYPE=VM vmname
vmname specifies the name of a virtual machine. The active backup for the specified virtual machine is
expired. The virtual machine name cannot contain wildcard characters.
When objtype=VM is specified, the expire command expires only full virtual machine backups
(MODE=IFFULL) for the virtual machine that is specified on the vmname parameter.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.

Table 92. Expire command: Related options

Option Where to use
dateformat “Dateformat” Client user-options file (dsm.opt) or command line.
on page 334
filelist “Filelist” on page Command line only.
387
noprompt “Noprompt” on Command line only.
page 443
numberformat Client user-options file (dsm.opt) or command line.
“Numberformat” on page
445
pick “Pick” on page 451 Command line only.
timeformat “Timeformat” Client user-options file (dsm.opt) or command line.
on page 528

Examples
Task
Deactivate the letter1.txt file in the home directory.
Command: expire "/home/letter1.txt"
Task
Deactivate all files in the /admin/mydir directory.
Command: expire /admin/mydir/*

Chapter 11. Using commands 625

 Task
Deactivate all files that are named in the /home/avi/filelist.txt file.
Command: expire -filelist=/home/avi/filelist.txt

Help
Use the help command to display information about commands, options, and messages.
Tip: If you use the help command on the initial command line, no server contact is made and no
password is needed.

Supported Clients
This command is valid for all clients.

Syntax
Help
command-name [subcommand-name]

option-name

TOC-section-number

[ANS]message-number

Entering the help command with no arguments causes help to display the complete table of contents.
Either with the initial command or when HELP displays a prompt, you can enter the following parameters.

Parameters
command-name [subcommand-name]
Specifies a command name and, optionally, a subcommand name or their abbreviation, for example:
backup image, or b i. In that case, the combination must be unique. Non-unique abbreviations
result in the display of the first section of the entire help file that matches the abbreviation. This
parameter is optional.
option-name
Specifies the name of an option, for example: domain or do. This parameter is optional.
TOC-section-number
Specifies a table of contents section number, for example: 1.5.3. This parameter is optional.
[ANS]message-number
Specifies a message number with or without its prefix, for example: ans1036 or 1036. This parameter
is optional. The severity code is never necessary. Entering ans1036E results in a not-found response.
Important: If you enter arguments that do not fit these descriptions, you may get unexpected results (or
no results) to be displayed. If you enter more than two arguments, your help request is rejected. Where a
command name and an option name are the same, for example: incremental (command) and
incremental (option), you can get help on the option by entering its table-of-contents section number.
The requested help text is displayed in one or more sections, depending on the number of display lines
that are available in your command window. When enough lines are displayed to fill the display space, or
when the end of the requested help text is displayed, you see a prompt along with instructions for what
can be entered at that prompt. To continue displaying text for your current selection, press enter or type
the 'd' key to scroll down. To scroll up in the current selection, press the 'u' key and press Enter. Other
choices might be presented, so read the prompt instructions.
Proper display of the help text requires a usable display width of 72 characters. A display width fewer
than 72 characters causes sentences that are 72 characters wide to wrap to the next line. This can cause

626 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 the displayed help text to begin somewhere within the section rather than at the beginning. The
undisplayed lines can be viewed by using the scrolling function of the terminal to move up.

Examples
Task
Display the table of contents of the help topics.
Command: dsmc help
Task
Display the information in help topic 2.1.2
Command: dsmc help 2.1.2
Task
Display help information on the archive command.
Command: dsmc help archive
Task
Display help information on message ANS1036.
Command: dsmc help 1036
Command: dsmc help ANS1036

Incremental
The incremental command backs up all new or changed data in the locations that you specify, unless
you exclude them from backup services.
You can back up all new or changed files or directories in the default client domain or from file systems,
directories, or files.
To incrementally back up selected files or directories, enter a file specification in the command. If you do
not enter a file specification, the default is to back up files or directories in the default domain.
AIX only: You can enable snapshot-based incremental backup by using the option
snapshotproviderfs=JFS2.
The following attributes in the management class that is assigned to the file or directory affect whether
the data is backed up:
Frequency
The number of days that must elapse between successive backups of the object. The frequency
attribute applies only to a full incremental backup.
This management class attribute is ignored during a journal-based backup.
Mode
Specifies whether changes since the last backup operation affect the processing. If mode=modified,
only objects that changed since the last backup operation are processed. If mode=absolute, every
object is processed, regardless of whether the object changed since the last backup operation.
If the copy group mode is set to modified, it can be overridden by using the client absolute option.
For more information about the absolute option, see “Absolute” on page 306.
Serialization
Permits or denies backup of files or directories according to the following values:
• static: To be backed up, data must not be modified during backup or archive.
• shared static: If data in the file or directory changes during each of the allowed attempts to
back up or archive it, it is not backed up or archived. The value of the changingretries option
determines how many attempts are made. The default is 4.

Chapter 11. Using commands 627

 • dynamic: The object is backed up or archived on the first attempt whether or not data changes
during the process.
• shared dynamic: The object is backed up or archived on the last attempt, even if data changes
during the process.
Using the include option in an include-exclude list, you can override the default management class for a
file or group of files.
You can perform either a full incremental backup or an incremental-by-date backup. The default is a full
incremental backup.
If you are journaling a file system and the journal is valid, the full incremental backup performs a journal-
based backup. More than one journal-based backup session can be started, but only one journal-based
backup session can proceed. All other journal-based backup sessions that need access to the same file
space must wait until the current journal-based backup session completes before the next session can
proceed. You can perform a full incremental backup without the journal by using the nojournal option.
You can also use the selective command to perform a backup that backs up only the files, directories,
or empty directories that you specify regardless of whether they were changed.
A full incremental backs up all files and directories that are new or were changed since the last
incremental backup. During a full incremental backup, the client queries the server. IBM Spectrum
Protect uses this information when it performs the following actions:
• Backing up new files or directories.
• Backing up files or directories whose contents were changed since the previous backup.
• Marking inactive backup versions on the server for files or directories that are deleted from the
workstation.
• Rebinding backup versions to management classes if the management class assignments change.

Supported Clients
This command is valid for all clients.

Syntax

Incremental
options filespec

"filespec"

Parameters
filespec
Specifies the path and file name that you want to back up. Use wildcard characters to select a group
of files or all the files in a directory. If you do not specify a file specification, the domain option
determine what to back up.
If you specify a file system, all new and changed files are backed up. In addition, the last incremental
date for the file space is updated on the server. If you specify a file or directory, the last incremental
date is not updated. This means that the file or directory might be backed up again if a later backup is
performed by using the incrbydate option. If you specify a file system, specify the file system
without a trailing slash.

Table 93. Incremental command: Related options

Option Where to use
absolute “Absolute” on page 306 Command line only.

628 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 93. Incremental command: Related options (continued)
Option Where to use
changingretries “Changingretries” on page 321 dsm.sys file or command line.
compressalways “Compressalways” on page 325 Client user-options file (dsm.opt) or
command line.
compression “Compression” on page 326 dsm.sys file within a server stanza or
command line.
detail “Detail” on page 342 Command line only.
diffsnapshot “Diffsnapshot” on page 343 Command line only.
dirsonly “Dirsonly” on page 346 Command line only.
domain “Domain” on page 349 dsm.sys file or the client user-options
file (dsm.opt) or command line.
encryptiontype “Encryptiontype” on page 368 System-options file (dsm.sys) within a
server stanza.
encryptkey “Encryptkey” on page 369 System-options file (dsm.sys) within a
server stanza.
filelist “Filelist” on page 387 Command line only.
filesonly “Filesonly” on page 390 Command line only.
incrbydate “Incrbydate” on page 420 Command line only.
memoryefficientbackup “Memoryefficientbackup” on Client user-options file (dsm.opt), client
page 434 system-options file (dsm.sys), server,
or command line.
nojournal “Nojournal” on page 443 Command line only.
preservelastaccessdate “Preservelastaccessdate” on Client user-options file (dsm.opt) or
page 457 command line.
removeoperandlimit “Removeoperandlimit” on page 466 Command line only.
snapdiff “Snapdiff” on page 494 Command line only.
snapshotcachesize “Snapshotcachesize” on page 502 Client options file (dsm.opt) or with the
include.fs option.
snapshotproviderfs “Snapshotproviderfs” on page 503 System-options file (dsm.sys) within a
server stanza or with the include.fs
option.
snapshotroot “Snapshotroot” on page 504 Command line only.
subdir “Subdir” on page 515 Client user-options file (dsm.opt) or
command line.
tapeprompt “Tapeprompt” on page 520 Client user-options file (dsm.opt) or
command line.

Examples
Task
Run an incremental backup of the client domain that is specified in your client user-options file
(dsm.opt).

Chapter 11. Using commands 629

 Incremental

Run an incremental backup that backs up all files in the domain regardless of whether they were
changed since the last backup.

Incremental -absolute

Task
Run an incremental backup for the /home, /usr, and /proj file systems.

Incremental /home /usr /proj

Task
Run an incremental backup for the /proj/test directory.

Incremental /proj/test/

Task
Run an incremental-by-date backup for the /home file system.

Incremental -incrbydate /home

Task
Run an incremental backup of the abc file in the /fs/dir1 directory.

Incremental -subdir=yes /fs/dir1/abc

Task
Run an incremental backup of the directory object /fs/dir1, but not any of the files in the /fs/
dir1 directory.

Incremental /fs/dir1

Task
Run an incremental backup of the directory object /fs/dir1, all of the files in the fs/dir1 directory,
and all files and subdirectories under /fs/dir1.

Incremental -subdir=yes /fs/dir1/

Task
Assuming that you initiated a snapshot of the /usr file system and mounted the snapshot as /
snapshot/day1, 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 /usr.

dsmc inc /usr -snapshotroot=/snapshot/day1

Task
Run an incremental backup for the /home file system by using the snapdiff option and specify the
option to create the difference snapshot. In the following example, /home is the NFS mount point for
a NAS/N-Series file server volume.

incremental /home -snapdiff -diffsnapshot=create

Related information
“Absolute” on page 306
“Journal-based backup” on page 631
“Selective” on page 698
“Include options” on page 403

630 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Journal-based backup
A backup for a particular file system is journal-based when the IBM Spectrum Protect journal daemon is
installed and configured to journal the file system, and a valid journal has been established.
Journal-based backup is supported on the AIX Backup-Archive Client, on JFS and JFS2 file systems.
Journal-based backup is supported on the Linux Backup-Archive client on Ext2, Ext3, Ext4; XFS,
ReiserFS, JFS, VxFS, and NSS. GPFS is not supported for journal-based backups on Linux.
If the journal daemon is installed and running, then by default the incremental command performs a
journal-based backup on file systems which are being monitored by the journal engine daemon. The
following conditions must be met in order to successfully perform a journal-based backup:
• The journal daemon must be set up to monitor the file system that contains the files and directories
being backed up.
• A full incremental backup must have been run successfully at least once on the file system being
backed up.
• The file space image of the file system at the server cannot have been modified by an administrative
command since the last full incremental backup.
• The storage management policy for the files being backed up cannot have been updated since the last
full incremental backup.
The journal daemon records changes to an object or its attributes in a journal database. During a journal-
based backup, the client obtains a list of files that are eligible for backup from the journal database.
Journal-based backup can increase backup performance because the client does not scan the local file
system or contact the server to determine which files to process. Journal-based backup also reduces
network traffic between the client and server
The backup-archive client filters the list based on the current include-exclude list and processes, expires,
and updates the resulting files according to policy constraints, such as serialization. However, the client
ignores the server frequency attribute during a journal-based backup. The reason for this is because a
journal-based backup eliminates the backup version query to the server; therefore, the client does not
know how many days have transpired since the last backup of the file.
The journal daemon does not record changes in UNIX special files.
The journal daemon excludes specific system files from having changes recorded in the journal. Because
changes to these files are not journaled, the client does not back up these files. See the journal daemon
configuration file tsmjbbd.ini located in the backup-archive client installation directory for specific
system files that are excluded.
Note:
1. When using antivirus software, there are limitations to journal-based backup. Some antivirus software
can incorrectly generate change notifications to the IBM Spectrum Protect journal service, causing
files that have not changed to be incorrectly backed up during journal based backup. To avoid these
problems, use Norton Anti-Virus Corporate Edition 8.0 and higher.
2. 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.
Add an exclude snapshot statement to the tsmjbbd.ini file for AIX 6.1 (or later) to prevent JFS2
internal snapshot directories from being monitored by the journal-based backup daemon. If you do not
exclude the snapshot directories, the files in them are backed up. Backing up the snapshot directories
is redundant and wastes server space.
Under the following conditions, the journal database is considered invalid and the client reverts to the
traditional full incremental backup:

Chapter 11. Using commands 631

 • A journaled file space name has changed.
• The client node name has changed.
• The client contacts a different server to do the backup.
• Policy changes have occurred (new policy set activation).
• The journal is corrupt (out of space conditions, disk error).
• The journal is not running.
Journal-based backup differs from the traditional full incremental backup in the following ways:
• IBM Spectrum Protect does not enforce non-default copy frequencies (other than 0).
• Changes to UNIX special files are not detected.
You can use the nojournal option with the incremental command to perform a traditional full
incremental backup instead of the default journal-based backup.

Incremental-by-Date
An incremental-by-date backup backs up new and changed files with a modification date later than the
date of the last incremental backup stored at the server, unless the files are excluded from backup by an
exclude statement.
If an incremental-by-date is performed on only part of a file system, the date of the last full incremental is
not updated, and the next incremental-by-date will back up these files again. Changes to the access
control lists (ACL) or Extended Attributes do not cause the files to be backed up during an incremental-
by-date. Use the query filespace command to determine the date and time of the last incremental
backup of the entire file system.
To perform an incremental-by-date backup, use the incrbydate option with the incremental
command.
Unlike a full incremental, an incremental-by-date does not maintain current server storage of all your
workstation files for the following reasons:
• It does not expire backup versions of files that are deleted from the workstation.
• It does not rebind backup versions to a new management class if the management class has changed.
• It does not back up files with attributes that have changed, unless the modification dates and times
have also changed.
• It ignores the copy group frequency attribute of management classes.
For these reasons, if you have limited time during the week to perform backups, but extra time on the
weekends, you can perform an incremental-by-date backup on weekdays and a full incremental backup
on weekends to maintain current server storage of your workstation files.
If the incremental command is retried because of a communication failure or session loss, the transfer
statistics will display the number of bytes that the client attempted to transfer during all command
attempts. Therefore, the statistics for bytes transferred might not match the file statistics, such as those
for file size.

Associate a local snapshot with a server file space

Use the snapshotroot option with the incremental command 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.
The snapshotroot option does not provide any facilities to take a volume snapshot, only to manage
data created by a volume snapshot.

632 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Loop
The loop command starts an interactive command line session that is maintained until you enter quit.
If you are required to enter a password, you are prompted for it before the loop mode prompt appears.
Note: It is not possible to enter loop mode without a valid server contact. One of the consequences is that
certain commands, such as restore backupset -location=file, are only accepted on the initial
command line when a valid server is not available.
In an interactive command line session, it is unnecessary to precede each command name with dsmc and
your password, if one is required.
In interactive mode, options that you enter on the initial command line override the value that you
specified in your client user-options file (dsm.opt) or dsm.sys file. This value remains in effect for the
entire interactive session unless overridden by a different value on a given interactive command. For
example, if you set the subdir option to yes in your client user-options file (dsm.opt), and you specify
subdir=no on the initial command line, the subdir=no setting remains in effect for the entire interactive
session unless overridden by the subdir=yes value on a given interactive command. However, the
subdir=yes value only affects the command it is entered on. When that command completes, the value
reverts back to subdir=no, the value at the beginning of the interactive session.
You can enter all valid commands in interactive mode except the schedule and loop commands.
There are some options that you cannot use in the interactive session created by the loop command and
are identified in the option description by this statement: This option is valid only on the initial command
line. It is not valid in interactive mode.
Note:
1. In loop mode, following a restore operation directly from tape, the mount point is not released in case
additional restore requests are made to that volume. If you request a backup operation in the same
session and that mount point is the only one available, the backup operation stops with the following
message:

Waiting for mount of offline media

In this case, the mount point is not released until one of the following conditions is met:
• The device class MOUNTRETENTION limit is satisfied.
• The client idletimeout period is satisfied.
• The dsmc loop session is closed after the restore operation completes, allowing you to start a
subsequent loop mode session to perform the backup operation.
2. In interactive mode, you cannot enter a file specification that contains national language characters. If
a command contains national characters, process the command in batch mode by preceding the
command with the executable program name, dsmc.

Supported Clients
This command is valid for all clients.

Syntax
LOOP

Parameters
There are no parameters for this command.

Chapter 11. Using commands 633

 Examples
Task
Start an interactive command line session.
Command: dsmc
At the Protect> prompt, enter a command.
There are two methods for ending an interactive session:
• Enter quit
• If you set editor=yes, you can do the following:
1. Press the Escape key (Esc).
2. Type Q and press the Enter key.
Note: The default setting is editor=yes.
Note: 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.
Related information
Chapter 10, “Processing options,” on page 277 for options that you cannot use in interactive mode.

Macro
The macro command runs a series of commands that you specify in a macro file.
By including the macro command within a macro file, you can nest as many as 10 levels of commands.
Comment lines are not supported within the macro file that you specify for the macro command.

Supported Clients
This command is valid for all clients.

Syntax
MAcro macroname

Parameters
macroname
Specifies the fully qualified name of the file that contains the commands.

Examples
The following is an example of how to use the macro command.
Task
Selectively back up files in the following directories:
• /devel/project/proja
• /devel/project/projb
• /devel/project/projc
Command: macro backabc.mac

634 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Where backabc.mac contains the following statements:

Selective /devel/project/proja/
Selective /devel/project/projb/
Selective /devel/project/projc/

Monitor Process
The monitor process command displays a list of current NAS (if NDMP support is enabled) image
backup and restore processes for which the administrative user has authority. You are prompted for the
IBM Spectrum Protect administrator ID.
The administrative user can then select one process to monitor. Client owner privilege is sufficient
authority to monitor the selected NAS image backup or restore processes.

Supported Clients
This command is valid for AIX, Linux, and Solaris clients only.

Syntax
MONitor Process

Parameters
There are no parameters for this command.

Examples
Task
Monitor current NAS image backup or restore processes.
Command: monitor process

Preview Archive
The preview archive command simulates an archive command without sending data to the server.
The preview archive command generates a tab-delineated text file that can be imported into a
spreadsheet program. The preview contains information such as whether the file is excluded or included.
If the file is excluded, the pattern, or reason, that the file is excluded is listed, along with the source for
the pattern.

Supported Clients
This command is valid for all clients.

Syntax
-filter=ALL

PREview Archive filespec -filter=INCL

-filter=EXCL -FILEName= filename

-TRAverse=Yes

-CONsole -TRAverse=No

Chapter 11. Using commands 635

 Parameters
filespec
Specifies the path and file name that you want to archive. Use wildcard characters to select a group of
files or all the files in a directory.
-filter
Specifies the output to display. You can display included objects, excluded objects, or both.
ALL
Display output for included and excluded objects. This is the default.
INCLuded
Display output for included objects only.
EXCLuded
Display output for excluded objects only.
-FILEName=
Specifies the filename in which to write the tab-delineated output. The default is dsmprev.txt.
-CONsole
Output is written to the console, and the file.
-TRAverse
Preview the current directory and subdirectories.
Yes
Preview the current directories and subdirectories. This is the default.
No
Preview only the current directory, not subdirectories.
Important: Specifying -traverse does not preview directories excluded using the exclude.dir
option.

Preview Backup
The preview backup command simulates a backup command without sending data to the server.
The preview backup command generates a tab-delineated text file that can be imported into a
spreadsheet program. The preview contains information such as whether the file is excluded or included.
If the file is excluded, the pattern, or reason, that the file is excluded is listed, along with the source for
the pattern.

Supported Clients
This command is valid for all clients.

Syntax
-filter=ALL

PREview backup filespec -filter=INCL

-filter=EXCL -FILEName= filename

-TRAverse=Yes

-CONsole -TRAverse=No

636 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Parameters
filespec
Specifies the path and file name that you want to back up. Use wildcard characters to select a group
of files or all the files in a directory.
-filter
Specifies the output to display. You can display included objects, excluded objects, or both.
ALL
Display output for included and excluded objects. This is the default.
INCLuded
Display output for included objects only.
EXCLuded
Display output for excluded objects only.
-FILEName=
Specifies the filename in which to write the tab-delineated output. The default is dsmprev.txt.
-CONsole
Output is written to the console, and the file.
-TRAverse
Preview the current directory and subdirectories.
Yes
Preview the current directories and subdirectories. This is the default.
No
Preview only the current directory, not subdirectories.
Important: Specifying -traverse does not preview directories excluded using the exclude.dir
option.

Query Access
The query access command shows who was given access to backup versions or archive copies of
specific files.
The backup-archive client displays a list of authorization rules that you defined with the set access
command or with the Utilities > Node Access List menu in the backup-archive client graphical user
interface (GUI).
The following information is included.
• Authority that you gave a user to restore backup versions or retrieve archive copies.
• The node name of the user to whom you gave authorization.
• The ID of the user at that node to whom you gave authorization.
• The files to which the user has access.

Supported Clients
This command is valid for all clients.

Syntax
Query ACcess

Parameters
There are no parameters for this command.

Chapter 11. Using commands 637

 Examples
Task
Display a list of users who have access to your files.
Command: query access

Query Archive
The query archive command displays a list of your archived files and the following information about
each file: file size, archive date, file specification, expiration date, and archive description.
If you use the detail option with the query archive command, the client displays the following
additional information:
• Last modification date
• Last access date
• Last file attributes (inode) change date
• Compression type
• Encryption type
• Client-side data deduplication
• Retention initiation
• Whether the file is on hold
• Size of ACL metadata (IBM Spectrum Scale), for AIX and Linux clients
• Server storage information (media class, volume ID, and restore order), for AIX and Linux clients
The following example shows sample output when the query archive command is issued with the
detail option:.

Size Archive Date - Time File - Expires on - Description

---- ------------------- -------------------------------
219 B 08/15/2016 09:32:13 /Volumes/Data/info.txt 08/16/2016
Archive Date: 08/16/2016
RetInit:STARTED Obj
Held:NO
Modified: 03/02/2016 19:43:00 Accessed: 03/03/2016 09:31:23 Inode changed: 03/02/2016 19:43:00
Compression Type: LZ4 Encryption Type: None Client-deduplicated: YES
ACL Size: 0 Media Class: Fixed Volume ID: 0008 Restore Order:
00000000-0000001F-00000000-00600774

For more information about the compression type, see “Compression” on page 326.

Supported Clients
This command is valid for all clients.

Syntax
Query ARchive filespec
options "filespec"

Parameters
filespec
Specifies the path and file name that you want to query. Use wildcard characters to specify a group of
files or all the files in a directory. If you use wildcard characters, enclose the file specification in
double quotation marks. Specify an asterisk (*) to query all archived files in the current directory.

638 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 94. Query Archive command: Related options
Option Where to use
dateformat “Dateformat” Client user-options file (dsm.opt) or command line.
on page 334
description “Description” Command line only.
on page 341
detail “Detail” on page 342 Command line only.
dirsonly “Dirsonly” on Command line only.
page 346
filelist “Filelist” on page Command line only.
387
filesonly “Filesonly” on Command line only.
page 390
fromdate “Fromdate” on Command line only.
page 393
fromnode “Fromnode” on Command line only.
page 394
fromowner “Fromowner” on Command line only.
page 395
fromtime “Fromtime” on Command line only.
page 395
numberformat Client user-options file (dsm.opt) or command line.
“Numberformat” on page
445
querysummary Command line only.
“Querysummary” on page
463
scrolllines “Scrolllines” Client user-options file (dsm.opt) or command line.
on page 487
scrollprompt Client user-options file (dsm.opt) or command line.
“Scrollprompt” on page 488
subdir “Subdir” on page Client user-options file (dsm.opt) or command line.
515
timeformat “Timeformat” Client user-options file (dsm.opt) or command line.
on page 528
todate “Todate” on page Command line only.
532
totime “Totime” on page Command line only.
532

Examples
Task
Display a list of all your archived files in the current working directory.
Command: q archive "*"

Chapter 11. Using commands 639

 Task
Display a list of all your archived files in the /devel directory and all of its subdirectories.
Command: query archive "/devel/*" -subdir=yes
Task
Display a list of all your archived files in the current directory. Use the dateformat and timeformat
options to reformat the dates and times.
Command: q ar –date=5 –time=1 "*"
Task
Display a list of all your archived files in the current directory. Use the detail option to display the
last modification date and the last access date of each file.
Command: q ar -detail "*"
Task
Display a list of archived files in the /home/proj directory whose first four characters of the file name
begin with proj.
Command: q ar "/home/proj/proj*"

Query Backup
The query backup command displays a list of backup versions of your files that are stored on the IBM
Spectrum Protect server, or that are inside a backup set from the server when the backupsetname
option is specified.
The command displays the following file information:
• File specification
• File size
• Backup date
• Whether the file is active or inactive
• The management class that is assigned to the file. Only the first 10 characters of the management class
name are displayed.
If you use the detail option with the query backup command, the client displays the following extra
information:
• Last modification date
• Last access date
• Last file attributes (inode) change date
• Compression type
• Encryption type
• Client-side data deduplication
• Whether the file is migrated or premigrated. A value of Yes means that the file is migrated or
premigrated. A value of No means that the file is not migrated or premigrated.
• File inode number (for AIX and Linux clients)
• Size of ACL metadata (IBM Spectrum Scale) (for AIX and Linux clients)
• Server storage information (media class, volume ID, and restore order) (for AIX and Linux clients)
The following example shows sample output when the query backup command is issued with the
detail option:

Size Backup Date Mgmt Class A/I File

---- ----------- ---------- --- ----
1,500,000 B 08/15/2016 16:01:25 DEFAULT A /home/test/mydir/

640 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 myfile1.txt
Modified: 08/15/2016 16:00:10 Accessed: 08/16/2016 15:31:23 Inode changed: 08/15/2016
16:00:10
Compression Type: LZ4 Encryption Type: None Client-deduplicated: YES Migrated: NO Inode#:
22691
ACL Size: 0 Media Class: Fixed Volume ID: 0008 Restore Order:
00000000-0000001F-00000000-00600774

For more information about the compression type, see “Compression” on page 326.

Supported Clients
This command is valid for all clients.

Syntax
Query Backup filespec
options "filespec"

Parameters
filespec
Specifies the path and file name that you want to query. Use wildcard characters to specify a group of
files or all the files in a directory. If you use wildcard characters, enclose the file specification in
double quotation marks. Specify an asterisk (*) to display information about backup versions for all of
your files in the current directory. Do not use wildcards characters when you query NAS file system
images with -class=nas option setting.

Table 95. Query Backup command: Related options

Option Where to use
backupsetname Command line only.
“Backupsetname” on page
318
class “Class” on page 321 Command line only.
dateformat “Dateformat” Client system options file (dsm.sys) or command line.
on page 334
detail “Detail” on page 342 Command line only.
dirsonly “Dirsonly” on Command line only.
page 346
filelist “Filelist” on page Command line only.
387
filesonly “Filesonly” on Command line only.
page 390
fromdate “Fromdate” on Command line only.
page 393
fromowner “Fromnode” on Command line only.
page 394
fromowner “Fromowner” on Command line only.
page 395
fromtime “Fromtime” on Command line only.
page 395

Chapter 11. Using commands 641

 Table 95. Query Backup command: Related options (continued)
Option Where to use
inactive “Inactive” on Command line only.
page 401
nasnodename Client system options file (dsm.sys) or command line.
“Nasnodename” on page 440
numberformat Client user-options file (dsm.opt) or command line.
“Numberformat” on page
445
pitdate “Pitdate” on page Command line only.
452
pittime “Pittime” on page Command line only.
453
querysummary Command line only.
“Querysummary” on page
463
scrolllines “Scrolllines” Client user-options file (dsm.opt) or command line.
on page 487
scrollprompt Client user-options file (dsm.opt) or command line.
“Scrollprompt” on page 488
subdir “Subdir” on page Client user-options file (dsm.opt) or command line.
515
timeformat “Timeformat” Client user-options file (dsm.opt) or command line.
on page 528
todate “Todate” on page Command line only.
532
totime “Totime” on page Command line only.
532

Examples
Task
Display a list of all active and inactive backup versions of your files in the current directory.
dsmc query backup –inactive "*"
Task
Display a list of all your backups in the current directory. Use the detail option to display the last
modification date and the last access date of each file.
dsmc q backup -detail "*"
Task
Display a list of files that were backed up from the /home/proj directory with file names that begin
with proj.
dsmc q b "/home/proj/proj*"
Task
Display a list of active and inactive backup file versions in the /home file system.
dsmc q b –ina –su=yes /home/

642 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Task
Query file system images from the nas2 NAS file server.
dsmc query backup -nasnodename=nas2 -class=nas
Related information
“Restore data from a backup set” on page 216

Query NAS file system images

You can use the query backup command to display information about file system images backed up for
a NAS file server. The client prompts you for an administrator ID.
Where supported, use the nasnodename option to identify the NAS file server to query. Place the
nasnodename option in your client system-options file (dsm.sys). The value in the client system-options
file is the default, but this value can be overridden on the command line.
Use the class option to specify the class of the file space to query. To display a list of images belonging
to a NAS node, use the -class=nas option.
Related reference
“Class” on page 321
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.
“Nasnodename” on page 440
The nasnodename option specifies the node name for the NAS file server when processing NAS file
systems. The client prompts you for an administrator ID.

Query Backupset
The query backupset command queries a backup set from a local file, tape device (if applicable), or
the IBM Spectrum Protect server.
This command displays the backup set name, generation date, retention (for a backup set on the IBM
Spectrum Protect server), and user-supplied description.

Supported Clients
This command is valid for all clients.
Tape support is only available on AIX and Oracle Solaris clients.

Syntax
Query BACKUPSET BACKUPSETName= backupsetname
options localfilename

tapedevice

LOCation= server

file

tape

Chapter 11. Using commands 643

 Parameters
BACKUPSETName=
Specifies the name of a backup set you want to query. You can use wildcards to specify the backup
set name. If you use wildcards or do not specify a backup set name, all backup sets that you own are
displayed. This parameter is required.
When a backup set is created, the server assigns root as the owner of the backup set. When querying
a backup set on the server, a non-root user does not see the backup set listed, even if they know the
backup set name and use it in the query.
The value of backupsetname depends on the location of the backup set, and corresponds to one of
these three choices:
backupsetname
Specifies the name of the backup set from the server. If the location parameter is specified, you
must set -location=server.
localfilename
Specifies the file name of the first backup set volume. You must set -location=file.
tapedevice
Specifies the name of the tape device that contains the backup set volume. You must use a
Windows native device driver, not the device driver that is provided by IBM. You must set -
location=tape.
LOCation=
Specifies where the backup-archive client searches for the backup set. If you do not specify the
location parameter, the client searches for backup sets on the IBM Spectrum Protect server.
server
Specifies that the client searches for the backup set from the server. This location is the default.
file
Specifies that the client searches for the backup set from a local file.
tape
Specifies that the client searches for the backup set from a local tape device.

Table 96. Query Backupset command: Related options

Option Where to use
description “Description” Command line only.
on page 341
scrolllines “Scrolllines” Client user-options file (dsm.opt) or command line.
on page 487
scrollprompt Client user-options file (dsm.opt) or command line.
“Scrollprompt” on page 488

Examples
Task
Query all backup sets from the IBM Spectrum Protect server.
Command: query backupset -backupsetname=*
Task
Query a backup set that is called monthy_financial_data from the IBM Spectrum Protect server.
Command: query backupset -backupsetname=monthly_financial_data.12345678
Task
Query the backup set in the file /home/budget/weekly_budget_data.ost.

644 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Command: dsmc query backupset -backupsetname="/home/budget/
weekly_budget_data.ost" -loc=file
Task
Query the backup set from the /dev/rmt0 tape device.
Command: dsmc query backupset -backupsetname=/dev/rmt0 -loc=tape
Related information
“Restore data from a backup set” on page 216

Query Backupset without the backupsetname parameter

The query backupset command can be used without the backupsetname parameter.

The preferred syntax for query backupset command requires the backupsetname parameter. Prior to
the introduction of the backupsetname parameter, the baxkup-archive client queried backup sets with a
different syntax.
While you can use syntax from previous releases for this command, do not do so unless you have a
specific need and cannot replace the old syntax with the syntax in Tivoli Storage Manager Version 6.1. For
best results, use the backupsetname parameter.

Supported Clients
This command is valid for all clients.
Tape support is only available on AIX and Oracle Solaris clients.

Syntax
Query BACKUPSET backupsetname
options localfilename

tapedevice

LOCation= server

file

tape

Parameters
backupsetname
Specifies the name of the backup set from the IBM Spectrum Protect server. If the location
parameter is specified, you must set -location=server.
localfilename
Specifies the file name of the first backup set volume. You must set -location=file.
tapedevice
Specifies the name of the tape device containing the backup set volume. You must use a Windows
native device driver, not the device driver provided by IBM. You must set -location=tape.
LOCation=
Specifies where the client searches for the backup set. If you do not specify the location parameter,
the client searches for backup sets on the IBM Spectrum Protect server.
server
Specifies that the client searches for the backup set from the server. This is the default.

Chapter 11. Using commands 645

 file
Specifies that the client searches for the backup set from a local file.
tape
Specifies that the client searches for the backup set from a local tape device.

Table 97. Query Backupset command: Related options

Option Where to use
description “Description” Command line only.
on page 341
scrolllines “Scrolllines” Client user-options file (dsm.opt) or command line.
on page 487
scrollprompt Client user-options file (dsm.opt) or command line.
“Scrollprompt” on page 488

Examples
Task
Query all backup sets from the IBM Spectrum Protect server.
Command: query backupset
Task
Query a backup set called monthy_financial_data from the IBM Spectrum Protect server.
Command: query backupset monthly_financial_data.12345678
Task
Query the backup set in the file /home/budget/weekly_budget_data.ost.
Command: dsmc query backupset /home/budget/weekly_budget_data.ost -loc=file
Task
Query the backup set from the /dev/rmt0 tape device.
Command: dsmc query backupset /dev/rmt0 -loc=tape
Related information
“Restore data from a backup set” on page 216

Query Filespace
The query filespace command displays a list of file spaces for a node. The file spaces are stored on
the IBM Spectrum Protect server, or inside a backup set from the server when the backupsetname
option is specified. You can also specify a single file space name to query.
A file space is a logical space on the server that contains files you backed up or archived. A separate file
space is assigned on the server for each node at your workstation from which you back up or archive files.
A separate file space is assigned on the server for each file system at your workstation from which you
back up or archive files. The file space name is the same as the file system name.

Supported Clients
This command is valid for all clients.

646 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Syntax
Query Filespace
filespacename options

Parameters
filespacename
Specifies an optional character string that can include wildcards. Use this argument to specify a
subset of file spaces. The default is to display all file spaces.

Table 98. Query Filespace command: Related options

Option Where to use
backupsetname Command line only.
“Backupsetname” on page
318
class “Class” on page 321 Command line only.
dateformat “Dateformat” Client user-options file (dsm.opt) or command line.
on page 334
detail “Detail” on page 342 Command line only.
fromnode “Fromnode” on Command line only.
page 394
fromowner “Fromowner” on Command line only.
page 395
nasnodename Client system options file (dsm.sys) or command line.
“Nasnodename” on page 440
scrolllines “Scrolllines” Client user-options file (dsm.opt) or command line.
on page 487
scrollprompt Client user-options file (dsm.opt) or command line.
“Scrollprompt” on page 488
timeformat “Timeformat” Client user-options file (dsm.opt) or command line.
on page 528

Examples
Display your file spaces. Use the dateformat and timeformat options to reformat the dates and times.

query filespace –date=5 –time=4

Display the /home file space.

query filespace /home

Display file space names that include the pattern smith.

query filespace "*smith*"

Query a file space from the nas2 NAS file server.

query filespace -nasnodename=nas2 -class=nas

Display detailed file space information that shows the replication status during a failover.

Chapter 11. Using commands 647

 Command:
query filespace -detail
Output:

# Last Incr Date Type fsID Unicode Replication File Space Name
--- -------------- ------ ---- ------- ----------- --------------
1 00/00/0000 00:00:00 HFS 3 Yes Current /

Last Store Date Server Local

--------------- ------ -----
Backup Data : 04/29/2013 16:49:55 04/29/2013 16:49:55
Archive Data : No Date Available No Date Available

Related concepts
“Restore data from a backup set” on page 216
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.
“Automated client failover overview” on page 87
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.
Related tasks
“Determining the status of replicated client data” on page 92
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.
Related reference
“Nasnodename” on page 440
The nasnodename option specifies the node name for the NAS file server when processing NAS file
systems. The client prompts you for an administrator ID.
“Class” on page 321
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.
“Nrtablepath” on page 444
The nrtablepath option specifies the location of the node replication table on the client. The backup-
archive client uses this table to store information about each backup or archive operation to the IBM
Spectrum Protect server.

Query NAS file spaces

Use the nasnodename option to identify the NAS file server to query. When using an interactive
command-line session with a non-administrative ID, the client prompts you for an administrator ID.
Place the nasnodename option in your client system-options file (dsm.sys). The value in the client
system-options file is the default, but this value can be overridden on the command line. If the
nasnodename option is not specified in the client system-options file, it must be specified on the
command line when processing NAS file systems.
Use the class option to specify the class of the object to query. To display a list of file spaces belonging
to a NAS node, use the -class=nas option.

Query Group
Use the query group command to display information about a group backup and its members.
Note:

648 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
1. Use the showmembers option to display and select individual group members that you want to query.
The showmembers option is not valid with the inactive option. If you want to display members of a
group that are not currently active, use the pitdate and pittime options to specify the backup date
and time of the member you want to query.
2. Use the query filespace command to display virtual file space names for your node that are stored
on the IBM Spectrum Protect server.
3. If you perform a full and differential group backup, a query of this group using the -inactive option
displays two active backups of the same name, one of type FULL and one of type DIFF.

Protect> q group {/fs}/v1 -inactive

Size Backup Date Mgmt Class A/I Group

—––– ––––––––––– –––––––––– ––– ––––––
978 B 06/02/2007 11:57:04 DEFAULT A FULL /fs/v1
32 B 06/05/2007 13:52:04 DEFAULT A DIFF /fs/v1

If you query a group backup without the -inactive option, the query displays only the latest group
backup, whether it is type FULL or type DIFF:

Protect> q group {/fs}/v1

Size Backup Date Mgmt Class A/I Group

—––– ––––––––––– –––––––––– ––– ––––––
32 B 06/05/2007 13:52:04 DEFAULT A DIFF /fs/v1

Supported Clients
This command is valid for all clients, except for Mac OS X.

Syntax
Query GRoup filespec
options

Parameters
filespec
Specifies the virtual file space name and the group name on the server that you want to query.

Table 99. Query Group command: Related options

Option Where to use
fromnode “Fromnode” on Command line only.
page 394
fromowner “Fromowner” on Command line only.
page 395
inactive “Inactive” on Command line only.
page 401
pitdate “Pitdate” on page Command line only.
452
pittime “Pittime” on page Command line only.
453
showmembers Command line only.
“Showmembers” on page
493 (does not apply to Mac
OS X)

Chapter 11. Using commands 649

 Examples
Task
Display all the groups in the /virtfs file space.
Command:

query group /virtfs/*

Task
Display active and inactive versions of the /virtfs/group1 file space.
Command:

query group /virtfs/group1 -inactive

Task
Display the /virtfs/group1 file space. Use the showmembers option to display a list of group
members from which you can select one or more to query.
Command:

query group /virtfs/group1 -showmembers

Related information
“Query Filespace” on page 646

Query Image
The query image command displays information about file system images that are stored on the IBM
Spectrum Protect server, or that are inside a backup set from the IBM Spectrum Protect server, when the
backupsetname option is specified.
The following information about file system images is displayed:
• Image Size - The volume size which was backed up.
• Stored Size - The actual image size that is stored on the server. The stored image on the IBM Spectrum
Protect server is the same size as the volume capacity. For online snapshot-based image backups, the
stored image can be larger than the file system based on the size of the cache files. The stored image on
the server is the same size as the volume capacity.
• File system type
• Backup date and time
• Management class that is assigned to image backup
• Whether the image backup is an active or inactive copy
• The image name
Note: The IBM Spectrum Protect API must be installed to use the query image command.

Supported Clients
This option is valid for AIX, Linux, and Oracle Solaris clients.

Syntax
Query IMage logicalvolumename
options filespacename

650 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Parameters
logicalvolumename
The name of a logical volume you want to query. You must specify the exact name of the image. You
cannot use wildcards. The default is all active images (unless restricted by one or more options).
filespacename
Specifies the file system name that you want to query.
Omitting logicalvolumename and filespacename causes all images to be displayed.

Table 100. Query Image command: Related options

Option Where to use
backupsetname Command line only.
“Backupsetname” on page
318
dateformat “Dateformat” Client user option file (dsm.opt) or command line.
on page 334
fromnode “Fromnode” on Command line only.
page 394
fromowner “Fromowner” on Command line only.
page 395
inactive “Inactive” on Command line only.
page 401
numberformat Client user option file (dsm.opt) or command line.
“Numberformat” on page
445
pitdate “Pitdate” on page Command line only.
452
pittime “Pittime” on page Command line only.
453
scrolllines “Scrolllines” Client user options file (dsm.opt) or command line.
on page 487
scrollprompt Client user options file (dsm.opt) or command line.
“Scrollprompt” on page 488
timeformat “Timeformat” Client user option file (dsm.opt) or command line.
on page 528

Examples
Task
Display all backed up images.
Command: q image
Task
Display all backed up images that are owned by kutras at node avalon .
Command: query image -fromnode=avalon -fromowner=kutras
Task
Display active and inactive version of the /usr image.
Command: q i /usr -inactive

Chapter 11. Using commands 651

 Task
Display all images that are contained within the backup set weekly_backup_data.32145678.
Command: query image -backupsetname=weekly_backup_data.32145678
Related information
“Restore data from a backup set” on page 216

Query Inclexcl
The query inclexcl command displays a list of include-exclude statements in the order in which they
are processed during backup and archive operations. The list displays the type of option, the scope of the
option (archive, all, and so on), and the name of the source file.
The backup-archive client excludes some files from file system backup and restore operations. You can
use the query inclexcl command to display a list of these files. In the output of the command, these
files have Operating System next to the path.
You can test the validity of patterns you want to use in your include-exclude list before you actually insert
them in your options file. See the test pattern explanation.
Use the detail option to display the management class that is associated with an include-exclude
statement.

Supported Clients
This command is valid for all clients.

Syntax

Query INCLexcl
test pattern -DETail

Parameters
test pattern
Use for testing the validity of patterns you want to use in your include-exclude list. When you use a
test pattern with this command, the following occurs:
• The internal include-exclude list is not displayed
• The pattern is processed as if it came from an include-exclude statement, including all the usual
error checking
• The pattern is displayed as it would appear in the include-exclude list
If the test pattern has no errors, the compiled pattern result is the same as the test pattern.
-DETail
Displays the management class that is associated with the include-exclude statement.

Examples
Task
Exclude a file from deduplication by excluding it in the client options file:

Exclude Dedup *\...\file2

Task
Display a basic list of include-exclude statements. Command:

query inclexcl

652 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Task
Display a list of include-exclude statements. Display the management class that is associated with
each statement.

query inclexcl -detail

Task
Test the validity of this pattern: /.../?x?/*.log

query inclexcl /.../?x?/*.log

Query Mgmtclass
The query mgmtclass command displays information about the management classes available in your
active policy set.
Your administrator defines management classes that contain attributes which control whether a file is
eligible for backup or archive services. Management classes also determine how backups and archives
are managed on the server.
Your active policy set contains a default management class; it can contain any number of extra
management classes. You can assign specific management classes to files using include options that
are located in the client user-options file (dsm.opt). If you do not assign a management class to a file, the
default management class is used.
When you archive files, you can override the assigned management class by using the archmc option.

Supported Clients
This command is valid for all clients.

Syntax
Query Mgmtclass
options

Parameters

Table 101. Query Mgmtclass command: Related options

Option Where to use
detail “Detail” on page 342 Command line only.
fromnode “Fromnode” on Command line only.
page 394

Examples
Task
Display default and available management classes.
Command: query mgmtclass

Chapter 11. Using commands 653

Query Node
The query node command displays all the nodes for which an administrative user ID has authority to
perform operations. You are prompted for the IBM Spectrum Protect administrator ID.
Ideally, the administrative user ID has at least client owner authority over the client workstation node
they are using either from the command line or from the web.
Use the type option to specify the type of node to filter for. The following are the valid values:
• nas
• client
• server
• any
The default is any.
Note: When the IBM Spectrum Protect for Virtual Environments: Data Protection for VMware license file is
installed on a vStorage backup server, the platform string that is stored on the IBM Spectrum Protect
server is set to "TDP VMware" for every nodename that is used on that machine. The platform string can
be used in the context of PVU calculations. If a nodename is being used to back up the machine with
standard Backup-Archive client functions (for example, file-level or image backup), then this platform
string would be interpreted as a "client" for the purposes of PVU calculations.
For more information about processor value units, see Estimating processor value units in the IBM
Spectrum Protect server documentation.

Supported Clients
This command is valid for all clients.

Syntax
Query Node
options

Parameters

Table 102. Query Node command: Related options

Option Where to use
type “Type” on page 534 Command line only.
scrolllines “Scrolllines” Client user options file (dsm.opt) or command line.
on page 487
scrollprompt Client user options file (dsm.opt) or command line.
“Scrollprompt” on page 488

Examples
Task
Display all NAS nodes.
Command: query node -type=nas
Task
Display all client nodes that are backup-archive clients.
Command: query node -type=client

654 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Related information
“Type” on page 534

Query Options
Use the query options command to display all or part of your options and their current settings that
are relevant to the command-line client.

Supported Clients
This command is valid for all clients.

Syntax
Query Options pattern
options

Parameters
pattern
An optional character string that can include wildcards. Use this argument to specify a subset of
options. The default is to display all options.

Table 103. Query Options command: Related options

Option Where to use
scrolllines “Scrolllines” Client user options file (dsm.opt) or command line.
on page 487
scrollprompt Client user options file (dsm.opt) or command line.
“Scrollprompt” on page 488

Examples
Task
Display all options and their values.

query options

Task
Display only options that begin with comm.

query options comm*

Task
Display the value of the replace option.

query options replace

Task
Issue the command to display all options and their values. The failover status information is
displayed.

query options

Output:

Chapter 11. Using commands 655

 MYPRIMARYSERVERNAME: SERVER1
MYREPLICATIONSERVER: TARGET
REPLSERVERNAME: TARGET
Address: 192.0.2.9
Port: 1501
SSLPort: 1502
GUID: 39.5a.da.d1.ae.92.11.e2.82.d3.00.0c.29.2f.07.d3
Used: yes

Related concepts
“Automated client failover configuration and use” on page 87
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
“Determining the status of replicated client data” on page 92
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.

Query Restore
The query restore command displays a list of your restartable restore sessions in the server database.
The list contains these fields: owner, replace, subdir, preservepath, source, and destination.
A restartable restore session is created when a wildcard restore command fails because of network
outage, client failure, server outage, or a similar problem. When such a failure occurs, the file space is
locked on the server and its files cannot be moved off the sequential volumes of the server. To unlock the
file space, either restart the restore and allow it to complete (query restore command), or cancel the
restore (cancel restore command). Use query restore to determine if you have any restartable
restore sessions and which file spaces are affected.

Supported Clients
This command is valid for all clients.

Syntax
Query Restore

Parameters
There are no parameters for this command.

Examples
Task
Display your restartable restore session in the server database.
Command: query restore

656 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Query Schedule
The query schedule command displays the events that are scheduled for your node. Your
administrator can set up schedules to perform automatic backups and archives for you. To plan your
work, use this command to determine when the next scheduled events occur.

Supported Clients
This command is valid for all clients.

Syntax
Query SChedule

Parameters
There are no parameters for this command.

Examples
Task
Display your scheduled events.
Command: query schedule

Query Session
The query session command displays information about your session, including the current node
name, when the session was established, server information, and server connection information.

Supported Clients
This command is valid for all clients.

Syntax
Query SEssion

Parameters
There are no parameters for this command.

Examples
Task
Display your session information.
Command: query session
A sample query session display follows:

Server Name.............: HALLEY_SERVER1

Server Type.............: Windows
Archive Retain Protect..: "No"
Server Version..........: Ver. 6, Rel. 2, Lev. 0.0
Last Access Date........: 09/03/2009 09:08:13
Delete Backup Files.....: "No"
Delete Archive Files....: "Yes"
Deduplication...........: "Server Only"

Chapter 11. Using commands 657

 Node Name...............: HALLEY
User Name...............:

Possible client-side deduplication values:

• None
– Displayed when connected to a pre V6.1 IBM Spectrum Protect server
• Server Only
• Client Or Server
Task
A sample query session display with LAN-free enabled follows:

IBM Spectrum Protect Server Connection Information

Server Name.............: TEMPLAR

Server Type.............: AIX
Archive Retain Protect..: "No"
Server Version..........: Ver. 6, Rel. 1, Lev. 4.0
Last Access Date........: 08/12/10 22:10:15
Delete Backup Files.....: "No"
Delete Archive Files....: "Yes"

Node Name...............: LAN2

User Name...............: root

Storage Agent Name......: TEMPLAR_STA

Storage Agent Type......: AIX
Storage Agent Version...: Ver. 6, Rel. 1, Lev. 3.3

Query Systeminfo
Use the query systeminfo command to gather information and output this information to a file or the
console.
This command is intended primarily as an aid for IBM support to help diagnosing problems. However,
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 can be difficult to read due to length and line-wrapping. If
the console output is difficult to read, use the filename option with the query systeminfo command.
This combination allows the output to be written to a file that can be submitted to IBM support.

Supported Clients
This command is valid for all clients.

Syntax

Query SYSTEMInfo item

options

Parameters
item
Specifies one or more items from which you want to gather information and output the information to
the file name that you specify with the filename option or to the console. The default is to gather all
items.
You can gather information on one or more of the following items:

658 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 • DSMOPTFILE - The contents of dsm.opt file.
• DSMSYSFILE - The contents of the dsm.sys file.
• ENV - Environment variables.
• ERRORLOG - The client error log file.
• FILE - Attributes for the file name that you specify.
• INCLEXCL - Compiles a list of include-exclude in the order in which they are processed during backup
and archive operations.
• OPTIONS - Compiled options.
• OSINFO - Name and version of the client operating system (includes ULIMIT information for UNIX).
• POLICY - Policy set dump.
• SCHEDLOG - The contents of the schedule log (usually dsmsched.log).
• CLUSTER - AIX cluster information.
• ENCRYPT - Available encryption methods.
Note:
1. Use the filename option to specify a file name in which to store the information that is gathered from
the items you specify. If you do not specify a file name, by default the information is stored in the /
Library/Application Support/tivoli/tsm/client/ba/bin/dsminfo.txt file (for Mac OS X) or the dsminfo.txt
file (for other UNIX and Linux).
2. Use the console option if you want to output the information to the console.

Table 104. Query Systeminfo command: Related options

Option Where to use
console “Console” on page Command line only.
328
filename “Filename” on Command line only.
page 389

Examples
Task
Gather and store the contents of the dsm.opt file and the IBM Spectrum Protect error log file in the
tsminfo.txt file.
Command: query systeminfo dsmoptfile errorlog -filename=tsminfo.txt
Related information
“Filename” on page 389
“Console” on page 328

Query VM
Use the query VM command to list and verify the successful backups of virtual machines (VMs).

Query VM for VMware virtual machines

Use the query vm command to determine which VMware virtual machines were backed up.

Supported Clients
This command is valid on Linux clients that are installed on a vStorage backup server.

Chapter 11. Using commands 659

 Syntax
Query VM vmname
BOTH options

-FROM SERVER

LOCAL

Parameters
vmname
Specifies the virtual machine host name that you want to query. If you omit the virtual machine name,
the command displays all VM backups on the IBM Spectrum Protect server.
-FROM
Specifies the backup location or locations to query. You can specify one of the following values:
SERVER
The query is limited to backups that are on the IBM Spectrum Protect server.
LOCAL
The query is limited to persisted snapshots that are on the hardware storage.
BOTH
The query lists information for both backups that are on the IBM Spectrum Protect server and
snapshots that are on the hardware storage. This value is the default.

Table 105. Query VM command: Related options for VMware virtual machine queries.
Option Where to use
detail “Detail” on page 342 Command line.
Valid for vmbackuptype=fullvm

inactive “Inactive” on page 401 Command line.

Valid for vmbackuptype=fullvm

pitdate “Pitdate” on page 452 Command line.

Valid for vmbackuptype=fullvm

pittime “Pittime” on page 453 Command line.

Valid for vmbackuptype=fullvm

vmbackuptype “Vmbackuptype” on page 544 Command line or client options file.

vmchost “Vmchost” on page 545 Command line or client options file.
vmcpw “Vmcpw” on page 546 Command line or client options file.
vmcuser “Vmcuser” on page 548 Command line or client options file.

Query VM examples (VMware)

The following are examples of using the query VM command and the command with the -detail
option.

660 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Full VM

q vm devesx04-24 -ina
Query Virtual Machine for Full VM backup

# Backup Date Mgmt Class Size Type A/I Location Virtual

Machine
--- ------------------- ---------- ----------- ------ --- --------
---------------
1 12/07/2016 14:45:24 DDMGMT 47.85 GB IFFULL I SERVER
devesx04-24
2 12/14/2016 17:38:05 DDMGMT 47.85 GB IFINCR A SERVER
devesx04-24
3 01/23/2017 14:07:44 DDMGMT 47.85 GB SNAPSHOT I LOCAL
devesx04-24
4 02/01/2017 08:59:52 DDMGMT 47.85 GB SNAPSHOT A LOCAL
devesx04-24
ANS1900I Return code is 0.

Chapter 11. Using commands 661

 Full VM with -detail option

q vm devesx04-24 -ina -detail

Query Virtual Machine for Full VM backup
# Backup Date Mgmt Class Size Type A/I Location Virtual
Machine
--- ------------------- ---------- ----------- ------ --- --------
---------------
1 12/07/2016 14:45:24 DDMGMT 47.85 GB IFFULL I SERVER
devesx04-24
The size of this incremental backup: n/a
The number of incremental backups since last full: 0
The amount of extra data: 0
The IBM Spectrum Protect objects fragmentation: 0
Backup is represented by: 79 TSM objects
Application protection type: VMware
Snapshot type: VMware Tools
Disk[1]Label: Hard Disk 1
Disk[1]Name: [TSMXIV11:vVOL_JOANNE]
rfc4122.750c6a3a-9c65-4a1f-9ed7-1b531aa204
af/devesx04-24-000003.vmdk
Disk[1]Status: Protected
Disk[2]Label: Hard Disk 2
Disk[2]Name: [TSMXIV11:vVOL_JOANNE]
rfc4122.750c6a3a-9c65-4a1f-9ed7-1b531aa204
af/devesx04-24_1-000003.vmdk
Disk[2]Status: Protected
Disk[3]Label: Hard Disk 3
Disk[3]Name: [TSMXIV11:vVOL_JOANNE]
rfc4122.750c6a3a-9c65-4a1f-9ed7-1b531aa204
af/devesx04-24_2-000003.vmdk
Disk[3]Status: Protected
2 12/14/2016 17:38:05 DDMGMT 47.85 GB IFINCR A SERVER
devesx04-24
The size of this incremental backup: 186.43 MB
The number of incremental backups since last full: 1
The amount of extra data: 0
The IBM Spectrum Protect objects fragmentation: 2
Backup is represented by: 119 TSM objects
Application protection type: VMware
Snapshot type: VMware Tools
Disk[1]Label: Hard Disk 1
Disk[1]Name: [TSMXIV11:vVOL_JOANNE]
rfc4122.750c6a3a-9c65-4a1f-9ed7-1b531aa204
af/devesx04-24-000006.vmdk
Disk[1]Status: Protected
Disk[2]Label: Hard Disk 2
Disk[2]Name: [TSMXIV11:vVOL_JOANNE]
rfc4122.750c6a3a-9c65-4a1f-9ed7-1b531aa204
af/devesx04-24_1-000006.vmdk
Disk[2]Status: Protected
Disk[3]Label: Hard Disk 3
Disk[3]Name: [TSMXIV11:vVOL_JOANNE]
rfc4122.750c6a3a-9c65-4a1f-9ed7-1b531aa204
af/devesx04-24_2-000006.vmdk
Disk[3]Status: Protected
3 01/23/2017 14:07:44 DDMGMT 47.85 GB SNAPSHOT I LOCAL
devesx04-24
The size of this incremental backup: n/a
The number of incremental backups since last full: 0
The amount of extra data: 0
The IBM Spectrum Protect objects fragmentation: 0
Backup is represented by: 0 TSM objects
Application protection type: VMware
Snapshot type: VMware Tools

662 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 4 02/01/2017 08:59:52 DDMGMT 47.85 GB SNAPSHOT A LOCAL
devesx04-24
The size of this incremental backup: n/a
The number of incremental backups since last full: 0
The amount of extra data: 0
The IBM Spectrum Protect objects fragmentation: 0
Backup is represented by: 0 TSM objects
Application protection type: VMware
Snapshot type: VMware Tools
-----------------------------------------------------------------------------
All averages are calculated only for incremental forever backups displayed
above.
The average size of incremental backup: 186.43 MB
The average number of incremental backups since last full: 1
The average overhead of extra data: 0
The average objects fragmentation: 0
The average number of objects per backup: 49
ANS1900I Return code is 0.

Query all VMware virtual machines that were backed up using -vmbacktype=fullvm:

q vm * -vmbackuptype=fullvm

Related tasks
“Preparing the environment for full backups of VMware virtual machines” on page 199
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.

Restart Restore
The restart restore command displays a list of your restartable restore sessions in the server
database.
You can restart only one restartable restore session at a time. Run the restart restore command
again to restart further restores.
The restarted restore uses the same options that you used in the failed restore. The restarted restore
continues from the point at which the restore previously failed.
To cancel restartable restore sessions, use the cancel restore command. Use the restart restore
command when:
• Restartable restore sessions lock the file space at the server so that files cannot be moved off the
sequential volumes of the server.
• You cannot back up files that are affected by the restartable restore.
Options from the failed session supersede new or changed options for the restarted session.

Supported Clients
This command is valid for all clients.

Syntax
RESTArt Restore

Parameters
There are no parameters for this command.

Chapter 11. Using commands 663

 Examples
Task
Restart a restore.
Command: restart restore

Restore
The restore command obtains copies of backup versions of your files from the IBM Spectrum Protect
server, or inside a backup set.
To restore files, specify the directories or selected files, or select the files from a list. Restore files to the
directory from which you backed them up or to a different directory. The backup-archive client uses the
preservepath option with the subtree value as the default for restoring files.
Note:
1. On UNIX and Linux systems when a symbolic link is created its modification time is set to the current
system time and cannot be changed. So, when restoring a symbolic link its modification date and time
is set to the date and time of the restore, not to the date and time the link had when it was backed up.
As a result, the client backs up the symbolic link during the next incremental backup because its
modification time changed since the last backup.
If you set the subdir option to yes when you restore a specific path and file, the client recursively
restores all subdirectories under that path, and any instances of the specified file that exist under any of
those subdirectories.
When you restore an entire directory or directory tree, and you do not specify the inactive, latest,
pick, todate, and fromdate options on the restore command, the client tracks which objects are
restored. If the restore process is interrupted for any reason, you can restart the restore at the point of
interruption by entering the restart restore command. It is possible to create more than one
restartable restore session. Restores are only restartable if the file specification is fully wildcarded. For
example, for a restore that is restartable, enter:

dsmc rest /home/* -sub=yes

For a restore that is not restartable, enter:

dsmc rest "/Users/user1/file?.c" -sub=yes

Use the query restore command to display a list of your restartable restore sessions in the server
database. Further backups of the file system cannot be performed unless the restartable restore
completes by using the restart restore command or is canceled by using the cancel restore
command.

dsmc rest "/Users/user1/file?.c" -sub=yes

Supported Clients
This command is valid for all clients.

664 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Syntax
FILE
REStore sourcefilespec
options "sourcefilespec"

destinationfilespec

BACKUPSETName= backupsetname

localfilename

tapedevice

LOCation= server

file

tape

Parameters
file
This parameter specifies that the source file specification is an explicit file name. This parameter is
required when you restore a file name from the current path, when you do not specify a relative or
absolute path, and when the file name conflicts with one of the reserved restore command
keywords, such as restore backupset.
sourcefilespec
Specifies the path and file name in storage that you want to restore. Use wildcard characters to
specify a group of files or all the files in a directory.
{filespacename}
Specifies the file space (enclosed in braces) on the server that contains the files you want to restore.
This is the name on the workstation drive from which the files were backed up.
Specify the file space name if the drive label name has changed or if you are restoring files that were
backed up from another node that had drive labels that are different from yours.
destinationfilespec
Specifies the path and file name where you want to place the restored files. If you do not specify a
destination, the client restores the files to the original source path.
• If the sourcefilespec names a single file, the destinationfilespec can be a file or a directory. If you are
restoring a single file, you can optionally end the specification with a file name if you want to give
the restored file a new name.
• If the sourcefilespec is wildcarded or subdir=yes is specified, the destinationfilespec must be a
directory and end with a directory delimiter (\).
Note: If the destination path or any part of it does not exist, the client creates it.
Note: If you do not specify a destination, the client determines whether the original file system can be
reached. If the original file system cannot be reached, the client will not restore the file. In this case,
you can specify a different destination and try the command again.
BACKUPSETName=
Specifies the name of a backup set. This parameter is optional. If you specify the backupsetname
parameter with the restore command, you cannot use the pick option.
The value of backupsetname depends on the location of the backup set, and corresponds to one of
the following options:

Chapter 11. Using commands 665

 backupsetname
Specifies the name of the backup set from the IBM Spectrum Protect server. If the location
parameter is specified, you must set -location=server. If the backup set resides in IBM
Spectrum Protect server storage, the backup set must have a TOC.
localfilename
Specifies the file name of the first backup set volume. You must set -location=file.
tapedevice
Specifies the name of the tape device that contains the backup set volume. You must use a
Windows-provided device driver, not the device driver that is provided by IBM. You must set -
location=tape.
LOCation=
Specifies where the client searches for the backup set. If you do not specify the location parameter,
the client searches for backup sets on the IBM Spectrum Protect server.
server
Specifies that the client searches for the backup set from the server. This is the default location.
file
Specifies that the client searches for the backup set from a local file.
tape
Specifies that the client searches for the backup set from a local tape device.

Table 106. Restore command: Related options

Option Where to use
dateformat “Dateformat” Client user options file (dsm.opt) or command line.
on page 334
dirsonly “Dirsonly” on Command line only.
page 346
filelist “Filelist” on page Command line only.
387
filesonly “Filesonly” on Command line only.
page 390
followsymbolic Client user options file (dsm.opt) or command line.
“Followsymbolic” on page
391
fromdate “Fromdate” on Command line only.
page 393
fromnode “Fromnode” on Command line only.
page 394
fromowner “Fromowner” on Command line only.
page 395
fromtime “Fromtime” on Command line only.
page 395
ifnewer “Ifnewer” on page Command line only.
399
inactive “Inactive” on Command line only.
page 401
latest “Latest” on page Command line only.
427

666 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 106. Restore command: Related options (continued)
Option Where to use
numberformat Client user options file (dsm.opt) or command line.
“Numberformat” on page
445
pick Command line only.
Note: If you specify the
backupsetname parameter
with the restore command,
you cannot use the pick
option.
“Pick” on page 451
pitdate “Pitdate” on page Command line only.
452
pittime “Pittime” on page Command line only.
453
preservepath Command line only.
“Preservepath” on page 458
replace “Replace” on page Client user options file (dsm.opt) or command line.
466
subdir “Subdir” on page Client user options file (dsm.opt) or command line.
515
tapeprompt “Tapeprompt” Client user options file (dsm.opt) or command line.
on page 520
timeformat “Timeformat” Client user options file (dsm.opt) or command line.
on page 528
todate “Todate” on page Command line only.
532
totime “Totime” on page Command line only.
532

Examples
Task
Restore a single file named budget in the /Users/user1/Documents directory.
restore /home/devel/projecta/budget
Task
Restore a single file named budget, which exists in the current directory.
restore file budget
Task
Restore all files with a file extension of .c from the /home/devel/projecta directory.
restore "/home/devel/projecta/*.c"
Task
Restore files in the /user/project directory. Use the pick and inactive options to select active
and inactive backup versions.
restore "/user/project/*" -pick -inactive

Chapter 11. Using commands 667

 Task
Restore all files from the /home/devel/projecta directory that end with the character .c to the /
home/newdevel/projectn/projecta directory. If the projectn or the projectn/projecta
directory does not exist, it is created.
restore "/home/devel/projecta/*.c" /home/newdevel/projectn/
Task
Restore all files in the /home/mydir directory to their state as of 1:00 PM on August 17, 2002.
restore -pitd=8/17/2002 -pitt=13:00:00 /home/mydir/
Task
Restore all objects in the /home/myid/ directory. Since this restore operation is fully wildcarded, if
the restore process is interrupted, a restartable restore session is created.
res "/home/myid/*"
Task
Restore all files in the /home/mydir directory to their state as of 1:00 PM on August 17, 2002.
restore -pitd=8/17/2002 -pitt=13:00:00 /home/mydir/
Related information
“Restore data from a backup set” on page 216
“Preservepath” on page 458
“File system and ACL support” on page 151

Restore from file spaces that are not Unicode-enabled

If you want to restore from file spaces that are not Unicode-enabled, you must specify the source on the
server and a destination on the client, prior to installing the Unicode-enabled client.
Note: This Unicode section applies only to Mac OS X.
For example, assume that Jaguar is the name of your startup disk and you back up all of the .log files in
the /Users/user5/Documents directory. Before the backup takes place, the server renames the file
space to Jaguar_OLD. The backup places the data specified in the current operation into the Unicode-
enabled file space named /. The new Unicode-enabled file space now contains only the /Users/user5/
Documents directory and the *.log files specified in the operation.
If you want to restore a file from the renamed (old) file space to its original location, you must enter both
the source and destination as follows:

restore Jaguar_OLD/Users/user5/Documents
/mylog.log /Users/user5/Documents/

Restore Backupset
The restore backupset command restores a backup set from the IBM Spectrum Protect server, a
local file, or a local tape device. You can restore the entire backup set, or, in some cases, specific files
within the backup set.

Supported Clients
This command is valid for all clients.

668 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Syntax
REStore Backupset
sourcefilespec
{filespacename}

-BACKUPSETName=
destinationfilespec options

backupsetname

localfilename -LOCation= server

tapedevice file

tape

Parameters
{filespacename}
Specifies the file space (enclosed in braces) on the server that contains the files you want to restore.
This is the name on the workstation drive from which the files were backed up, or the virtual file space
name for a group.
Specify a file space name when you restore a backup set containing a group.
Specify a file space name when the sourcefilespec does not exist on the target computer. This can
occur if the drive label name has changed or if you are restoring files that were backed up from
another node that had drive labels that are different from yours.
sourcefilespec
Specifies the source path of a portion of the backup set. The default is to restore the entire backup
set.
destinationfilespec
Specifies the destination path for the restored files. If you do not specify a sourcefilespec, you cannot
specify a destinationfilespec. If you do not specify a destination, the backup-archive client restores
the files to the original source path. If you are restoring more than one file, you must end the file
specification with a directory delimiter (/), otherwise, the client assumes that the last name is a file
name and reports an error. If you are restoring a single file, you can optionally end the destination file
specification with a file name if you want to give the restored file a new name. When the
sourcefilespec does not exist on the target workstation, you must specify destinationfilespec.
-BACKUPSETName=
Specifies the name of the backup set from which to perform a restore operation. You cannot use
wildcard characters to specify the backup set name. The value of backupsetname depends on the
location of the backup set, and corresponds to one of the following three choices:
backupsetname
Specifies the name of the backup set on the server from which to perform a restore operation. If
location option is specified, you must set -location=server.
localfilename
Specifies the file name of the first backup set volume. You must set -location=file.
tapedevice
Specifies the name of the tape device containing the backup set volume. You must use a
Windows-provided device driver, not the device driver that is provided by IBM. You must set -
location=tape.
-LOCation=
Specifies the location of the backup set. If you do not specify the location parameter, the client
searches for backup sets on the IBM Spectrum Protect server. If you specify the location parameter,
the value must be one of the following three choices:

Chapter 11. Using commands 669

 server
Specifies that the backup set is on the IBM Spectrum Protect server. Server is the default
location.
file
Specifies that the backup set is on an available file system.
tape
Specifies that the backup set is on an available tape device.

Table 107. Restore Backupset command: Related options

Option Where to use
dirsonly “Dirsonly” on Command line only.
page 346
filesonly “Filesonly” on Command line only.
page 390
ifnewer “Ifnewer” on page Command line only.
399
preservepath Command line only.
“Preservepath” on page 458
quiet “Quiet” on page 464 Client user options file (dsm.opt) or command line.
replace “Replace” on page Client user options file (dsm.opt) or command line.
466
subdir “Subdir” on page Client user options file (dsm.opt) or command line.
515

Examples
Task
Restore the entire backup set called monthly_financial_data.87654321 from the server.

dsmc restore backupset

-backupsetname=monthly_financial_data.87654321
-loc=server

Task
Restore the entire backup set contained in the file: /home/budget/weekly_budget_data.ost.

dsmc restore backupset

-backupsetname="/home/budget/weekly_budget_data.ost"
-loc=file

Task
Restore the entire backup set from the /dev/rmt0 device.

dsmc restore backupset

"-backupsetname=/dev/rmt0" -loc=tape

Task
Restore a single file named /home/jones/budget.dev from the /dev/rmt0 tape device, to the
original source path.

dsmc restore backupset

-backupsetname=/dev/rmt0 "/home/jones/budget.dev"
-loc=tape

670 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Task
Restore all files in the budget directory that contain a file extension of .txt from the tapes on
the /dev/rmt0 device, to the original source path.

dsmc restore backupset "/home/budget/*.txt"

-backupsetname=/dev/rmt0 -loc=tape

Task
Restore the entire backup set contained in local file named "/home/jones/bset01.file"

dsmc restore backupset

-backupsetname="/home/jones/bset01.file"
-loc=file

Task
Restore groups from the backup set mybackupset.12345678 on the IBM Spectrum Protect server
to the /home/devel/projectb directory. The groups' virtual file space is accounting.

dsmc restore backupset {/accounting}/*

/home/devel/projectb/
-backupsetname=mybackupset.12345678 -loc=server
-subdir=yes
Task
Restore groups from the local backup set mybackupset.ost to the /home/devel/projectb/
directory. The groups' virtual file space is accounting.

dsmc restore backupset {/accounting}/*

/home/devel/projectb/
-backupsetname=mybackupset.ost
-loc=server -subdir=yes

Related information
“Restore data from a backup set” on page 216

Restore backup sets: considerations and restrictions

This topic lists some considerations and restrictions that you must be aware of when restoring backup
sets.

Backup set restore considerations

Consider the following when restoring backup sets:
• 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.
• 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.
• 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.
• 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.

Chapter 11. Using commands 671

 - Use the subdir option to include subdirectories.
• 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.
• If a backup set contains files from several owners, the backup set itself is owned by the root user ID,
and non-root user IDs cannot see the backup set. In this case, non-root user IDs can restore their files
by obtaining the backup set name from the IBM Spectrum Protect administrator. Non-root users can
restore only their own files.
• 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:
• A backup set data that was backed up with the API cannot be restored or used.
• 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.
• 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 428
The localbackupset option specifies whether the backup-archive client GUI bypasses initial logon with
the IBM Spectrum Protect server to restore a local backup set on a standalone workstation.
“Restore” on page 664
The restore command obtains copies of backup versions of your files from the IBM Spectrum Protect
server, or inside a backup set.
“Restore Image” on page 677
The restore image command restores a file system or raw volume image that was backed up using the
backup image command.
“Restore Backupset” on page 668
The restore backupset command restores a backup set from the IBM Spectrum Protect server, a
local file, or a local tape device. You can restore the entire backup set, or, in some cases, specific files
within the backup set.

Restore backup sets in a SAN environment

You can restore backup sets in a storage area network (SAN) in the following ways:
• If the backup set is on a SAN-attached storage device, specify the device using the filename parameter
and use the location=tape option, where applicable. The backup-archive client restores the backup
set directly from the SAN-attached storage device, gaining high-speed restore performance.
Note: You must ensure that the correct tape is mounted in the SAN-attached tape drive prior to issuing
the restore command. The backup-archive client will not initiate a SCSI autochanger to mount the
tape automatically.
• If the backup set is not on local media or a SAN-attached storage device, you can specify the backup set
using the backupsetname option. Use the location=server option to restore the backup set directly
from the server using the LAN.

Restore Backupset without the backupsetname parameter

The restore backupset command can be used without the backupsetname parameter.
The preferred syntax for restore backupset command requires the backupsetname parameter.
Before the introduction of the backupsetname parameter, the backup-archive client restored backup

672 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
sets with a different syntax. The previous syntax is supported, but whenever possible, follow the syntax
that requires the backupsetname parameter. The previous syntax is documented for those cases when it
cannot be replaced by the preferred syntax.

Supported Clients
This command is valid for all clients.

Syntax
REStore Backupset
sourcefilespec
{filespacename}

backupsetname
destinationfilespec options localfilename

tapedevice

LOCation= server

file

tape

Parameters
options
All options that are valid with the preferred syntax of restore backupset are valid with the
previous syntax of restore backupset.
{filespacename}
Specifies the file space (enclosed in braces) on the server that contains the files you want to restore.
This is the name on the workstation drive from which the files were backed up, or the virtual file space
name for a group.
Specify a file space name when you restore a backup set containing a group.
Specify a file space name when the sourcefilespec does not exist on the target computer. This can
occur if the drive label name has changed or if you are restoring files that were backed up from
another node that had drive labels that are different from yours.
sourcefilespec
Specifies the source path of a portion of the backup set. The default is to restore the entire backup
set.
destinationfilespec
Specifies the destination path for the restored files. If you do not specify a sourcefilespec, you cannot
specify a destinationfilespec. If you do not specify a destination, the client restores the files to the
original source path. If you are restoring more than one file, you must end the file specification with a
directory delimiter (/), otherwise, the client assumes that the last name is a file name and reports an
error. If you are restoring a single file, you can optionally end the destination file specification with a
file name if you want to give the restored file a new name. When the sourcefilespec does not exist on
the target workstation, you must specify the destinationfilespec.
backupsetname
Specifies the name of the backup set from the IBM Spectrum Protect server. If the location
parameter is specified, you must set -location=server.
localfilename
Specifies the file name of the first backup set volume. You must set -location=file.

Chapter 11. Using commands 673

 tapedevice
Specifies the name of the tape device containing the backup set volume. You must use a Windows-
provided device driver, not the device driver that is provided by IBM. You must set -location=tape.
LOCation=
Specifies the location of the backup set. If you do not specify the location parameter, the client
searches for backup sets on the IBM Spectrum Protect server. If you specify the location parameter,
the value must be one of the following three choices:
server
Specifies that the backup set is on the server. Server is the default location.
file
Specifies that the backup set is on an available file system.
tape
Specifies that the backup set is on an available tape device.

Examples
Task
Restore the entire backup set called monthly_financial_data.87654321 from the server.
dsmc restore backupset monthly_financial_data.87654321 -loc=server
Task
Restore the entire backup set contained in the file: /home/budget/weekly_budget_data.ost.
dsmc restore backupset "/home/budget/weekly_budget_data.ost" -loc=file
Task
Restore the entire backup set from the /dev/rmt0 device.
dsmc restore backupset "/dev/rmt0" -loc=tape
Task
Restore a single file named /home/jones/budget.dev from the /dev/rmt0 tape device, to the
original source path.
dsmc restore backupset /dev/rmt0 "/home/jones/budget.dev" -loc=tape
Task
Restore all files in the budget directory that contain a file extension of .txt from the tape(s) on
the /dev/rmt0 device, to the original source path.
dsmc restore backupset /dev/rmt0 "/home/budget/*.txt" -loc=tape
Task
Restore the entire backup set contained in local file "/home/jones/bset01.file"
dsmc restore backupset "/home/jones/bset01.file" -loc=file
Task
Restore groups from the backup set mybackupset.12345678 on the IBM Spectrum Protect server
to the /home/devel/projectb directory. The groups' virtual file space is accounting.
dsmc restore backupset mybackupset.12345678 {/accounting}/* /home/devel/
projectb/ -loc=server -subdir=yes
Task
Restore groups from the local backup set mybackupset.ost to the /home/devel/projectb/
directory. The groups' virtual file space is accounting.
dsmc restore backupset mybackupset.ost {/accounting}/* /home/devel/projectb/
-loc=server -subdir=yes
Related information
“Restore data from a backup set” on page 216

674 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Restore Group
Use the restore group command to restore specific members or all members of a group backup.
Note:
1. Use the pick option to display a list of groups from which you can select one group to restore.
2. Use the showmembers option with the pick option to display and restore one or more members of a
group. In this case, you first select the group from which you want to restore specific members, then
you select one or more group members to restore.
3. You can restore a group from a backup set.

Supported Clients
This command is valid for all clients, except Mac OS X.

Syntax
REStore GRoup source
options destination

Parameters
source
Specifies the virtual file space name and the group name on the server that you want to restore.
destination
Specifies the path where you want to place the group or one or more group members. If you do not
specify a destination, the client restores the files to their original location.

Table 108. Restore Group command: Related options

Option Where to use
backupsetname Command line only.
“Backupsetname” on page 318
followsymbolic Client options file (dsm.opt) or command line.
“Followsymbolic” on page 391
fromdate “Fromdate” on page Command line only.
393
fromnode “Fromnode” on page Command line only.
394
fromowner “Fromowner” on Command line only.
page 395
fromtime “Fromtime” on page Command line only.
395
ifnewer “Ifnewer” on page Command line only.
399
inactive “Inactive” on page Command line only.
401
latest “Latest” on page 427 Command line only.
pick “Pick” on page 451 Command line only.
pitdate “Pitdate” on page 452 Command line only.

Chapter 11. Using commands 675

 Table 108. Restore Group command: Related options (continued)
Option Where to use
pittime “Pittime” on page 453 Command line only.
preservepath “Preservepath” Command line only.
on page 458
replace “Replace” on page Client options file (dsm.opt) or command line.
466
showmembers Command line only.
“Showmembers” on page 493
(does not apply to Mac OS X)

subdir “Subdir” on page 515 Client user options file (dsm.opt) or command line.
tapeprompt “Tapeprompt” on Client user options file (dsm.opt) or command line.
page 520
todate “Todate” on page 532 Command line only.
totime “Totime” on page 532 Command line only.

Examples
Task
Restore all members in the /virtfs/group1 group backup to their original location on the client
system.
Command:

restore group /virtfs/group1

Task
Display all groups within the /virtfs virtual file space. Use the showmembers option to display a list
of group members from which you can select one or more to restore.
Command:

restore group /virtfs/

* -pick -showmembers

Task
Display a list of groups within the /virtfs virtual file space from which you can select one or more
groups to restore.
Command:

restore group /virtfs/* -pick

Related information
“Restore Backupset” on page 668

676 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Restore Image
The restore image command restores a file system or raw volume image that was backed up using the
backup image command.
The restore obtains the backup image from the IBM Spectrum Protect server, or inside a backup set from
the IBM Spectrum Protect server, when the backupsetname option is specified. This command can
restore an active base image, or a point-in-time base image, with associated incremental updates.
Note:
1. Using the incremental option with the restore image command to perform a dynamic image
backup is not supported.
2. If you use IBM Spectrum Protect HSM for Windows or IBM Spectrum Protect for Space Management,
and you restore a file system image backup and plan to run reconciliation, you must restore the files
that were backed up after the image backup. Otherwise, migrated files that were created after the
image backup expire from the HSM archive storage on the IBM Spectrum Protect server.
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, teh client 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.
Considerations:
• The API must be installed to use the restore image command.
• Image restore is not supported for the Sun QFS file system.
• Image restore is not supported for GPFS file systems on Linux x86_64, Linux on POWER and Linux on
System z.
• On Linux systems, some file systems such as ext2, ext3, ext4, btrfs, and xfs use a universally unique
identifier (UUID) to identify themselves to the operating system. If you create an image backup of such
a volume and you restore it to a different location, you might have two volumes with the same UUID. If
you use UUID to define your file systems in /etc/fstab, be aware that the backup-archive client might
be unable to correctly mount the restored file system because the UUIDs conflict. To avoid this
situation, restore the image to its original location. If you must restore it to a different location, change
the UUID of either the original or restored volume before you mount the restored file system. Refer to
the Linux documentation for instructions on how to change a UUID. You might also need to manually
edit the /etc/fstab file so the original volume, the restored volume, or both volumes can be mounted.
• If you use the pick option, the following information is displayed for file system images that were
backed up by the client:
– Image Size
– Stored Size - This value is the actual image size that is stored on the IBM Spectrum Protect server.
The stored image on the server is the same size as the volume capacity.
– File system type
– Backup date and time
– Management class that is assigned to image backups
– Whether the image backup is an active or inactive copy
– The image name
• If for some reason a restored image is corrupted, you can use the fsck tool to attempt to repair the
image.

Chapter 11. Using commands 677

 Supported Clients
This option is valid for AIX, Linux, and Oracle Solaris clients.

Syntax
REStore Image sourcefilespec
options "sourcefilespec"

destinationfilespec

Parameters
sourcefilespec
Specifies the name of a source image file system to be restored. Only a single source image can be
specified; you cannot use wildcard characters.
destinationfilespec
Specifies the name of an existing mounted file system or the path and file name to which the source
file system is restored. The default is the original location of the file system.

Table 109. Restore Image command: Related options

Option Where to use
backupsetname Command line only.
“Backupsetname” on page
318
dateformat “Dateformat” Client user option file (dsm.opt) or command line.
on page 334
deletefiles “Deletefiles” Command line only.
on page 340
fromnode “Fromnode” on Command line only.
page 394
fromowner “Fromowner” on Command line only.
page 395
imagetofile “Imagetofile” Command line only.
on page 401
inactive “Inactive” on Command line only.
page 401
incremental “Incremental” Command line only.
on page 421
noprompt “Noprompt” on Command line only.
page 443
pick “Pick” on page 451 Command line only.
pitdate “Pitdate” on page Command line only.
452
pittime “Pittime” on page Command line only.
453
timeformat “Timeformat” Client user option file (dsm.opt) or command line.
on page 528

678 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 109. Restore Image command: Related options (continued)
Option Where to use
verifyimage “Verifyimage” Command line only.
on page 539

The restore image command does not define or mount the destination file space. The destination
volume must exist, must be large enough to hold the source, and if it contains a file system, must be
mounted. If an image backup contains a file system, and you restore them to a different location, be
aware of the following points:
• If the destination volume is smaller than the source volume, the operation fails.
• If the destination volume is larger than the source, after the restore operation you lose the difference
between the sizes. The lost space can be recovered by increasing the size of the volume, which also
increases the size of the restored volume.

Examples
Task
Restore the /home/test directory over which the logical volume is mounted, to its original location.
Command: dsmc rest image /home/test
Task
Restore the /home/proj directory over which the logical volume is mounted, to its original location
and apply the changes from the last incremental backup of the original image that is recorded on the
server. The changes include deletion of files.
Command: dsmc restore image /home/proj -incremental -deletefiles
Task
Restore the /usr file system to its original location. Use the verifyimage option to enable detection
of bad sectors on the target volume.
Command: dsmc restore image /usr -verifyimage
Task
If bad sectors present on the target volume, use the imagetofile option to restore the /usr file
system to the /home/usr.img file to avoid data corruption.
Command: dsmc restore image /usr /home/usr.img -imagetofile
Related information
“Verifyimage” on page 539
“Imagetofile” on page 401

Restore NAS
The restore nas command restores the image of a file system that belongs to a Network Attached
Storage (NAS) file server. When you are using an interactive command-line session with a non-
administrative ID, you are prompted for an administrator ID.
The NAS file server performs the outboard data movement. A server process performs the restore.
If you used the toc option with the backup nas command or the include.fs.nas option to save
Table of Contents (TOC) information for each file system backup, 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. If you do not save TOC information, you can still restore
individual files or directory trees with the RESTORE NODE server command, if you know the fully qualified
name of each file or directory and the image in which that object was backed up.

Chapter 11. Using commands 679

 Use the nasnodename option to specify the node name for the NAS file server. The NAS node name
identifies the NAS file server to the IBM Spectrum Protect server. You must register the NAS node name
at the server. Place the nasnodename option in your client system-options file (dsm.sys). The value in the
client system-options file is the default, but this value can be overridden on the command line.
You can use the pick option to display a list of NAS images that are owned by the NAS node you specify.
From this list, you can select one or more images to restore. If you select multiple images to restore with
the pick option, do not use the monitor option or you serialize the restores. To start multiple restore
processes simultaneously when you are restoring multiple images, do not specify monitor=yes.
Use the monitor option to specify whether you want to monitor a NAS file system image restore and
display processing information on your screen.
Use the monitor process command to display a list of current restore processes for all NAS nodes for
which your administrative user ID has authority. 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.
Use the cancel process command to stop NAS restore processing.
Regardless of client platform, NAS file system specifications use the forward slash (/) separator, as in this
example: /vol/vol0.

Supported Clients
This command is valid for AIX, and Solaris clients only.

Syntax
REStore NAS sourcefilespec
options

destinationfilespec

Parameters
sourcefilespec
Specifies the name of the NAS file system image you want to restore. This parameter is required
unless you use the pick option to display a list of NAS images from which to choose. You cannot use
wildcard characters when you specify the sourcefilespec.
destinationfilespec
Specifies the name of an existing mounted file system on the NAS device over which you want to
restore the image. This parameter is optional. The default is the original location of the file system on
the NAS device.

Table 110. Restore NAS command: Related options

Option Where to use
dateformat “Dateformat” Client user option file (dsm.opt) or command line.
on page 334
inactive “Inactive” on Command line only.
page 401
mode “Mode” on page 435 Command line only.
monitor “Monitor” on page Command line only.
438

680 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 Table 110. Restore NAS command: Related options (continued)
Option Where to use
nasnodename Client system options file (dsm.sys) or command line.
“Nasnodename” on page 440
numberformat Client user option file (dsm.opt) or command line.
“Numberformat” on page
445
pick “Pick” on page 451 Command line only.
pitdate “Pitdate” on page Command line only.
452
pittime “Pittime” on page Command line only.
453
timeformat “Timeformat” Client user option file (dsm.opt) or command line.
on page 528

Examples
Task
Restore the NAS file system image /vol/vol1 to the /vol/vol2 file system on the NAS file server called
nas1.
Command: restore nas -nasnodename=nas1 /vol/vol1 /vol/vol2
Task
Restore inactive NAS images.
Command: restore nas -nasnodename=nas2 -pick -inactive
Related information
“Nasnodename” on page 440
“Monitor” on page 438
“Cancel Process” on page 615

Restore VM
Use the restore vm command to restore a virtual machine (VM) that was previously backed up.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments.

Restore VM for VMware virtual machines

The restore vm command can be used to restore VMware virtual machines or VMware virtual machine
templates.
If the backup-archive client is installed on a separate system that is configured as a vStorage backup
server, you can restore full virtual machine backups to the ESX or ESXi server that they came from, or to a
different server. To restore a full virtual machine backup to a different server, use the HOST parameter.
The backup-archive client copies the data from the IBM Spectrum Protect server over either the LAN or
SAN. The client then writes the data directly to the ESX server, by using the transport method that is
specified in the client options file.

Chapter 11. Using commands 681

 Restoring a full virtual machine backup creates a new virtual machine; the configuration information and
content of the new machine is identical to what it was when the backup occurred. All virtual machine
disks are restored to the specified point-in-time, as virtual disks in the newly created virtual machine.
To create a new virtual machine, specify the vmname parameter and provide a name for the new virtual
machine. The vmname parameter creates a new virtual machine with a configuration that is identical to
what it was when the backup occurred.
Virtual machines are restored to their original resource pool, cluster, or folder if the containers exist.
During a restore operation, if the destination target (a vCenter or ESXi host) does not have the required
containers, the VM is restored to the top-level default location on the target ESXi host. If you use the
command-line client to restore a virtual machine, and if the virtual machine cannot be restored to its
original inventory location, an informational message (ANS2091I) is displayed. If you use the Java GUI to
restore a virtual machine, and if the virtual machine cannot be restored to its original inventory location,
the informational message is not displayed, but the virtual machine is still restored to the top-level
default location.
Data protection tags that were backed up with the run backup vm command are restored with the virtual
machine. Data protection tags are used to exclude virtual machines from backups and to specify the
retention policy of backups.

Supported Clients
This command is valid on supported Linux clients that are installed on a vStorage backup server for a
VMware virtual machine.

Syntax
;

vmname1,vmname2
REStore VM
VM=vmname1,vmname2

-VM=vmname1,vmname2

vmname:vmdk=all-vmdk

vmname:vmdk=cnfg

vmname:vmdk=disk_label

vmname:-vmdk=disk_label

VMHost=host1,host2

-VMNAme= newVMname -PREView options

*
<timestamp>

<date>

<time>

DATACENTER="myDatacenter"

HOST="myHost"

DATASTORE="myDatastore"

destinationfilespec

682 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Parameters
Any parameter that contains spaces must be enclosed in quotation marks (" ").
vmname
Specify the name of one or more virtual machines that you want to restore. The name is the virtual
machine display name. Separate multiple VM names with commas (for example, vm1,vm2,vm5). If
you backed up template VMs, the vmname parameter can specify the name of a template VM to
restore.
Wildcard characters can be used to select VMs names that match a pattern. An asterisk (*) matches
any sequence of characters. A question mark (?) matches any single character. For example:
• restore vm VM_TEST* restores all VMs that have names that begin with "VM_TEST".
• restore vm VM?? restores any VM that has a name that begins with the letters "VM", followed by
2 characters.
Specifying one or more VMs to restore is required.
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.
Wildcard characters can be used in VM names. For the specification of the vmname parameter, see
“vmname” on page 683 .
In the following example, vm= is specified and commas are used to separate two machine names.

restore vm vm=my_vm1,my_vm2

-vm=vmname
You can exclude a virtual machine from a restore operation by specifying the exclude operator (-)
before the vm= keyword.
Use the -vm= keyword to exclude a list of virtual machines from a larger group of VM backups, such as
a group of VMs that begin with a VM name pattern. For example, if you need to restore all the VMs that
start with Dept99_ but prevent vm2 from being restored, issue the following command:

restore vm vm=Dept99_*;-vm=vm2

Wildcard characters can be used with the -vm= keyword to exclude VM names that match a pattern.
For example:
• Exclude all files that have test in the host name:

-vm=*test*

• Include all virtual machines with names such as: test20, test25, test29, test2A:

vm=test2?

Note: You cannot use the exclude operator (-) to exclude a VM host domain. The exclude operator
works only at the virtual machine name level.
vmname:vmdk=all-vmdk
This option specifies that all virtual disks (*.vmdk files) are included when the virtual machine is
restored. This parameter is the default for vmdk specifications.
Note: This parameter is not valid for restoring VMware virtual machines that were backed up using
VCB.
vmname:vmdk=cnfg
This option specifies that the virtual machine configuration information is restored. The configuration
information is always restored when a new virtual machine is created. However, by default the
configuration is not restored when you update an existing virtual machine with selected virtual disks.

Chapter 11. Using commands 683

 Ordinarily, restoring configuration information to an existing virtual machine fails because the
restored configuration information conflicts with the existing virtual machine configuration
information. Use this option if the existing configuration file for a virtual machine on the ESXi server
has been deleted, and you want to use the backed-up configuration to re-create it.
Note: This parameter is not valid for restoring VMware virtual machines that were backed up using
VCB.
vmname:vmdk=disk_label
This option is used to specify the disk label of a virtual disk to include in the restore operation. Specify
this option only if you want to restore one or more specific disks, but not all disks. Repeat this option
for each disk you want to restore.
The following considerations apply to each disk that you want to restore:
• The disk must exist on the VM before you initiate the restore operation. If the disk does not exist,
you must create it. You can use the -preview parameter to identify the original disk label, capacity,
and datastore. The -preview output does not include provisioning information.
• The existing disk must be at least as large as the disk you want to restore.
• The existing disk label must be the same as the disk you want to restore.
• Any data on the existing disk is overwritten.
Only the specified disks are restored. Other disks on the VM are not altered.
The VM that you are restoring the disk to must be powered off before you initiate the restore
operation.
Required: On the restore vm command, the label names of the vmdk files that you want to include
(with the vmname:vmdk=disk_label parameter) in a restore VM operation must be specified as the
English-language label name. The label name must be as it is displayed in the output of the -preview
parameter. Examples of the English vmdk labels are "Hard Disk 1", "Hard Disk 2", and so on.
Note: This parameter is not valid for restoring VMware virtual machines that were backed up using
VCB.
vmname:-vmdk=disk_label
This option is used to specify the disk label of one or more virtual disks to exclude from the restore
operation.
Required: On the restore vm command, the label names of the vmdk files that you want to include
(with the vmname:vmdk=disk_label parameter) in a restore VM operation must be specified as the
English-language label name. The label name must be as it is displayed in the output of the -preview
parameter. Examples of the English vmdk labels are "Hard Disk 1", "Hard Disk 2", and so on.
Note: This parameter is not valid for restoring VMware virtual machines that were backed up using
VCB.
vmhost=hostname
This option restores 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.
Separate multiple host names with commas (for example, host1,host2,host5).
This parameter can include multiple ESX servers that are separated by commas.
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 you backed up VM templates, they are included in the restore operation.
VMName=
Specifies the new name for the virtual machine after it is restored, if you do not want to use the name
specified by the VM= parameter.

684 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
newVMname
Specify a new VM name to use for the restored VM.
The following characters are not supported in names of restored VMs:

: ; ' \ / " ? , < > |

A restore command that includes unsupported characters will fail with error message ANS9117E.
VMware does not support VM names of greater than 80 characters in length.
*
Use the * (asterisk) symbol as a wildcard to represent the original name of the VM that is being
restored. Placing valid characters before or after the asterisk creates a prefix or suffix in the name
of the restored VM.
The following characters are not supported in names of restored VMs:

: ; ' \ / " ? , < > |

A restore command that includes unsupported characters will fail with error message ANS9117E.
VMware does not support VM names of greater than 80 characters in length.
You can use the * symbol in the following manner:
• Use the original VM name for the restored VM name by specifying vmname=*.
• Append a suffix to the original VM name for the restored VM. For example, if the original VM
name is VM1, you can append the suffix "_restored" to VM1 by specifying the following
command:

dsmc restore vm VM1 -VMName=*_restored

The name of the restored VM is VM1_restored.

• Insert a prefix before the original VM name for the restored VM. For example, if the original VM
name is VM2, you can insert the prefix "new_" to VM2 by specifying the following command:

dsmc restore vm VM2 -vmname=new_*

The name of the restored VM is new_VM2.

<timestamp>
Appends a timestamp with the date and time of the restore operation to the name of the restored
VM. The <timestamp> parameter is a keyword, and must include the bracket symbols ("<" and
">"). The format for the timestamp string is determined by the DATEFORMAT and TIMEFORMAT
options in the dsm.opt file. A dash is used as a delimiter for the timestamp that is returned by the
<timestamp> parameter.
For example, to restore two VMs named VM5 and VM6, and append the date and time of restore to
the restored VM names, issue the following command:

dsmc restore vm VM5,VM6 -vmn=*_<timestamp>

The names of the restored VMs are VM5_06-22-2017_14-56-55 and

VM6_06-22-2017_14-56-55.
<date>
Appends the date of the restore operation to the name of the restored VM. The <date> parameter
is a keyword, and must include the bracket symbols ("<" and ">"). The format of the date string is
determined by the DATEFORMAT option in the dsm.opt file. A dash is used as a delimiter for the
date that is returned by the <date> parameter.
For example, to insert the prefix "new_" before the VM named VM3, and append the restore date
to the restored VM name, issue the following command:

Chapter 11. Using commands 685

 dsmc restore vm VM3 -vmname=new_*_<date>

The name of the restored VM is new_VM3_06-22-2017.

<time>
Appends the time of the restore operation to the name of the restored VM. The <time> parameter
is a keyword, and must include the bracket symbols ("<" and ">"). The format of the time string is
determined by the TIMEFORMAT option in the dsm.opt file. A dash is used as a delimiter for the
time that is returned by the <time> parameter.
For example, to append the suffix "_today_" after the VM named VM8, and add the restore time to
the restored VM name, issue the following command:

dsmc restore vm VM8 -vmn=*_today_<time>

The name of the restored VM is VM8_today_14-56-55.

Note: This parameter is not valid for restoring VMware virtual machines that are backed up using VCB
or if the FROM parameter specifies LOCAL.
DATACENTER
Specifies the name of the data center to restore the virtual machine to as it is defined in the vSphere
vCenter. If the data center is contained in a folder, you must specify the -datacenter option when
you restore the virtual machine and include the folder structure of the data center in the data center
name. For example, the following syntax is valid:

-datacenter=folder_name/datacenter_name

When you restore a virtual machine by using the GUI, you must restore the virtual machine to a
different location. If you restore to the original location, you cannot specify the folder name of the
data center. Without a folder name to help locate the original data center, the restore operation fails.
Note: This parameter is not valid for restoring VMware virtual machines that were backed up using
VCB.
HOST
Specifies the domain name of the ESX host server to restore to as it is defined in the vSphere vCenter.
This parameter is case-sensitive and must be the same value as the host name that is shown in the
VMware vSphere Web Client. To confirm the host name in the vSphere Web client, select a host and
click Manage > Networking > TCP/IP configuration > DNS.
Note: This parameter is not valid for restoring VMware virtual machines that were backed up using
VCB.
DATASTORE
Specifies the VMware datastore to restore the virtual machine to. The datastore can be on a SAN,
NAS, iSCSI device, or VMware virtual volume (VVOL). You can specify only one datastore when you
restore a virtual machine. If you do not specify a datastore parameter, the virtual machine's VMDK
file is restored to the datastore it was on when the backup was created.
Note: This parameter is not valid for restoring VMware virtual machines that were backed up using
VCB.
-PREView
Use this parameter to verify the results of a restore operation without restoring any VMs. The -
preview parameter provides a list of VMs that will be restored and information about the VMs, such
as labels of the hard disks in the VM, and the management class for a VM.
When you issue the -preview parameter with the restore vm command, the restore operation
does not start. The restore operation starts only if the -preview parameter is removed from the
command.
For more information, see “Preview virtual machine restore operations” on page 691.

686 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 111. Restore VM command: Related options used for restoring VMware virtual machines
Option Where to use
datacenter Command line or options file. This parameter is not
valid for restoring VMware virtual machines that
were backed up using VCB.
datastore Command line or options file. This parameter is not
valid for restoring VMware virtual machines that
were backed up using VCB.
host Command line or options file. This parameter is not
valid for restoring VMware virtual machines that
were backed up using VCB.
inactive Command line.
pick Command line. This parameter is not valid for
restoring VMware virtual machines that were
backed up using VCB.
pitdate Command line. This parameter is not valid for
restoring VMware virtual machines that were
backed up using VCB.
pittime Command line. This parameter is not valid for
restoring VMware virtual machines that were
backed up using VCB.
vmbackdir Command line or client options file.
vmbackuplocation Command line.
vmbackuptype Command line or client options file.
vmchost Command line or client options file
vmcpw Command line or client options file
vmcuser Command line or client options file
vmdefaultdvportgroup Command line or client options file
vmdefaultdvswitch Command line or client options file
vmdefaultnetwork Command line or client options file
vmdiskprovision Command line or client options file.
This parameter is only valid when
instantrestore is specified for the
vmrestoretype value.

vmexpireprotect Command line or client options file.

This parameter is only valid when either
instantaccess or instantrestore is specified
for the vmrestoretype value.

vmiscsiadapter Command line or client options file.

This parameter is only valid when either
instantaccess or instantrestore is specified
for the vmrestoretype value.

Chapter 11. Using commands 687

 Table 111. Restore VM command: Related options used for restoring VMware virtual machines
(continued)
Option Where to use
vmmaxrestoresessions Command line or client options file.
vmmaxrestoreparalleldisks Command line or client options file.
vmmaxrestoreparallelvms Command line or client options file.
vmmountage Command line.
vmnoprdmdisks Command line or client options file.
vmnovrdmdisks Command line or client options file.
vmstoragetype Command line or client options file.
This parameter is only valid when either
instantaccess or instantrestore is specified
for the vmrestoretype value.

vmvstortransport Command line or client options file. This parameter

is not valid for restoring VMware virtual machines
that were backed up using VCB.

Tip about the final statistics: If you are running multiple restore sessions, the value that is displayed in
the Data transfer time field in the final statistics can be higher than the value in the Elapsed processing
time field. The data transfer time is the sum of the times that each restore operation takes to send data
across the network. This number does not include the time for the data mover to read the data from disk
before sending it, nor the time to wait for server transactions to complete. This number can be greater
than the elapsed processing time if the operation uses multiple concurrent sessions to move data, such
as multi-session restore operations. This value includes the time that it takes to send data more than
once due to retry operations.

Examples
Task
Restore the most recent backup version of myVM to its original name. Use the VMware management
interface to delete the original virtual machine, before you restore it using this syntax.

dsmc restore vm myvm

Task
Restore the most recent backup version of myvm to a new virtual machine that is created with the
name "Test Machine", and with the restore target for the data center, ESX host, and datastore all
specified on the command.

dsmc restore vm myvm -vmname="Test Machine"

-datacenter="myDatacenter" -host="myHostName"
-datastore="myDatastore"

Task
Restore the most recent backup version of myvm with the new name myvm_restored.

dsmc restore vm myvm -vmname="*_restored"

-datacenter="myDatacenter" -host="myHostName"
-datastore="myDatastore"

688 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Task
Restore the most recent backup version of myvm with a new name, showing date and time, similar to
myvm_03-22-2017_14-41-24.

dsmc restore vm myvm -vmname="*_<timestamp>"

-datacenter="myDatacenter" -host="myHostName"
-datastore="myDatastore"

Task
Restore the most recent backup version of myvm. Restore to a data center named mydatacenter. The
data center is within the vCenter; the relative path within the vCenter is dirA/datacenters/.

dsmc restore vm myvm -vmname="Test Machine"

-datacenter="dirA/datacenters/myDatacenter"
-host="myHostName" -datastore="myDatastore"

Task
Restore a virtual machine template back to the same location and name.

dsmc restore vm vmTemplateName

Task
Restore a virtual machine template to a new location.

dsmc restore vm vmTemplateName -vmname=newName

-datastore=newDatastore -host=newHost
-datacenter=newDatacenter

Task
Restore only Hard Disk 2 and Hard Disk 3 to the existing virtual machine that is named vm1.

dsmc restore vm "vm1:vmdk=Hard Disk 2:vmdk=Hard Disk 3"

Task
Restore all disks to the existing virtual machine named vm1, but do not restore the data from Hard
Disk 4.

dsmc restore vm "vm1:-vmdk=Hard Disk 4"

Task
Restore only the data from Hard Disk 1 to the existing virtual machine vm1; do not update any
configuration information.
Note: When you restore an existing virtual machine, the default behavior is to not update the
configuration information.

dsmc restore vm "vm1:vmdk=Hard Disk 1:-vmdk=cnfg"

Task
Restore all disks to the existing virtual machine named vm1.

dsmc restore vm "vm1:vmdk=all-vmdk"

This command updates all virtual disks on an existing virtual machine, named vm1. Note that this
action is different from the action that is performed by dsmc restore vm vm1, which creates a new
virtual machine named vm1 (vm1 must not exist in order for dsmc restore vm vm1 to succeed).
Task
Set a maximum of three sessions to be used for restore operations for virtual disks in the VM vm1:

dsmc restore vm vm1 -vmmaxrestoresessions=3

Chapter 11. Using commands 689

 Task
Restore the VM named Accounts and all VMs that begin with Dept99:

dsmc restore vm Accounts,Dept99*

Task
Restore all VMs that begin with the word "Payroll" but exclude any VMs that contain the word "temp"
in the name:

dsmc restore vm vm=Payroll*;-vm=*temp*

Task
Restore the virtual machines VM1, VM2, and VM3 with new VM names that are based on the original
VM names. Append the suffix "_restored_" and the date and time of the restore operation to the VM
name:

dsmc restore vm vm=VM1,VM2,VM3 -vmname=*_restored_<timestamp>

The restored VMs are named VM1_restored_07-28-2017_13-28-00,

VM2_restored_07-28-2017_13-28-00, and VM2_restored_07-28-2017_13-28-00.
Task
Restore all VMs from the host esx03 that were backed up to the IBM Spectrum Protect server, and of
all the VMs being restored, restore the VM named esx03-02 without the VM disk Hard Disk 1:

dsmc restore vm VMHOST=esx03.example.com;esx03-2:-vmdk=Hard Disk 1

Task
Restore all virtual machines on ESXi hosts named brovar, doomzoo, and kepler:

dsmc restore vm
vmhost=brovar.example.com,doomzoo.example.com,kepler.example.com

Task
Verify that the VM named Dept99_VM1 is restored correctly without restoring the VM:

dsmc restore vm VM=Dept99_VM1 -vmname=*_restored -preview

Important: For Windows virtual machines: 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.
For more information, see “INCLUDE.VMSNAPSHOTATTEMPTS” on page 416.
Related concepts
Virtual machine exclude options
Virtual machine include and exclude options influence the behavior of backup and restore operations for
virtual machines. These options are processed before any command-line options are processed, so that
options on the command line can override options specified on any of the virtual machine include options

690 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 or virtual machine exclude options. See the individual option descriptions for information about the
options.
Virtual machine include options
Virtual machine include and exclude options influence the behavior of backup and restore operations for
virtual machines. These options are processed before any command-line options are processed, so that
options on the command line can override options specified on any of the virtual machine include options
or virtual machine exclude options. See the individual option descriptions for information about the
options.
Related tasks
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.

Preview virtual machine restore operations

You can use the -preview parameter to verify the results of a restore operation without restoring any
virtual machines (VMs). The -preview parameter provides a list of VMs that will be restored and
information about the VMs. To understand how to use the -preview parameter with the restore vm
command, review information about the options that are displayed and examples of the restore vm -
preview command.
The -preview parameter returns options and their values only if the options override the default values
or if no default exists.
The options that are displayed depend on various factors:
• The following options apply to all VM restore operations:

VMNAME
DATACENTER
DATASTORE
HOST

• The following options are displayed when they are set in the client options file:

VMDEFAULTDVPORTGROUP
VMDEFAULTDVSWITCH
VMDEFAULTNETWORK

• The following option is always displayed only during previews of non-instant restore operations:

VMBACKDIR

The value that is returned for this option is the directory CTL files that are cached for both backup and
restore operations.
• The following options are displayed when set during previews of instant access restore operations:

VMDISKPROVISION
VMAUTOSTARTVM

When you issue the -preview parameter with the restore vm command, the restore operation does
not start. The restore operation starts only if the -preview parameter is removed from the command.

Examples
Task
Preview the operation to restore the VM named VM8, and exclude the disk Hard Disk 1. The VM is
restored to the ESXi host server esx03 with a new VM name that ends with -restore.

Chapter 11. Using commands 691

 The command also displays the port group for the NICs to use, the distributed virtual switch
(dvSwitch) that contains the port group, and the network for the NICs to use during the restore
operation.

dsmc restore vm "VM8:-vmdk:Hard Disk 1" -vmname="* -restore"

-vmdfaultdvportgroup=portgroup1 -vmdefaultdvswitch=switch1
-vmdefaultnetwork=network1 -host=esx03.example.com -preview

Command output:

Restore function invoked.

Restore VM command started. Total number of virtual machines to process: 1

1. VM Name: 'VM8'
Mode: 'Incremental Forever - Full'
Backup Time: IFFULL 05/22/2017 11:08:33

Disk 1 Label: 'Hard Disk 1'

Disk 1 Name: '[TSMV5K2:DS1_VMData (26TB)] VM8/TestVM8.vmdk'
Disk 1 Status: Excluded by user
Disk 1 Capacity: 42,949,672,960
Disk 1 Data to Send: 42,878,369,792

Disk 2 Label: 'Hard Disk 2'

Disk 2 Name: '[TSMV5K2:DS1_VMData (26TB)] VM8/TestVM8_1.vmdk'
Disk 2 Status: Selected
Disk 2 Capacity: 10,737,418,240
Disk 2 Data to Send: 10,737,418,240

Destination Name: 'VM8 -restore'

Destination Host: 'esx03.example.com'
Destination vPortGroup: 'portgroup1'
Destination Switch: 'switch1'
Destination Network: 'network1'
Destination CTL Folder: 'C:\mnt\tsmvmbackup'

Task
Preview the instant restore operation of the VM named VM8, which also excludes the disk Hard Disk
1. The VM is restored to the ESXi host server esx03 with a new VM name that ends with -restore.
The command also displays the port group for the NICs to use, the distributed virtual switch
(dvSwitch) that contains the port group, and the network for the NICs to use during the restore
operation. The new VM is provisioned as a thick VM and will be restarted automatically after the
restore operation.

restore vm "VM8:-vmdk=Hard Disk 1" -vmname="* -restore"

-vmdefaultdvportgroup=portgroup1 -vmdefaultdvswitch=switch1
-vmdefaultnetwork=network1 -host=esx03.storage.example.com
-vmrestoretype=instantrestore -vmdiskprovision=thick
-vmautostartvm=yes -preview

Command output:

692 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 1. VM Name: 'VM8'
Mode: 'Incremental Forever - Full'
Backup Time: IFFULL 05/22/2017 11:08:33

Disk 1 Label: 'Hard Disk 1'

Disk 1 Name: '[TSMV5K2:DS1_VMData (26TB)] VM8/TestVM8.vmdk'
Disk 1 Status: Excluded by user
Disk 1 Capacity: 42,949,672,960
Disk 1 Data to Send: 42,878,369,792

Disk 2 Label: 'Hard Disk 2'

Disk 2 Name: '[TSMV5K2:DS1_VMData (26TB)] VM8/TestVM8_1.vmdk'
Disk 2 Status: Selected
Disk 2 Capacity: 10,737,418,240
Disk 2 Data to Send: 10,737,418,240

Destination Name: 'VM8 -restore'

Destination Host: 'esx03.example.com'
Destination vPortGroup: 'portgroup1'
Destination Switch: 'switch1'
Destination Network: 'network1'
Destination Provision: 'THICK'
Destination Autostart: YES

Related reference
“Restore VM” on page 681
Use the restore vm command to restore a virtual machine (VM) that was previously backed up.

Retrieve
The retrieve command obtains copies of archived files from the IBM Spectrum Protect server. You can
retrieve specific files or entire directories.
Use the description option to specify the descriptions that are assigned to the files you want to
retrieve.
Use the pick option to display a list of your archives from which you can select an archive to retrieve.
Retrieve the files to the same directory from which they were archived, or to a different directory. he
backup-archive client uses the preservepath option with the subtree value as the default for restoring
files.
Note: When a directory is retrieved, its modification date and time is set to the date and time of the
retrieval, not to the date and time the directory had when it was archived. This is because the backup-
archive client retrieves the directories first, then adds the files to the directories.

Supported Clients
This command is valid for all clients.

Syntax
RETrieve sourcefilespec
options "sourcefilespec"

destinationfilespec

Chapter 11. Using commands 693

 Parameters
sourcefilespec
Specifies the path and file name that you want to retrieve. Use wildcard characters to specify a group
of files or all the files in a directory.
destinationfilespec
Specifies the path and file name where you want the files to be written. If you do not specify a
destination, the client restores the files to the original source path.
Note: If you do not specify a destination, the backup-archive client determines whether the original
file system can be reached. If the original file system cannot be reached, the client does not restore
the file.
This failure can also occur if you remove the virtualmountpoint option from the dsm.sys file. In
this case, you can specify a different destination, or restore the original virtualmountpoint option
to the dsm.sys file, restart the client, and try the command again.

Table 112. Retrieve command: Related options

Option Where to use
dateformat “Dateformat” Client user options file (dsm.opt) or command line.
on page 334
description “Description” Command line only.
on page 341
dirsonly “Dirsonly” on Command line only.
page 346
filelist “Filelist” on page Command line only.
387
filesonly “Filesonly” on Command line only
page 390
followsymbolic Client user options file (dsm.opt) or command line.
“Followsymbolic” on page
391
fromdate “Fromdate” on Command line only
page 393
fromnode “Fromnode” on Command line only.
page 394
fromowner “Fromowner” on Command line only
page 395
fromtime “Fromtime” on Command line only
page 395
ifnewer “Ifnewer” on page Command line only
399
pick “Pick” on page 451 Command line only.
preservepath Command line only.
“Preservepath” on page 458
replace “Replace” on page Client user options file (dsm.opt) or command line.
466
subdir “Subdir” on page Client user options file (dsm.opt) or command line.
515

694 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Table 112. Retrieve command: Related options (continued)
Option Where to use
tapeprompt “Tapeprompt” Client user options file (dsm.opt) or command line.
on page 520
timeformat “Timeformat” Client user options file (dsm.opt) or command line.
on page 528
todate “Todate” on page Command line only.
532
totime “Totime” on page Command line only.
532

Examples
Task
Retrieve a single file named budget.
retrieve /home/devel/projecta/budget
Task
Retrieve all files with an extension of .c from the /home/devel/projecta directory.
retrieve "/home/devel/projecta/*.c"
Task
Retrieve all files in the /home directory.
retrieve /home/
Task
Retrieve all files with a file extension of .c from the /home/devel/projecta directory to the /
home/newdevel/projectn/projecta directory. If the /projectn or the /projectn/projecta
directory does not exist, it is created.
retrieve "/home/devel/projecta/*.c" /home/newdevel/projectn/
Task
Retrieve files in the /user/project directory. Use the pick option.
ret "/user/project/*" -pick
Task
Retrieve all files that were archived from the /proj directory with the description "2012 survey
results".
retrieve "/proj/*" -desc="2012 survey results"
Task
Retrieve archived file /home/devel/budget with description "my budget" to the /dev/rmt1 tape
drive.

mkfifo fifo
dd if=fifo of=/dev/rmt1&
dsmc retrieve -replace=yes -description="mybudget"
/home/devel/budget fifo

Task
Retrieve a file from the renamed file space Jaguar_OLD to its original location. Enter both the source
and destination as follows:
ret Jaguar_OLD/user5/Documents/myresume.doc /Users/user5/Documents/
Related information

Chapter 11. Using commands 695

 “Client options reference” on page 306

Retrieve archives from file spaces that are not Unicode-enabled

If you want to retrieve archives from file spaces that were renamed by the Unicode-enabled client, you
must specify the source on the server and a destination on the client.
This section applies to Mac OS X only. For example, assume that Jaguar is the name of your startup disk
and you archive all of the .log files in the /Users/user5/Documents directory. Before the archive takes
place, the server renames the file space to Jaguar_OLD. The archive places the data specified in the
current operation into the Unicode-enabled file space named /. The new Unicode-enabled file space now
contains only the Users/user5/Documents directory and the *.log files specified in the operation.
If you want to retrieve a file from the renamed (old) file space to its original location, you must enter both
the source and destination as follows:

retrieve Jaguar_OLD/Users/user5/Documents/mylog.log /Users/user5/Documents/

Schedule
The schedule command starts the client scheduler on your workstation. The client scheduler must be
running before scheduled work can start.
Authorized User: The schedule command starts the client scheduler on your workstation. The client
scheduler must be running before scheduled work can start.
Note:
1. The schedule command cannot be used if the managedservices option is set to schedule.
2. For Mac OSX only, to use the schedule command, specify managedservices none in the dsm.sys
file.
3. This command is valid only on the initial command line. It is not valid in interactive mode or in a macro
file.
If the schedmode option is set to polling, the client scheduler contacts the server for scheduled events at
the hourly interval you specified with the queryschedperiod option in your client user-options file
(dsm.opt). If your administrator sets the queryschedperiod option for all nodes, that setting overrides
the client setting.
If you are using TCP/IP communications, the server can prompt your workstation when it is time to run a
scheduled event. To do so, set the schedmode option to prompted in the client user-options file
(dsm.opt) or on the schedule command.
You can use the sessioninitiation option with the schedule command to control whether the
server or client initiates sessions through a firewall.
After you start the client scheduler, it continues to run and to start scheduled events until you press Ctrl
+C, stop the scheduler process with the UNIX kill command, start the workstation again, or turn off the
workstation to end it.
After you start the client scheduler, it continues to run and to start scheduled events until you press Ctrl
+C, press the Q key twice, start the workstation again, or turn off the workstation to end it.
Note: You cannot enter this command in interactive mode.

Supported Clients
This command is valid for all clients.

696 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Syntax
SCHedule
options

Parameters

Table 113. Schedule command: Related options

Option Where to use
maxcmdretries Client system options file (dsm.sys) or command line.
“Maxcmdretries” on page
431
password “Password” on client user options file (dsm.opt)
page 447
queryschedperiod Client system options file (dsm.sys) or command line.
“Queryschedperiod” on page
462
retryperiod “Retryperiod” Client system options file (dsm.sys) or command line.
on page 477
schedlogname Client system options file (dsm.sys) or command line.
“Schedlogname” on page
482
schedmode “Schedmode” on Client system options file (dsm.sys) or command line.
page 485
sessioninitiation Client system options file (dsm.sys) or command line.
“Sessioninitiation” on page
490
tcpclientport Client system options file (dsm.sys) or command line.
“Tcpclientport” on page 524

Examples
Task
Start the client scheduler.
Command: dsmc sch –password=notell
Task
For AIX: Start the scheduler at system bootup time by entering this command in the /etc/inittab file.
Ensure that the passwordaccess option is set to generate.
Command: tsm::once:/usr/bin/dsmc sched > /dev/null 2>&1 #TSM
Task
Interactively start the scheduler and keep it running in the background.
Command: nohup dsmc sched 2> /dev/null &
When you run the schedule command, all messages that regard scheduled work are sent to the
dsmsched.log file or to the file you specify with the schedlogname option in your client system-
options file (dsm.sys). If you do not specify a directory path with the file name in the schedlogname
option, the dsmsched.log resides in the current working directory, except for Mac OS X. For Mac OS X,
the dsmsched.log resides in the /Library/Logs/tivoli/tsm/ directory.

Chapter 11. Using commands 697

 Important: To prevent log write failures and process termination in certain cases, set the DSM_LOG
environment variable to name a directory where default permissions allow the required access.
Related information
“Sessioninitiation” on page 490

Selective
The selective command backs up files that you specify. If you damage or mislay these files, you can
replace them with backup versions from the server.
When you run a selective backup, all the files are candidates for backup unless you exclude them from
backup, or they do not meet management class requirements for serialization.
During a selective backup, copies of the files are sent to the server even if they did not change since the
last backup - which can result in more than one copy of the same file on the server. If this occurs, you
might not have as many different down-level versions of the file on the server as you intended. Your
version limit might consist of identical files. To avoid this, use the incremental command to back up
only new and changed files.
You can selectively back up single files or directories. You can also use wildcard characters to back up
groups of related files.
If you set the subdir option to yes when you back up a specific path and file, the client recursively backs
up all subdirectories under that path, and any instances of the specified file that exist under any of those
subdirectories.
During a selective backup, a directory path might be backed up, even if the specific file that was targeted
for backup is not found. For example, the following command still backs up dir1 and dir2 even if the file
bogus.txt does not exist.

selective /Users/user1/Documents/dir1/bogus.txt

selective "/dir1/dir2/bogus.txt"

If the selective command is retried because of a communication failure or session loss, the transfer
statistics displays the number of bytes that the client attempts to transfer during all command attempts.
Therefore, the statistics for bytes transferred might not match the file statistics, such as those for file size.
You can use the removeoperandlimit option to specify that the 20-operand limit is removed. If you
specify the removeoperandlimit option with the selective command, the 20-operand limit is not
enforced and is restricted only by available resources or other operating system limits.

Supported Clients
This command is valid for all clients.

Syntax

Selective filespec
options

Parameters
filespec
Specifies the path and name of the file you want to back up. Use wildcard characters to include a
group of files or to include all files in a directory.

698 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 To include multiple file specifications, separate each filespec with a space character. If multiple file
specifications are included, and two or more of the specifications have common parent directories,
then it is possible for the common directory objects to be backed up more than once. The conditions
under which this behavior occurs are runtime-dependent, but the behavior itself has no adverse
effects.
For example, if the filespec is /home/amr/ice.doc /home/amr/fire.doc, then /home and /
home/amr might be backed up twice. The file objects, ice.doc and fire.doc, are backed up only
once.
If you want to avoid including the shared parent directory more than once, use separate, non-
overlapping selective commands to back up each file specification.
If you back up a file system, include a trailing slash (/home/).
There is a limit of 20 operands. This limit prevents excessive sessions that are caused when wildcards
are expanded by the UNIX shell command processor. You can prevent shell expansion from causing
you to go over the 20-operand limit by placing quotation marks around file specifications that contain
wildcards ("home/docs/*").
You can use the removeoperandlimit option to specify that the 20-operand limit is removed. If you
specify the removeoperandlimit option, the 20-operand limit is not enforced and is restricted only
by available resources or other operating system limits. For example, remove the 20 operand limit to
backup 21 file specifications:

selective -removeoperandlimit filespec1 filespec2 ... filespec21

You can use the filelist option, instead of file specifications, to identify which files to include in
this operation. However, these two methods are mutually exclusive. You cannot include file
specification parameters and use the filelist option. If the filelist option is specified, any file
specifications that are included are ignored.

Table 114. Selective command: Related options

Option Where to use
changingretries Client system options file (dsm.sys) or command line.
“Changingretries” on page
321
compressalways Client user options file (dsm.opt) or command line.
“Compressalways” on page
325
compression Client user options file (dsm.opt) or command line.
“Compression” on page 326
dirsonly “Dirsonly” on Command line only.
page 346
filelist “Filelist” on page Command line only.
387
filesonly “Filesonly” on Command line only.
page 390
preservelastaccessdate Client user options file (dsm.opt) or command line.
“Preservelastaccessdate” on
page 457
removeoperandlimit Command line only.
“Removeoperandlimit” on
page 466

Chapter 11. Using commands 699

 Table 114. Selective command: Related options (continued)
Option Where to use
snapshotcachesize Client options file (dsm.opt) or with the include.fs option.
“Snapshotcachesize” on
page 502
snapshotproviderfs System-options file (dsm.sys) within a server stanza or with the
“Snapshotproviderfs” on include.fs option.
page 503
snapshotroot Command line only.
“Snapshotroot” on page 504
subdir “Subdir” on page Client user options file (dsm.opt) or command line.
515
tapeprompt “Tapeprompt” Client user options file (dsm.opt) or command line.
on page 520

Examples
Task
Back up the proja file in the /home/devel directory.
Command: selective /home/devel/proja
Task
Back up all files in the /home/devel directory whose file names begin with proj.
Command: selective "/home/devel/proj*"
Task
Back up all files in the /home/devel directory whose file names begin with proj. Back up the single
file that is named budget in the /user/home directory.
Command: selective "/home/devel/proj*" /user/home/budget
Task
Back up the /home file system.
Command: selective /home/ -subdir=yes
Task
Assuming that you initiated a snapshot of the /usr file system and mounted the snapshot as /
snapshot/day1, run a selective backup of the /usr/dir1/sub1 directory tree from the local
snapshot and manage it on the IBM Spectrum Protect server under the file space name /usr.
Command: dsmc sel "/usr/dir1/sub1/*" -subdir=yes -snapshotroot=/snapshot/
day1

Associate a local snapshot with a server file space

Use the snapshotroot option with the selective command in conjunction 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. The
snapshotroot option does not provide any facilities to take a volume snapshot, only to manage data
created by a volume snapshot.
AIX only: You can perform a snapshot-based selective backup by specifying the option
snapshotproviderfs=JFS2.

700 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Set Access
The set access command gives users at other nodes access to your backup versions or archived
copies.
You can also use the set access command to give users at other nodes access to your backup images.
You can give another user access to a specific file or image, multiple files or images, or all files in a
directory. When you give access to another user, that user can restore or retrieve your objects. Specify in
the command whether you are giving access to archives or backups.
For VMware virtual machines, you can give a user at another node access to the backups of a specific
virtual machine.
When a node is exported to another IBM Spectrum Protect server, the access rules can change on the
importing server. If an access rule is applied to all file spaces on the exporting server, the access rule on
the importing server is restricted to only those file spaces that are imported. The file spaces are restricted
in the access rule on the importing server for security reasons. Additionally, the access rules do not
recognize the first occurrence of a wildcard character in the file specification when you restore or retrieve.
This means that if you restore or retrieve with a wildcard character in the file specification, subdirectories
are ignored.
Tip: If you export a node to another IBM Spectrum Protect server, do not use a single wildcard character
as the file specification in the access rule. Instead, create an access rule for each filespace.
Note: You cannot give access to both archives and backups using a single command.
When an existing file space is renamed during Unicode conversion, any access rules that are defined for
the file space remain applicable to the original file space. However, new access rules must be defined to
apply to the new Unicode file space.

Supported Clients
This command is valid for all clients.

Syntax
SET Access Archive filespec node

Backup image-fs

TYPE=VM vmname

user

Parameters
Archive
Permits access to archived files or images.
Backup
Permits access to backup versions of files or images.
filespec
Specifies the path, file, image, or directory to which your are giving access to another node or user.
Use wildcard characters to specify a group of files or images, or all files in a directory; all objects in a
directory branch; or all objects in a file system. Use a single asterisk "*" for the file spec to give access
to all files or images owned by you and backed up on the server. When the command set access
backup "*" node is entered, no check is made with the server; it is assumed you have at least one
object backed up.

Chapter 11. Using commands 701

 If you give access to a branch of the current working directory, you only need to specify the branch. If
you give access to objects that are not in a branch of the current working directory, you must specify
the complete path. The file spec to which you gave access must have at least one backup version or
archive copy object (file or directory) on the server.
To specify all files in a named directory, enter /home/mine/proj1/* on the command line.
To give access to all objects below a certain level, use an asterisk, directory delimiter, and an asterisk
at the end of your file spec. For example, to give access to all objects below home/test, use file spec
home/test/*/*.
Important: Use of the form /*/* alone will not give access to objects in the named directory; only
those in directories below the named directory are accessible.
The rules are essentially the same when considering the root directory. Enter /* on one set access
command and /*/* on another if you want another user to have access to all files and directories in
and below the root directory. The first /* gives access to all directories and all files in the root
directory. The second /* allows access to all directories and files below the root directory.
For example:
• Your directory structure is multilevel: /home/sub1/subsub1.
• The /home directory contains the h1.txt and h2.txt files.
• The /home/sub1 directory contains file s1.htm.
• The /home/sub1/sub2 directory contains the ss1.cpp file.
To allow access to all files in the /home/sub1/sub2 directory, enter:

set access backup /home/sub1/sub2/* * *

To allow access to only those files in the /home directory, enter:

set access backup /home/* * *

To allow access to all files in all directories in and below the /home directory, enter:

set access backup /home/* * *

set access backup /home/*/* * *

image-fs
The name of the image file system to be shared. This can be specified as an asterisk (*) to allow
access to all images owned by the user granting access.
-TYPE=VM vmname
This parameter is required if you are using this command to provide another user with access to
VMware virtual machine backups. The vmname option can be specified only if -TYPE=VM is specified;
vmname is the name of the VMware virtual machine that you are permitting access to.
node
Specifies the client node of the user to whom you are giving access. Use wildcards to give access to
more than one node with similar node names. Use an asterisk (*) to give access to all nodes.
user
This is an optional parameter that restricts access to the named user at the specified node. To allow
any authorized user to access your backed up or archived data, specify root as the user.

Examples
Task
Give the user at node_2 authority to restore the budget file from the /home/user directory.
set access backup /home/user/budget node_2
Task
Give node_3 the authority to retrieve all files in the /home/devel/proja directory.

702 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 set ac archive /home/devel/proja/ node_3
Task
Give all nodes whose names end with bldgb the authority to restore all backup versions from
directories with a file space name of project.
set ac b "{project}/*" "*bldgb"
Task
Give any authorized user on node1 authority to retrieve all files in the /home/devel/projb
directory.
set access archive /home/devel/projb/ node1 root
Task
Give user serena at node_5 authority to restore all images of the file space mounted on directory /
home/devel/proja.
set acc backup "home/devel/proja/*/*" node_5 serena
Task
Give the node named myOtherNode the authority to restore files backed up by the VMware virtual
machine named myTestVM.
set access backup -TYPE=VM myTestVM myOtherNode

Set Event
Using the set event command, you can specify the circumstances for when archived data is deleted.
You can use the set event command in the following ways:
• Prevent the deletion of data at the end of its assigned retention period (Deletion hold)
• Allow the expiration to take place, as defined by the archive copy group (Release a deletion hold)
• Start the expiration clock to run when a particular event occurs (Notify the server that an event
occurred)
Objects that are affected can be specified with a standard file specification (including wildcards), a list of
files whose names are in the file that is specified using the filelist option, or a group of archived files
with the description specified with the description option.
Note: When only a <filespec> is used, all archived copies of files or folders that match the filespec are
affected. If you want to affect certain versions of a file, use the -pick option and select from the
displayed list.

Interaction with down-level servers

If the set event command is issued when the client is connected to a server that does not support
event-based policy (previous to IBM Spectrum Protect 5.2.2), the command is rejected with an error
message that indicates the current server does not support event-based policy.

Supported Clients
This command is valid for all clients.

Chapter 11. Using commands 703

 Syntax
SET Event -TYPE= Hold <filespec>

Release

Activateretention

-filelist=<filespec> -description= -pick

Parameters
TYPE=
Specifies the event type setting. This parameter must be specified.
hold
Prevents the object from being deleted regardless of expiration policy.
release
Allows normal event-controlled expiration to take place.
activateretention
Signals the server that the controlling event occurred and starts to run the expiration clock.
-pick
Provides a list of objects from which the user can select to apply the event.
The following options can also be used and serve their usual purpose:
• Dateformat
• Numberformat
• Noprompt
• Subdir
• Timeformat

Examples
Task
The following example displays the verbose and statistics output from the set event command set
event type=hold /home/accounting/ledgers/*05.books, with objects rebound (as opposed
to archived or some other notation).

Rebinding--> 274 /home/accounting/ledgers/

jan05.books
Rebinding--> 290 /home/accounting/ledgers/
feb05.books

Total number of objects archived: 0

Total number of objects failed: 0
Total number of objects rebound: 2
Total number of bytes transferred: 0 B
Data transfer time: 0.00 sec
Network data transfer rate: 0.00 KB/sec
Aggregate data transfer rate: 0.00 KB/sec
Objects compressed by: 0%
Elapsed processing time: 00:00:02

Task
The -pick option used with the set event command set event type=activate /user/
tsm521/common/unix shows the event type instead of the command name:

Scrollable PICK Window - Retention Event : ACTIVATE

# Archive Date/Time File Size File

704 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 -----------------------------------------------------
1. | 08/05/2003 08:47:46 766 B /user/tsm521
/common/unix
2. | 08/01/2003 10:38:11 766 B /user/tsm521
/common/unix
3. | 08/05/2003 08:47:46 5.79 KB /user/tsm521
/common/unix
4. | 08/01/2003 10:38:11 5.79 KB /user/tsm521
/common/unix
5. | 08/05/2003 08:47:46 10.18 KB /user/tsm521
/common/unix

Related information
“Dateformat” on page 334
“Numberformat” on page 445
“Noprompt” on page 443
“Subdir” on page 515
“Timeformat” on page 528

Set Netappsvm
The set netappsvm command associates the logon credentials for a cluster management server, which
are specified on the set password command, with a NetApp storage virtual machine, and the data
storage virtual machine (SVM) name (data Vserver). You must enter this command before you can create
a snapshot difference incremental backup of a clustered NetApp volume.
This command is typically entered only once. The parameters are stored and are reused the next time
that you backup a clustered volume that is managed by the storage virtual machine. If you move an
storage virtual machine to another cluster management server, you must reenter this command and
specify the new cluster management server. If necessary, change the login credentials by using the set
password command.

Supported clients
This command is valid for Linux backup-archive clients that complete snapshot difference backups of
clustered-data ONTAP-c-mode file-server volumes.

Syntax
SET NETAPPSVM svm_hostname cms_hostname svm_name

-remove svm_hostname

Parameters
svm_hostname
Specifies the host name or IP address of the storage virtual machine that manages the volumes and
logical interfaces (LIFs), for the volumes that you want to protect.
cms_hostname
Specifies the host name or IP address of the cluster management server. Specify the same host name
that you specified for this cluster management server when you used the set password command
to establish the login credentials.
svm_name
Specifies the name of the data SVM that manages the mounted volume. Contact the NetApp SVM
administrator to obtain the data SVM name that is assigned to the virtual machine.

Chapter 11. Using commands 705

 -remove svm_hostname
Disassociates the SVM from the cluster management server that it was previously associated with.
Specify a SVM host-name
You can specify this parameter if you accidentally associated a storage virtual machine with a 7-mode
file server. If you remove a 7-mode file server and then associate a cluster management server, set
the logon credentials for the cluster management server by using the set password command.

Examples
Configure the credentials and access to a storage virtual machine:

set netappsvm svm_example.com cms_filer1.example.com svm_2

dsmc set password cms_filer1.example.com user_name password

Remove the associations that were created for the storage virtual machine:

set netappsvm -remove svm_example.com

Related tasks
“Protecting clustered-data ONTAP NetApp file server volumes” on page 106
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).

Set Password
The set password command changes the IBM Spectrum Protect password for your workstation, or sets
the credentials that are used to access another server.
If you omit the old and new passwords when you enter the set password command, you are prompted
once for the old password and twice for the new password.
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.
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 b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9 . ! @ # $ % ^ & * _ - + = ` ( )
| { } [ ] : ; < > , ? / ~

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 b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 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.

706 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
On AIX, Linux, and Solaris systems:
Enclose the command parameters in single quotation marks (').
Command line example:
dsmc set password -type=vmguest 'Win 2012 SQL' 'tsml2dag\administrator'
'7@#$%^&7'
Quotation marks are not required when you type a password with special characters in an options file.
Restriction: The set password command does not support the Federal Information Processing
Standard (FIPS) enabled operating system environment for locally stored passwords.
For more information on FIPS support, see technote 2007756.
This restriction applies to AIX, Linux, and Solaris clients.

Supported Clients
This command is valid for all clients.
The following parameters apply to VMware operations, which are available only if you are using the client
as a data mover for IBM Spectrum Protect for Virtual Environments: Data Protection for VMware.
• TYPE=DOMAIN
• TYPE=VM
• TYPE=VMGUEST

Syntax
SET Password
oldpw newpw

otherserver otheruserid otherpassword

TYPE=TSM

TYPE=FASTBack

TYPE=FILER

TYPE=VM

TYPE=VMGUEST ALLVM

Parameters
oldpw
Specifies the current password for your workstation.
newpw
Specifies the new password for your workstation.
other_server other_user_id other_password
These three parameters specify the attributes that the client uses to access another server, such as a
filer or an ESXi host.
other_server
Specifies the host name or IP address of the server that the client can access to protect files.
other_user_id
The user ID of an account on the server that the client uses to log on to the other server. The
account must have the privileges that are necessary to perform the operations that are run after
the user is logged on to the other server.

Chapter 11. Using commands 707

 other_password
The password that is associated with the user ID on the other server.
TYPE
Specifies whether this password is for the backup-archive client or for another type of server.
Use TYPE=TSM to specify the password for your backup-archive client. The default type is TYPE=TSM.
Use TYPE=FastBack, on Linux and Windows clients, to store the Tivoli Storage Manager FastBack
credentials that are required for mounting and dismounting the FastBack volumes on the Windows
FastBack Disaster Recovery Hub server.
The password file on the vStorage backup server must have either the Windows administrator ID for
the VMware virtual center system, or the UNIX user ID for a specific ESX server. For a proxy backup
for FastBack, the password file must contain the FastBack administrator ID and password. Here are
some examples:

dsmc set password 192.0.2.24 admin admin 123 -type=fastback

dsmc set password 192.0.2.24 WORKGROUP:admin admin 123 -type=fastback

dsmc set password windserv administrator windpass4 -type=fastback

Important: You must define the user credentials that are required to mount and unmount FastBack
volumes from a repository to the backup-archive client before you enter the backup-archive FastBack
subcommand. Use the fbserver option to define the credentials.
Here is a brief description of the various configurations and credentials that you need:
• The backup-archive client is installed on a dedicated vStorage backup server. The client on the
vStorage backup server must connect to multiple network share repositories.
Follow these steps for each of the network share repositories where the client is connected:
1. Configure the repository for remote network access from FastBack Manager. Refer to the Tivoli
Storage Manager FastBack product documentation on IBM Knowledge Center at http://
www.ibm.com/support/knowledgecenter/SS9NU9/welcome.
This step establishes a domain name, a network share user ID, and a network share password to
connect remotely to the repository.
2. On the backup-archive client workstation, manually enter the following command:

dsmc set password type=fastback FBServer domain:networkaccessuserid

networkaccesspassword

The fbserver option specifies the short host name of the FastBack server workstation. For the
FastBack DR Hub, the fbserver option specifies the short name of the workstation where the DR
Hub is installed.
Networkaccessuserid is either the Windows administrator ID or the FastBack administration
password.
Domain is the domain name of the user ID.
Networkaccesspassword is either the Windows administrator ID or the FastBack administration
password.
3. These credentials are retrieved based on the short host name that you specify with the fbserver
option.
Use TYPE=FILER, on Linux and Windows systems to specify that this password is for snapshot
difference operations on a file server.
For TYPE=FILER, you must specify a file server name, and the user ID and the password that is used
to access the file server. For example: dsmc set password -type=filer myfiler filerid
filerpasswd.

708 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
When you specify TYPE=FILER, the password is stored in the password (TSM.sth) file without
validating that the password is valid. Passwords that are stored with TYPE=FILER can be shared
between client nodes. For example, a password that is stored by NODE_A can be used by NODE_B.
Only one set of credentials is stored per file server.
Use TYPE=VM to set the password that is used to log on to an ESX or vCenter server.

dsmc SET PASSWORD -type=VM hostname administrator password

where:
hostname
Specifies the VMware VirtualCenter or ESX server that you want to back up, restore, or query. This
host name must match the host name syntax that is used in the vmchost option. That is, if
vmchost uses an IP address instead of a host name, this command must provide the IP address,
and not a short host name or a fully qualified host name.
administrator
Specifies the account that is needed to log on to the vCenter or ESXi host.
password
Specifies the password that is associated with the login account that you specified for the vCenter
or ESXi administrator.
Use the Preferences editor to set the vmchost, vmcuser, and vmcpw options.
You can also set the vmchost option in the client options file and then use the set password
command to associate that host name with the administrator account and the administrative
account password that is used to log on to that host. For example, set password TYPE=VM
myvmchost.example.com administrator_name administrator_password.
Use TYPE=VMGUEST, on Linux and Windows clients, if you use the INCLUDE.VMTSMVSS option to
protect a virtual machine. Use the following format for the set password command:

set password -type=vmguest guest_VM_name administrator password

where:
guest_VM_name
Specifies the name of the virtual machine guest that you want to protect.
administrator
Specifies the account that is needed to log on to the guest VM.
password
Specifies the password that is associated with the login account.
If you use the same credentials to log on to multiple virtual machines that are protected by the
INCLUDE.VMTSMVSS option, you can set the password for the all of the virtual machines by specifying
the ALLVM parameter. The ALLVM parameter causes the same credentials to be used when the client
logs on to any guest that is included in an INCLUDE.VMTSMVSS option. The following command
TYPE=TSM is an example of how to use ALLVM. In this example, the user name "Administrator" and
the password "Password" are used to log on to any virtual machine that you included on an
INCLUDE.VMTSMVSS option:

set password -type=vmguest ALLVM Administrator Password

You can also set a combination of shared and individual credentials. For example, if most virtual
machines in your environment use the same credentials, but a few virtual machines use different
credentials, you can use multiple set password commands to specify the credentials. For example,
assume that most virtual machines use "Administrator1" as the login name and "Password1" as the
password. Assume also that one virtual machine, named VM2, uses "Administrator2" as the login
name and "Password2" as the password. The following commands are used to set the credentials for
this scenario:

Chapter 11. Using commands 709

 set password -type=vmguest ALLVM Administrator1 Password1 (sets credentials for
most of the VMs).
set password -type=vmguest VM2 Administrator2 Password2 (sets unique credentials
for VM2).

Examples
The following examples use the set password command.
Task
Change your password from osecret to nsecret.
set password osecret nsecret
Task
Set up a user ID and password for the root user on the file server myFiler.example.com.
dsmc set password -type=filer myFiler.example.com root
Please enter password for user id "root@myFiler.example.com": ******** Re-
enter the password for verification:******** ANS0302I Successfully done.
Task
Set up a user ID and password for the root user on the file server myFiler.example.com.
dsmc set password -type=filer myFiler.example.com root secret
Task
Set up a user ID and password for the FastBack server myFastBackServer. Use the -fbserver
option in the archive fastback and backup fastback commands for the server name.
dsmc set password -type=FASTBack myFastBackServer myUserId 'pa$sword'
Important:
1. The dsmc set password -type=fastback command must be repeated on a dedicated client
proxy workstation once for each FastBack repository where the backup-archive client is expected
to connect.
2. For network share repositories, issue the dsmc set password -type=fastback command in
this format: dsmc set password -type=fastback myFBServer domainName:userId
password.
The server name that is specified, which is myFBServer in this example, must match the name
that you specify on the -fbserver option on a backup fastback or archive fastback
command.
3. For the FastBack server or the FastBack Disaster Recovery Hub, the user ID and password that are
specified must have FastBack administrator privileges.
You must issue the dsmc set password -type=fastback command once for each FastBack
Server branch repository on the FastBack DR Hub that the backup-archive client is expected to
connect to.
Task
The backup-archive client is connecting to the FastBack server repository whose short host name is
myFBServer. user ID is the FastBack network user ID that has read/write access to the repository
share. DOMAIN is the domain to which the user ID belongs. myNetworkPass is the corresponding
password for the user ID.
dsmc set password -type=fastback myFbServer DOMAIN:USERID myNetworkPass
Task
The backup-archive client is connecting to a repository on a DR Hub machine whose short host name
is myFbDrHub. The user ID is the Windows administrator ID. DOMAIN is the domain to which the DR
Hub machine belongs. myNetworkPass is the corresponding password for the administrator ID.

710 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 dsmc set password -type=fastback myFbDrHub DOMAIN:administrator adminPasswd
Related reference
“Snapdiff” on page 494
Using the snapdiff (snapshot difference) option with the incremental command streamlines the
incremental backup process. The command runs an incremental backup of the files that were reported as
changed by NetApp instead of scanning all of the volume for changed files.

Set Vmtags
The set vmtags command creates data protection tags and categories that can be added to VMware
inventory objects. You can manage IBM Spectrum Protect backups of virtual machines in these VMware
objects by specifying the tags with tools such as VMware vSphere PowerCLI Version 5.5 R2 or later.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.
If you are using the IBM Spectrum Protect vSphere Client plug-in to manage backups, you do not need to
run the set vmtags command first. The tags and categories are created for you.
If you are writing scripts to apply these tags to VMware inventory objects, you need only to issue the set
vmtags command once so that data protection tags are created before they are added to the VMware
inventory.
You can manage virtual machine backups at the following VMware inventory object levels:
• Datacenter
• Folder (Host and Cluster folders and VM and Template folders)
• Host
• Host cluster
• Resource pool
• Virtual machine
For the list of supported tags, see "Supported data protection tags."
For tags that are related to schedules, the virtual machines must be in a protection set that is protected
by a schedule. A protection set consists of the virtual machines in a container that is assigned the
Schedule (IBM Spectrum Protect) tag.
After running the set vmtags command, you can assign the tags to VMware objects to manage the
protection of virtual machines. For example, you can exclude or include virtual machines in scheduled
backup services, specify the retention policy for backups, set the data consistency of snapshots, or select
the virtual machine disks to protect.
If the data protection tags already exist, running the set vmtags command does not create the tags
again.
If you are upgrading from a previous version of the data mover, running the set vmtags command again
will create any new tags that are available in the new version of the data mover.
Requirements: Before you run the set vmtags command, ensure that the following requirements are
met:
• VMware vCenter Server must be at Version 6.0 Update 1 or later.
• The vmchost option must be configured in the dsm.opt file on Windows data movers or dsm.sys file
on Linux data movers. The user name and password that are associated with the vmchost value must
also be set. If not already set, you can use the dsmc set password command to set the user name
and password.

Chapter 11. Using commands 711

 Supported clients
This command is valid only on supported Linux x86_64 clients that are installed on a vStorage backup
server that protects VMware assets.

Syntax
SET VMTAGS

Parameters
No parameters are required for this command.

Examples
Task
Create data protection tags and categories that can be added to VMware inventory objects:

dsmc set vmtags

Related concepts
“Management classes and copy groups” on page 266
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.
Related reference
“Supported data protection tags” on page 713
IBM Spectrum Protect data protection tags can be assigned to VMware inventory objects to control how
virtual machine backups are managed.
“Vmchost” on page 545
Use the vmchost option with the backup VM, restore VM, or query VM commands to specify the host
name of the VMware VirtualCenter or ESX server that you want to backup, restore, or query.
“Vmtagdatamover” on page 572
Use the vmtagdatamover option to enable tagging support in the backup-archive client (data mover).
When this option is enabled, the client manages backups of virtual machines in VMware inventory objects
according to the data protection tags that are set by the IBM Spectrum Protect vSphere Client plug-in of
the vSphere Web Client, or set with tools such as VMware vSphere PowerCLI Version 5.5 R2 or later.
“Set Password” on page 706
The set password command changes the IBM Spectrum Protect password for your workstation, or sets
the credentials that are used to access another server.

Data protection tagging overview

To manage data protection of virtual machines, you can assign IBM Spectrum Protect tags to VMware
inventory objects. You can assign tags to VMware objects by specifying data protection settings in the
IBM Spectrum Protect vSphere Client plug-in of the vSphere Web Client. If you do not use the IBM
Spectrum Protect vSphere Client plug-in, you can assign tags by using scripting tools such as VMware
Power CLI.
If you enable tagging support to manage backups, you can manage the protection of virtual machines,
such as excluding or including virtual machines in scheduled backup services, or assigning a schedule to
protect virtual machines in a container. For tags that are related to schedules, the virtual machines must
be in a protection set that is protected by a schedule. A protection set consists of the virtual machines in a
container that is assigned the Schedule (IBM Spectrum Protect) tag.
You can also specify the retention policy for backups, set the data consistency of snapshots, specify the
virtual machine disks to protect, or enable application protection with the IBM Spectrum Protect vSphere
Client plug-in.

712 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
The following VMware inventory objects are the containers that you can use to manage virtual machine
backups:
• Datacenter
• Folder (Host and Cluster folders and VM and Template folders)
• Host
• Host cluster
• Resource pool
• Virtual machine
When tagging support is enabled, you can assign data protection tags to VMware containers. If you do not
use the IBM Spectrum Protect vSphere Client plug-in, you must run the set vmtags command to create
data protection categories and tags in the VMware inventory.
When the vmtagdatamover option is set to yes, all tags that are assigned to a virtual machine are backed
up during backup vm operations. The tags are restored when the restore vm command is run. Tags
that are assigned to other inventory objects are not backed up and cannot be restored.

Representation of tags in the IBM Spectrum Protect vSphere Client plug-in

When you specify data protection settings in the IBM Spectrum Protect window in the IBM Spectrum
Protect vSphere Client plug-in, data protection tags are assigned to the inventory object.
For example, if you selected Yes in the Exclude from backup field, the Backup Management (IBM
Spectrum Protect) category and Excluded tag are assigned to the inventory object. The assigned tag
and category are displayed in the Tags portlet in the Summary tab of the inventory object.

Supported data protection tags

IBM Spectrum Protect data protection tags can be assigned to VMware inventory objects to control how
virtual machine backups are managed.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect for
Virtual Environments: Data Protection for VMware.
If you use the IBM Spectrum Protect vSphere Client plug-in to configure backup policy, you do not need to
manually assign the tags and categories to inventory objects. You can use the IBM Spectrum Protect
window to specify data protection settings for inventory objects in the vSphere Web Client. This action is
equivalent to assigning tags to an inventory object.
If you use scripting tools for tagging, you can use the set vmtags command on the data mover
command line to create the tags and categories in the vSphere inventory.
Unless otherwise stated, you can assign data protection tags to the following types of inventory objects:
• Datacenter
• Folder (Host and Cluster folders and VM and Template folders)
• Host
• Host cluster
• Resource pool
• Virtual machine
The following data protection tags are supported.

Category Tag Tag description

Application Protection Enabled Application protection is
(IBM Spectrum Protect) provided by IBM Spectrum
Protect

Chapter 11. Using commands 713

 Category Tag Tag description
Application Protection EnabledKeepSqlLog Protect Microsoft SQL
(IBM Spectrum Protect) Server and keep log files
for in-guest log file
management
Backup Management (IBM Excluded The object is always
Spectrum Protect) excluded from backups by
IBM Spectrum Protect
Backup Management (IBM Included The object is always
Spectrum Protect) included in backups by
IBM Spectrum Protect
Data Mover (IBM Spectrum Datamover_name The data mover used for
Protect) backups in IBM Spectrum
Protect
Data Mover (IBM Spectrum Default Data Mover The default data mover
Protect) that is assigned to a
schedule, if any, is used
for backups in IBM
Spectrum Protect
Disk Backup List (IBM Include | Exclude:disk The list of virtual disks
Spectrum Protect number,disk number,... included or excluded in
backups by IBM Spectrum
Protect
Local Backup Management LocalIncluded The object is included in
(IBM Spectrum Protect)1 local backups on the
hardware storage
Local Backup Management LocalExcluded The object is excluded
(IBM Spectrum Protect)1 from local backups on the
hardware storage
Local Management Class Management_class_name The policy that is used
(IBM Spectrum Protect)1 for retention settings
for local backups on the
hardware storage
Management Class (IBM Management_class_name The policy used for
Spectrum Protect) retention settings in IBM
Spectrum Protect
Schedule (IBM Spectrum Schedule_name The schedule to use for
Protect) backups by IBM Spectrum
Protect
Schedule (IBM Spectrum Schedule_group The schedule group to use
Protect) for backups by IBM
Spectrum Protect
Snapshot Attempts (IBM quiesce,nonquiesce The number of quiesced
Spectrum Protect) and nonquiesced snapshots
to attempt by IBM
Spectrum Protect before
the backup fails

1 This category and tag apply only to virtual machines that are stored in a VVOL datastore.

714 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
IBM Spectrum Protect category and tag names are case sensitive. The category and tag combinations are
defined as follows:
Application Protection (IBM Spectrum Protect)
Enabled
Notifies virtual machine applications that a backup is about to occur. This category and tag
combination allows an application to truncate logs and commit transactions so that the
application can resume from a consistent state when the backup is completed.
When a virtual machine is assigned this category and tag, application protection is provided by
IBM Spectrum Protect. The data mover freezes and thaws VSS writers and truncates application
logs. If a virtual machine is not assigned this tag, application protection is provided by VMware,
which freezes and thaws the VSS writers, but does not truncate application logs.
You can assign this tag and category only to virtual machines.
When you assign this category and tag to a virtual machine, you must complete an additional
configuration step. On each data mover that you are using to back up virtual machines, store the
guest virtual machine credentials to Data Protection for VMware by running the following
command from the data mover command line:

dsmc set password –type=vmguest vm_guest_display_name guest_admin_ID

guest_admin_pw

Where vm_guest_display_name specifies the name of the guest virtual machine as shown in the
VMware vSphere Web Client.
This command stores the guest virtual machine credentials, which are encrypted on the system
that hosts the data mover. The following minimum permissions are required for guest_admin_ID
guest_admin_pw:
Backup rights: Microsoft Exchange Server 2013 and 2016: Organization Management
permissions (membership in the management role group, Organization Management)
Backup rights: Microsoft SQL Server 2014 and 2016: Organization Management permissions
(membership in the management role group, Organization Management)
If you use the same credentials to log on to multiple virtual machines that are enabled for
application protection, you can set the password for the all of the virtual machines by specifying
the allvm parameter in the following command:

dsmc set password –type=vmguest allvm guest_admin_ID guest_admin_pw

For more information, see Configuring Data Protection for VMware.

If you do not enable application protection, the setting in the include.vmtsmvss option is used.
This setting cannot be inherited.
This tag overrides the include.vmtsmvss option.
EnabledKeepSqlLog
Provides application protection and prevents Microsoft SQL Server logs from being truncated
when a data mover backs up a virtual machine that is running a Microsoft SQL Server. Specifying
this tag enables the SQL server administrator to manually manage the SQL server logs, so that
they can be preserved and be used to restore SQL transactions to a specific checkpoint after the
virtual machine is restored. The SQL server administrator must manually back up, and possibly
truncate the SQL server logs on the guest virtual machine.
You can assign this tag and category only to virtual machines. In addition to this tag, you must
assign the Enabled tag to the virtual machines.

Chapter 11. Using commands 715

 When this tag is specified, the SQL server log is not truncated and the following message is
displayed and logged on the IBM Spectrum Protect server:

ANS4179I IBM Spectrum Protect application protection

did not truncate the Microsoft SQL Server logs on VM 'VM'.

If you need to enable truncation of the SQL server logs after a backup is completed, remove the
EnabledKeepSqlLog tag and assign the Application Protection (IBM Spectrum
Protect) Enabled category and tag to the virtual machine. In this case, the data mover does
not back up the SQL log files.
If you do not set this tag, Microsoft SQL Server logs are not retained during application protection
enabled backup. This tag cannot be inherited.
This tag overrides the keepsqllog parameter in the include.vmtsmvss option.
Backup Management (IBM Spectrum Protect)
Excluded
Excludes the virtual machines in an inventory object from scheduled backup services.
Included
Includes the virtual machines in an inventory object in scheduled backup services. This tag is the
default for the Backup Management (IBM Spectrum Protect) category and typically does
not need to be set.
Use this tag when a parent object is assigned the Excluded tag, or if you want to make sure that
virtual machines in an object are always included in scheduled backups, regardless of any
inheritance settings.
If you do not assign these tags, and no inherited setting exists, virtual machines are included in
scheduled backups.
These tags override the domain.vmfull data mover option.
Data Mover (IBM Spectrum Protect)
Datamover_name
Assigns a data mover to run backups of virtual machines.
If you use the IBM Spectrum Protect vSphere Client plug-in, data movers are automatically
assigned to virtual machines if you apply the Schedule category and tag to a container. However,
you can also manually update data movers for individual virtual machines.
If you do not use the IBM Spectrum Protect vSphere Client plug-in to apply the Schedule tag to a
container, you must manually assign data mover tags to those virtual machines, or their parent
containers, that are in that schedule.
If you do not assign a data mover to a virtual machine, the data mover is inherited from the parent
object. If no inherited setting exists, or the Default Data Mover tag is set or inherited, the
virtual machines are backed up by the default data mover that is assigned to a schedule, if any.
Otherwise, the virtual machines are not backed up and are identified in the IBM Spectrum Protect
vSphere Client plug-in with the At Risk status until a data mover is assigned to the virtual
machines.
This tag overrides the nodename data mover option.
Default Data Mover
Assigns the default data mover for a schedule, if any, to run backups of virtual machines. If the
schedule does not have a default data mover, the virtual machines are not backed up and are
identified in the IBM Spectrum Protect vSphere Client plug-in with the At Risk status until a data
mover is assigned to the virtual machines or the schedule is assigned a default data mover.

716 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Disk Backup List (IBM Spectrum Protect)
Include | Exclude:disk number,disk number,...
Includes or excludes a set of virtual machine hard disks in backup operations. Virtual machine
hard disks are identified by the disk number in the virtual machine. For example, in most cases,
disk 1 is the system disk. If you do not assign this tag to a virtual machine, all hard disks in the
virtual machine are backed up.
For ease of use, the Disk Backup List (IBM Spectrum Protect) category is prepopulated
with several commonly used tags:
Include:all
Includes all disks in a backup.
Include:1
Includes only disk 1 in a backup, and explicitly excludes all other disks.
Exclude:1
Includes all disks except for disk 1 in a backup.
You can modify the disk numbers to suit your needs. You can specify a disk number in the range 1
- 999. The disk numbers must be listed as comma-separated values, with no spaces between the
commas and numbers.
For example, to include only disks 1, 3, and 5 in backups, assign the Disk Backup List (IBM
Spectrum Protect) category and Include:1,3,5 tag to a virtual machine.
To back up all disks except for 1, 2, and 4, assign the Disk Backup List (IBM Spectrum
Protect) category and Exclude:1,2,4 tag to a virtual machine.
If you do not specify the disks to include or exclude and no inherited setting exists, all virtual
machine disks are backed up.
These tags override the include.vmdisk and exclude.vmdisk data mover options.
Local Backup Management (IBM Spectrum Protect)
LocalExcluded
Excludes snapshots for virtual machines in an inventory object from the scheduled backup
services.
LocalIncluded
Includes snapshots for virtual machines in an inventory object in the scheduled backup services.
This tag is the default for the Local Backup Management (IBM Spectrum Protect)
category and typically does not need to be set.
Use this tag when a parent object is assigned the LocalExcluded tag, or if you want to make
sure that snapshots for virtual machines in an object are always included in scheduled backups,
regardless of any inheritance settings.
If you do not assign these tags, and no inherited setting exists, virtual machines are included in
scheduled backups.
These tags override the domain.vmfull data mover option.
Local Management Class (IBM Spectrum Protect)
Management_class_name
Specifies the name of the retention policy that defines how long snapshot versions are kept on the
hardware storage or how many snapshot versions can exist on the storage before they are
expired.
If you do not specify the management class, the retention policy is inherited from a parent object.
If no inherited setting exists, the management class that is specified in the vmmc option is used. If
the vmmc option is not set, the default retention policy for the datacenter node is used.
This tag overrides the include.vmlocalsnapshot option.

Chapter 11. Using commands 717

 Management Class (IBM Spectrum Protect)
Management_class_name
Specifies the name of the retention policy that defines how long backup versions are kept on the
IBM Spectrum Protect server or how many backup versions can exist on the server before they are
expired.
If you do not specify the management class, the retention policy is inherited from a parent object.
If no inherited setting exists, the management class that is specified in the vmmc option is used. If
the vmmc option is not set, the default retention policy for the datacenter node is used.
This tag overrides the include.vm, vmmc, or vmctlmc options.
Schedule (IBM Spectrum Protect)
Schedule_name
Specifies the name of the schedule that is used for virtual machine backups to the IBM Spectrum
Protect server. The schedule name must be unique.
Schedules are set up by the IBM Spectrum Protect server administrator or VMware administrator
to automatically back up virtual machines in your vSphere inventory. For ease of use,
administrators can use IBM Spectrum Protect Operations Center Version 8.1 to create schedules
that are compatible with tagging.
When you assign this category and tag to a virtual machine, all virtual machines at the inventory
object level and any child object levels are backed up according to the schedule.
Only schedules with the -domain.vmfull="Schedule-Tag" option (and no other domain-level
parameters) in the schedule definitions are compatible with tagging support. Otherwise, the
Schedule tag is ignored, and virtual machines in inventory objects that are tagged with non-
compatible schedules are not backed up.
To be compatible with tagging, the following criteria must be included in the schedule definition:
• The -domain.vmfull="Schedule-Tag" option (and no other domain-level parameters) must
be specified in the option string. The option is case insensitive and must contain no spaces. The
quotation marks that enclose the Schedule-Tag parameter are optional.
• The schedule must contain the ACTION=BACKUP and SUBACTION=VM parameters.
• The option string must contain the -asnodename=datacenter option, where the value for the
datacenter parameter must correspond to the datacenter that is being managed by the IBM
Spectrum Protect vSphere Client plug-in.
• If the -vmbackuptype=backuptype option is specified in the option string, the value for the
backuptype parameter must be FULLVM (case insensitive).
The following sample server command defines a schedule that is compatible with tagging:

define schedule domain_name schedule_name

description=schedule_description action=backup subaction=VM
starttime=NOW+00:10 schedstyle=Classic period=1 perunits=Weeks
durunits=minutes duration=10 options='-vmbackuptype=fullvm
-asnodename=datacenter_node_name -mode=IFIncremental
-domain.vmfull="Schedule-Tag"'

The server administrator must also associate a data mover with the schedule by using the
following server command:

define association domain_name schedule_name data_mover_node_name

This category and tag can be assigned to datacenters, folders, hosts, host clusters, resource
pools, and virtual machines.
Tip: If you assign the Schedule tag to a container without using the IBM Spectrum Protect
vSphere Client plug-in, the Data Mover category and tag are not automatically assigned to the
virtual machines in the container. You must manually assign the Data Mover tag to each virtual

718 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
 machine. Alternatively, if a schedule is associated with only one data mover, you can assign the
data mover directly to the container that is protected by the schedule.
If you do not set this tag on an object, the Schedule tag is inherited from the parent object. If no
inherited setting exists, virtual machines are not included in any scheduled backups.
Any domain-level parameters in the domain.vmfull data mover option are ignored for a
schedule that is compatible with tagging.
Schedule_group
Specifies the name of the schedule group that is used for virtual machine backups. A schedule
group contains multiple schedules. You can 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.
Snapshot Attempts (IBM Spectrum Protect)
quiesce,nonquiesce
This category and tag combination specifies the total number of snapshot attempts for a virtual
machine backup operation that fails due to snapshot failure. The tag value consists of a pair of
positional parameters, which describe the number of times to attempt a snapshot and the data
consistency to achieve during the attempt.
quiesce
A positional parameter that specifies the number of times to attempt the snapshot with
quiescing, which creates an application-consistent snapshot.
• For Windows virtual machines assigned with the Application Protection tag, the
quiesce parameter specifies the number of times to attempt the snapshot with IBM
Spectrum Protect VSS quiescing and Microsoft Windows system provider VSS quiescing.
Depending on the number that you specify, the first snapshot attempt is always made with
IBM Spectrum Protect VSS quiescing. Subsequent snapshot attempts are made with
Windows system provider VSS quiescing.
• For Windows virtual machines without the Application Protection tag or for Linux
virtual machines, the quiesce parameter specifies the number of times to attempt the
snapshot with VMware Tools file system quiescing.
You can specify a value in the range 0 - 10. The default value is 2.
nonquiesce
A positional parameter that specifies the number of times to attempt the snapshot without
quiescing, after the snapshot attempts with quiescing (as specified by the quiesce parameter)
are completed. Without snapshot quiescing, crash-consistent snapshots are created. With
crash-consistent snapshots, operating system, file system, and application consistency are
not guaranteed.
You can specify a value in the range 0 - 10. The default value is 0.
Restriction: The 0,0 entry is not valid. Backup operations require at least one snapshot.
The following snapshot attempts are common choices to use for data consistency:
2,0 - Always application consistent
Attempts two quiesced snapshots before failing the backup. This combination is the default.
2,1 - Attempt application consistent
Attempts two quiesced snapshots and, as a final attempt, a nonquiesced, crash-consistent
snapshot.
0,1 - Machine consistent only
Attempts only a nonquiesced snapshot for virtual machines that can never complete a
quiesced snapshot.

Chapter 11. Using commands 719

 If you do not specify the snapshot attempts and no inherited setting exists, the snapshot attempts
that are specified in the include.vmsnapshotattempts option are used.
This tag overrides the include.vmsnapshotattempts option.
Tip: Data protection tags can be inherited from higher-level inventory objects. For more information, see
“Inheritance of data protection settings” on page 720.
Related reference
“Schedgroup” on page 480
The schedgroup option assigns a schedule to a group.
“Vmtagdatamover” on page 572
Use the vmtagdatamover option to enable tagging support in the backup-archive client (data mover).
When this option is enabled, the client manages backups of virtual machines in VMware inventory objects
according to the data protection tags that are set by the IBM Spectrum Protect vSphere Client plug-in of
the vSphere Web Client, or set with tools such as VMware vSphere PowerCLI Version 5.5 R2 or later.
“Vmtagdefaultdatamover” on page 574
Use the vmtagdefaultdatamover option to protect virtual machines, defined in a schedule, that do not
have an assigned or inherited Data Mover category and tag.
“Domain.vmfull” on page 355
The domain.vmfull option specifies the virtual machines (VMs) to include in your full virtual machine
image backup operations.
“Include.vmdisk” on page 411
The INCLUDE.VMDISK option includes a virtual machine (VM) disk in backup operations. If you do not
specify one or more disk labels, all disks in the VM are backed up.
“INCLUDE.VMSNAPSHOTATTEMPTS” on page 416
Use the INCLUDE.VMSNAPSHOTATTEMPTS option to determine the total number of snapshot attempts to
try for a virtual machine (VM) backup operation that fails due to snapshot failure.
“INCLUDE.VMTSMVSS” on page 418
The INCLUDE.VMTSMVSS option notifies virtual machine applications that a backup is about to occur.
This option allows the application to truncate transaction logs and commit transactions so that the
application can resume from a consistent state when the backup completes. An optional parameter can
be specified to suppress truncation of the transaction logs.

Inheritance of data protection settings

IBM Spectrum Protect data protection settings, or tags, can be inherited, or passed down, from a higher-
level parent inventory object in the vSphere Web Client navigator.
When you assign a data protection tag to an inventory object in the vSphere Web Client, the child objects
inherit the same data protection tag as the parent inventory object that the tag was assigned to.
The following list shows the types of vSphere inventory objects that can be tagged and can inherit data
protection tags:
• Datacenter
• Folder (Host and Cluster folders and VM and Template folders)
• Host
• Host cluster
• Resource pool
• Virtual machine
For example, if you assign the Excluded tag to a host cluster, the child objects of the host cluster object
(host, host folder, and virtual machine) all inherit the Excluded tag. In this example, all virtual machines
that are within the host cluster are excluded from scheduled backups.

720 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
If a child object is assigned a tag and inherits tags in the same category, the assigned tag of the child
object overrides the inherited tag. If a child object inherits tags in the same category from multiple
ancestor objects, the tag that is inherited from the nearest ancestor overrides tags from other ancestors.
If no data protection tags are assigned in the vSphere inventory hierarchy, the system default tag settings
are applied. For information about the supported tags and any default tag settings, see "Supported data
protection tags." .

Order of precedence for inheritance

Depending on the object (target object) that you are trying to assign a data protection tag to, a
precedence exists for determining the distance from the target object to its ancestors during processing
of tag inheritance from multiple ancestors. The following table contains target objects and the possible
ancestors of each target object type, based on the hierarchy of objects that is presented in the vSphere
Web Client Navigator.

Table 115. Order of precedence of vSphere inventory objects

Target object Order of precedence of tags processed
Virtual machine Target virtual machine → Nested VM folders → Nested resource pools →
Host → Host cluster → Nested host folders → Datacenter
VM folder Target VM folder → Other nested VM folders → Datacenter
Host folder Target host folder → Other nested host folders → Datacenter
Resource pool Target resource pool → Other nested resource pool → Nested VM folders
→ Host → Host cluster → Nested host folders → Datacenter
Host Target host → Nested host folders → Cluster → Datacenter
Cluster Target cluster → Nested host folders → Datacenter
Datacenter Target datacenter

If the target object is a virtual machine, the virtual machine itself, and any combinations of its ancestors
(including VM folders, resource pools, host, host cluster, host folders, datacenter) can be assigned tags
from the same category. During processing, each object type is checked in the order of precedence, and
processing stops when a tag in the same category is found or the end of the list is reached.
For example, to determine whether the Excluded or Included tag Backup Management (IBM
Spectrum Protect) is applied to virtual machines, IBM Spectrum Protect searches for the Excluded
and Included tags in the inventory in a datacenter. According to the order of precedence for the virtual
machine target object, the search for the Excluded and Included tags starts from the target object
(virtual machine) itself, followed by the list of potential ancestors. If a tag is found before the end of the
list is reached, this tag is applied to the target object. Otherwise, no tag from the Backup Management
(IBM Spectrum Protect) category is applied to the target virtual machine.
Related concepts
“Tips for data protection tagging” on page 722
Backup policies are determined by the data protection tag assignments on vSphere inventory objects. The
performance for processing data protection tags can also be affected by the number of tags that are
applied to the vSphere inventory and where the tags are applied.
Related reference
“Supported data protection tags” on page 713

Chapter 11. Using commands 721

 IBM Spectrum Protect data protection tags can be assigned to VMware inventory objects to control how
virtual machine backups are managed.

Tips for data protection tagging

Backup policies are determined by the data protection tag assignments on vSphere inventory objects. The
performance for processing data protection tags can also be affected by the number of tags that are
applied to the vSphere inventory and where the tags are applied.
Consider taking the following actions when you define the backup policy for objects in the vSphere
inventory:
• Take advantage of the order of precedence for tagging inventory objects. Create a general policy
configuration for an organization by setting backup policies (or tags) on the highest container in the
vSphere inventory hierarchy. The policies are inherited by child containers and their virtual machines. In
general, you do not need to set policies on individual virtual machines.
Then, create exceptions by changing the policy on a child container or individual virtual machines to
override the inherited policy setting.
Alternatively, if you do not want to configure an overall backup policy, do not assign data protection tags
to any high-level objects. Assign the data protection tags to lower-level objects.
• For ease of maintenance, performance, and usability, avoid assigning tags to too many inventory
objects.
• For ease of maintenance and reduced complexity, avoid assigning tags to different object types. For
example, assign tags to clusters, hosts, host folders and VMs only, or to VM folders and VMs only, but
not both at the same time.
• With tagging support, you can assign multiple schedules to multiple data movers. However, do not
overlap the schedules for a data mover. Otherwise, some schedules will be skipped.
• For ease of use, administrators can use IBM Spectrum Protect Operations Center Version 8.1 to create
schedules that are compatible with tagging.
Related concepts
“Inheritance of data protection settings” on page 720
IBM Spectrum Protect data protection settings, or tags, can be inherited, or passed down, from a higher-
level parent inventory object in the vSphere Web Client navigator.

722 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Appendix A. Accessibility features for the IBM
Spectrum Protect product family
Accessibility features assist users who have a disability, such as restricted mobility or limited vision, to
use information technology content successfully.

Overview
The IBM Spectrum Protect family of products includes the following major accessibility features:
• Keyboard-only operation
• Operations that use a screen reader
The IBM Spectrum Protect family of products uses the latest W3C Standard, WAI-ARIA 1.0
(www.w3.org/TR/wai-aria/), to ensure compliance with US Section 508 (www.access-board.gov/
guidelines-and-standards/communications-and-it/about-the-section-508-standards/section-508-
standards) and Web Content Accessibility Guidelines (WCAG) 2.0 (www.w3.org/TR/WCAG20/). To take
advantage of accessibility features, use the latest release of your screen reader and the latest web
browser that is supported by the product.
The product documentation in IBM Knowledge Center is enabled for accessibility. The accessibility
features of IBM Knowledge Center are described in the Accessibility section of the IBM Knowledge Center
help (www.ibm.com/support/knowledgecenter/about/releasenotes.html?view=kc#accessibility).

Keyboard navigation
This product uses standard navigation keys.

Interface information
User interfaces do not have content that flashes 2 - 55 times per second.
Web user interfaces rely on cascading style sheets to render content properly and to provide a usable
experience. The application provides an equivalent way for low-vision users to use system display
settings, including high-contrast mode. You can control font size by using the device or web browser
settings.
Web user interfaces include WAI-ARIA navigational landmarks that you can use to quickly navigate to
functional areas in the application.

Vendor software
The IBM Spectrum Protect product family includes certain vendor software that is not covered under the
IBM license agreement. IBM makes no representation about the accessibility features of these products.
Contact the vendor for accessibility information about its products.

Related accessibility information

In addition to standard IBM help desk and support websites, IBM has a TTY telephone service for use by
deaf or hard of hearing customers to access sales and support services:

TTY service
800-IBM-3383 (800-426-3383)
(within North America)

For more information about the commitment that IBM has to accessibility, see IBM Accessibility
(www.ibm.com/able).

© Copyright IBM Corp. 1993, 2019 723

724 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Notices
This information was developed for products and services offered in the US. This material might be
available from IBM in other languages. However, you may be required to own a copy of the product or
product version in that language in order to access it.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that only
that IBM product, program, or service may be used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual property right may be used instead. However, it is the
user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can send
license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
US

For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual
Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"

WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties in
certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM websites are provided for convenience only and do not in
any manner serve as an endorsement of those websites. The materials at those websites are not part of
the materials for this IBM product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this
one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Director of Licensing

IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
US

© Copyright IBM Corp. 1993, 2019 725

 Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any
equivalent agreement between us.
The performance data discussed herein is presented as derived under specific operating conditions.
Actual results may vary.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform for
which the sample programs are written. These examples have not been thoroughly tested under all
conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work must include a copyright notice
as follows: © (your company name) (year). Portions of this code are derived from IBM Corp. Sample
Programs. © Copyright IBM Corp. _enter the year or years_.

Trademarks
IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be
trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at
"Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.
Adobe is a registered trademark of Adobe Systems Incorporated in the United States, and/or other
countries.
Linear Tape-Open, LTO, and Ultrium are trademarks of HP, IBM Corp. and Quantum in the U.S. and other
countries.
Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the
United States and other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States, other
countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or
its affiliates.
UNIX is a registered trademark of The Open Group in the United States and other countries.
VMware, VMware vCenter Server, and VMware vSphere are registered trademarks or trademarks of
VMware, Inc. or its subsidiaries in the United States and/or other jurisdictions.

726 Notices
Terms and conditions for product documentation
Permissions for the use of these publications are granted subject to the following terms and conditions.
Applicability
These terms and conditions are in addition to any terms of use for the IBM website.
Personal use
You may reproduce these publications for your personal, noncommercial use provided that all
proprietary notices are preserved. You may not distribute, display or make derivative work of these
publications, or any portion thereof, without the express consent of IBM.
Commercial use
You may reproduce, distribute and display these publications solely within your enterprise provided
that all proprietary notices are preserved. You may not make derivative works of these publications,
or reproduce, distribute or display these publications or any portion thereof outside your enterprise,
without the express consent of IBM.
Rights
Except as expressly granted in this permission, no other permissions, licenses or rights are granted,
either express or implied, to the publications or any information, data, software or other intellectual
property contained therein.
IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use
of the publications is detrimental to its interest or, as determined by IBM, the above instructions are
not being properly followed.
You may not download, export or re-export this information except in full compliance with all
applicable laws and regulations, including all United States export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THE PUBLICATIONS
ARE PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, NON-
INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.

Privacy policy considerations

IBM Software products, including software as a service solutions, (“Software Offerings”) may use cookies
or other technologies to collect product usage information, to help improve the end user experience, to
tailor interactions with the end user, or for other purposes. In many cases no personally identifiable
information is collected by the Software Offerings. Some of our Software Offerings can help enable you to
collect personally identifiable information. If this Software Offering uses cookies to collect personally
identifiable information, specific information about this offering’s use of cookies is set forth below.
This Software Offering does not use cookies or other technologies to collect personally identifiable
information.
If the configurations deployed for this Software Offering provide you as customer the ability to collect
personally identifiable information from end users via cookies and other technologies, you should seek
your own legal advice about any laws applicable to such data collection, including any requirements for
notice and consent.
For more information about the use of various technologies, including cookies, for these purposes, see
IBM’s Privacy Policy at http://www.ibm.com/privacy and IBM’s Online Privacy Statement at http://
www.ibm.com/privacy/details in the section entitled “Cookies, Web Beacons and Other Technologies,”
and the “IBM Software Products and Software-as-a-Service Privacy Statement” at http://www.ibm.com/
software/info/product-privacy.

Notices 727
728 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Glossary
A glossary is available with terms and definitions for the IBM Spectrum Protect family of products.
See the IBM Spectrum Protect glossary.

© Copyright IBM Corp. 1993, 2019 729

730 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Index

Special Characters archive (continued)

copy group attributes 267
* ? 211 copy mode 269
delete file spaces 171, 239
delete files after 340
Numerics delete individual archives from server file space 245,
128–bit AES encryption support 150 616
256-bit AES encryption support 150 display the last modification date and last access
datecreation date 638
files only 537
A grace period retention 266
hard links 247
absolute mode 269
how managed 249, 265
absolute option 306
improving speed using share memory 279
access
include files for 403
permissions, archive 246
information, query 638
access control lists
list of files 387
extended permissions, backup 166
more than one file specification 243
permissions, backup 166
number of attempts to archive open files 321
accessibility features 723
only files; not directories 243
ACL
overriding management class during 272
file systems supported 151
primary tasks 241
active backup versions
process directories only (not files) 346
displaying 142, 231, 640
query user access 637
restoring 231
removeoperandlimit 466
administrative client
retrieving using command line 248
allowing secure sessions within a private network 522
running 241
afmskipuncachedfiles 307
shared data on multiple clients under a single node
AIX
name 244, 309
configuring for snapshots 104
starting a web client session 136
workload partition (WPAR)
starting a web user interface session 137
backup 194
subdirectories 243
restore 227
summary of options 280
AIX client
suppress confirmation prompt before deleting 443
client components 3
symbolic links 246
communication methods 3
using commands 242, 246
installing 9
archive copy group 266
uninstalling 12
archive fastback
AIX components
command 595
installable 3
archive maximum file size 155
AIX disk space 3
archmc option 308
AIX hardware requirements 3
archsymlinkasfile option 308
AIX software requirements 3
asnodename option 309
AIX system requirements 3
asnodename session settings 310
application program interface (API)
auditlogging option 311
setting 61
auditlogname option 312
archive
authentication
a list of files 243
IBM Spectrum Protect client 131
assign description to 341
authorization
assigning description on command line 243
options 294
associating local snapshot with server file space 243,
authorized user
504
definition 49
binding management class to 308
tasks 49
binding management classes to files 243
authorized users
btrfs 186
enabling encryption 51
command 593
authorizing
compressing files 326
user to restore or retrieve your files 236
configuring client node proxy support 244

Index 731
auto-update 314 backup (continued)
autodeploy option 314 query user access 637
autofsrename option 315 selective
automated client failover associating local snapshot with server file space
configuration and use 87 700
configuring 90 selective backup using client command line 167
determining the replication status 92 skip acl processing 493
force failover 94 starting a web client session 136
other components 90 starting a web user interface session 137
overview 87 summary of options 280
preventing 93 backup chain integrity checks 576, 578
requirements 88 backup comparison: incremental, incremental-by-date 162
restoring data 221 backup considerations 205
restrictions 89 backup copy group
retrieving data 221 attributes 267
testing the connection 94 backup fastback command 597
automating backup services backup files
displaying scheduled work 258, 259 assigning management class 271
options for 260 backup group command 600
process commands after backup 453 backup image
process commands before backup 456 btrfs 186
starting client scheduler 66 using DSM_DIR to point to plug-in library 59
automount option 316 backup image command
supported devices 180
backup image, volume device type support 180
B backup maximum file size 155
back up backup NAS
btrfs 186 using DSM_DIR to point to plug-in library 59
network-attached storage (NAS) 606 backup nas command 606
new or changed files 158 backup planning 145
number of attempts to back up open files 321 backup set
parallel 554–556, 558 enabling GUI for local restore 216
shared data on multiple clients under a single node restore 213, 216
name 309 restoring in a SAN environment 672
symbolic links 207 backup sets
VM templates 552 restore considerations 218, 671
back up hard links 209 backup vm command 608
back up open files 210 backup with client node proxy
back up sparse files 209 agent node 172
back up volume 156 overview 172
backing up target node 172
in parallel sessions 202 backup-archive client
backing up data 199 GUI 190
backmc option 317 installation 9
backup NAS
copy mode 269 file systems backup 190
displaying processing status 202 overview 1
Encrypted File Systems (EFS) 196 backup-archive client GUI
grace period retention 266 establishing communications through firewall 68
image backupset
client domain 353 enabling GUI for local restore of 428
with incremental backup 605 backupsetname option 318
image: static, dynamic, snapshot 178 basesnapshotname option 319
improving speed using share memory 279 batch mode
incremental starting a session 134
associating local snapshot with server file space bottom-up processing
632 include-exclude list 122
incremental-by-date include-exclude options file 122
client command line 167 Bourne and Korn shell
multi-session, send files contiguously to the server 322 pointing to client user-options file 56
one server session per file specification 322 Bourne and Korn shell variables, setting 61
overview 145 btrfs 213, 677
primary tasks 145 btrfs file system
process directories only (not files) 346 archiving 186

732 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
btrfs file system (continued) client options (continued)
backing up 186 exclude (continued)
backup image 186 exclude.fs 113
protecting 187 exclude.image 113
protecting subvolumes 188 order of processing (precedence) 297
restore image 186 overriding using command line 297
restoring 186 overview 589
retrieving 186 using with commands 297
client options file
creating and modifying 54
C overview 53
C shell variables required options for 54
setting 61 client options reference 306
c-mode 106 client scheduler
cadlistenonport option 320 displaying scheduled work 258, 259
cancel process command 615 options for 260
cancel restore command 615 run at startup 256
central scheduling starting 66, 696
summary of options 292 starting automatically 140
Certificate Authorities client system options
root certificates exclude
Certificate Authorities 74 exclude.archive 113
changingretries option 321 exclude.attribute.symlink 113
CIFS exclude.backup 113
backing up file systems 193 exclude.compression 113
class option 321 exclude.dir 113
classic (standard) restore 234 exclude.file 113
client exclude.file.backup 113
automatic update 2 exclude.fs 113
client TCP/IP address other than the one for first server client system-options file
contact 524 copying and modifying 54
client TCP/IP port number other than the one for first specifying include-exclude options 112
server contact 524 client user-options
registering with server 111 customizing 58
setting password 112 client user-options file
size for the TCP/IP sliding window for client node 527 overriding using commands 297
client acceptor daemon client-node proxy support 172
configuring to manage scheduler 64 client-server communication
manage scheduler, web client, or both 430 client TCP/IP address other than the one for first server
client command options contact 524
overview 589 client TCP/IP port number other than the one for first
client components server contact 524
AIX client 3 establishing 54
Linux on Power Systems client 4 identify your workstation to the server 442
Linux on System z client 6 maximum disk I/O buffer size client uses when reading
Linux x86_64 client 5 or writing files 347
Mac OS X client 7 method 323
Oracle Solaris client 7 reconnection attempts after failure 324
client management service 47 reconnection interval after failure 325
client node proxy size for the TCP/IP sliding window for client node 527
archive overview 244 size of internal TCP/IP communication buffer 522
backup 174 specifying default server 339
scheduling 174 specifying name of server to contact for services 489
support 244 specifying number of kilobytes client buffers before
client options sending transaction to server 533
display current settings 655 TCP/IP address for dsmcad 523
exclude TCP/IP address of IBM Spectrum Protect server 526
exclude.archive 113 TCP/IP port address of IBM Spectrum Protect server
exclude.attribute.symlink 113 526
exclude.backup 113 TCP/IP port address on which to establish shared
exclude.compression 113 memory connection 492
exclude.dir 113 whether to send small transactions to server without
exclude.file 113 buffering them first 525
exclude.file.backup 113 closed registration

Index 733
closed registration (continued) commands (continued)
permissions 112 monitor process 635
using 112 overview of parameters 590
cluster environment preview archive 635
installing IBM Spectrum Protect 95 preview backup 636
clustered data ONTAP 106 query access 637
collecting diagnostic information 47 query archive 638
collocatebyfilespec option 322 query backup 640
command line query backupset 643, 645
archiving files 246 query filespace 646
assigning description to archive 243 query group 648
display current settings for client options 655 query image 650
displaying query inclexcl 652
processing status 202 query mgmtclass 653
ending a session 143 query node 654
entering commands 589 query options 655
general rules when entering options with commands query restore 656
298 query schedule 657
NAS file systems backup 191 query session 657
overriding management class during archive 272 query systeminfo 658
overview of parameters 590 query VM 659
performing image backup 185 restart restore 663
performing large restore operations 233 restore 664
performing point-in-time restore 224 restore backupset 668, 672
restoring retention set data 226 restore backupset considerations 218, 671
restrictions for NAS file systems 189 restore group 675
retrieving archived files 248 restore image 677
return codes for operations 263 restore NAS 679
specifying file specification 590 restore vm 681
specifying options file during session 447 retrieve 693
starting a session 133 schedule 696
using wildcard characters 592 scheduled, enabling or disabling 260
command parameters selective backup 698
overview 590 set access 701
command processing, summary of options 294 set event 703
command session set netappsvm 705
ending 588 set password 706
starting 588 set vmtags 711
commands specifying file specification 590
archive 593 using 585
archive fastback 595 using in executables 263
backup fastback 597 using in shell scripts 263
backup group 600 using options with 297
backup image 602 using wildcard characters 592
backup nas 606 commmethod option 323
backup vm 608 Common Internet File System (CIFS)
batch mode 588 backing up file systems 193
cancel process 615 commrestartduration option 324
cancel restore 615 commrestartinterval option 325
delete access 616 communication methods
delete archive 616 installable software 4–8
delete backup 618 Shared Memory
delete filespace 622 AIX client 3
delete group 623 HP-UX Itanium 2 API 4
entering 589 Linux on System z client 6
entering on command line 589 Linux x86_64 client 6
expire 624 Oracle Solaris client 8
general rules when entering options with 298 summary 278
help 626 TCP/IP
incremental 627 AIX client 3
interactive (loop) mode 588 HP-UX Itanium 2 API 4
loop 633 Linux on Power Systems client 5
macro 634 Linux on System z client 6
maximum file specifications permitted 590 Linux x86_64 client 6

734 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
communication methods (continued) data protection tagging (continued)
TCP/IP (continued) inheritance of tags 720
Mac OS X client 7 overview 712
Oracle Solaris client 8 supported list 713
communications datacenter option 333
establishing through firewall 68 datastore option 333
establishing with Secure Sockets Layer (SSL) 70 date format
compressalways option 325 specifying 334
compression dateformat option 334
disabling processing 409 dedupcachepath option 337
enabling processing 409 dedupcachesize option 338
include-exclude statements 409 deduplication option 338
compression and encryption processing default client user-options file
back up 409 creating and modifying 56
exclude from backup 409 example of 56
exclude options 409 default data mover 574
compression option 326 default domain
compression processing excluding domains from backup 167, 349
exclude from backup 409 default management class 265
exclude options 409 default policy domain 265
include files for 403 defaultserver option 339
concurrent backups 202 delete
configure file space 171, 239
file restore NAS or client objects 321
options 139 delete access command 616
configure the client for data deduplication 84 delete archive command 616
configuring delete backup command 618
client acceptor-managed scheduler 64 delete group command 623
optional tasks 49 delete individual backups from server file space 170
required tasks 49 deleted file systems 210
the client scheduler 63 deletefiles option 340
configuring support for client node proxy backups 172 deleting
configuring the web client 62 individual archives from server file space 245, 616
console option 328 individual backups from server file space 618
containing quotation marks 135 description option 341
control files 541 detail option 267, 342
copy destination attribute 270 diagnostics
copy frequency attribute 268 options 297
copy group name attribute 268 diffsnapshot option 343
copy groups diffsnapshotname option 344
archive 266 directories
backup 266 assigning management class for 345
copy mode parameter excluding 114
absolute 269 excluding from backup processing 374
modified 269 incremental backup processing overview 158
copy serialization attribute 269 processing during incremental-by-date 162
copy type attribute 268 specifying on command line 590
createnewbase 329 dirmc option 345
createnewbase option 329 dirsonly option 346
csv option 330 disability 723
disablenqr option 347
disaster recovery 238
D disk recovery 238
data disk space requirements
restoring 232 client 3
data deduplication 80 disk space, AIX 3
data deduplication client configuration 84 disk space, HP-UX Itanium 2 4
data deduplication files disk space, Linux on Power Systems 5
exclude 86 disk space, Linux System z 6
data protection settings disk space, Linux x86_64 5
inheritance 720 disk space, Mac OS X 7
represented as tags 713 disk space, Solaris 8
tips for configuring backup policies 722 diskbuffsize option 347
data protection tagging diskcachelocation option 348

Index 735
displaying dsmtca executable file (continued)
archive information 638 set DSM_DIR to point to 59
online help 143 dsmwebcl.log 481, 483
policy information 267 dual boot systems
restartable restore sessions 656 duplicate names 156
scheduled events 657 dynamic and shared serialization 269
session information 657 dynamicimage option 362
domain
back up using the GUI 166
include for full vm backups 355
E
include for image backup 353 efsdecrypt option 363
include for incremental backup 349 enablearchiveretentionprotection option 363
include for NAS image backup 354 enablededupcache option 365
incremental backup 208 enableinstrumentation option 366
specifying drives in the default 166 enablelanfree option 367
domain option 349 enabling encryption for authorized users 51
domain.image option 353 Encrypted File Systems (EFS)
domain.nas option 354 backup file systems 196
domain.vmfull option 355 restore file systems 227
dontload option 361 encrypting data during archive 150
download system logs encrypting data during backup 150
by using a web user interface session 138 encryption
downloading maintenance updates 47 multiple clients under a single node name 309
DSM_CONFIG of file data 150
adding to .cshrc file 61 saving encryption key password 369
pointing to client user-options file 56, 59 encryption considerations 51
using on Solaris 59 encryption processing
DSM_DIR encryption methods available 150
adding to .cshrc file 61 excluding files from 374
pointing to dsm.sys file 59 include files for 403
pointing to executable files 59 query systeminfo command 658
pointing to resource files 59 encryptiontype option 150, 368
set for image or NAS backup or restore 59 encryptkey option
DSM_LOG encryptkey=generate 369
adding to .cshrc file 61 encryptkey=prompt
set to point to dsmerror.log, dsmwebcl.log, encryptkey=save 369
dsmsched.log 59 enhanced query schedule 258
dsm.opt file enhanced query schedule command 657
creating 56 environment prerequisites
creating and modifying 54 AIX client 3
customizing 58 HP-UX Itanium 2 API 4
example of 56 Linux for zSeries client 6
required options for 54 Linux on Power Systems 4
specifying a drive specification using wildcards 117 Linux x86_64 client 5
dsm.opt.smp file 56 Solaris client 7
dsm.smp file environment variables
copying to dsm.opt 54 DSM_CONFIG 59
location 54 DSM_DIR 59
dsm.sys file DSM_LOG 59
creating 54 LANG 59
example of 54 setting API 61
dsm.sys.smp file 54 setting Bourne and Korn shell 61
dsmerlog.pru file 371 setting C shell 61
dsmerror.log error log
set DSM_LOG to point to 59 pruning 373
dsmerror.log file 371 specifying path and file name 372
DSMI_CONFIG environment variable error processing, summary of options 295
API, UNIX and Linux 61 errorlogmax option 371
DSMI_DIR environment variable errorlogname option 372
API, UNIX and Linux 61 errorlogretention option 371, 373
DSMI_LOG environment variable estimate function 166
API, UNIX and Linux 61 event logging
dsmsched.log 481, 483 scheduler 259
dsmtca executable file event-based policy retention protection

736 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
event-based policy retention protection (continued) file specification (continued)
archive 274 maximum allowed on commands 590
backup 274 file systems
exclude ACL support for 151
EXCLUDE.VMDISK 378 Btrfs 151
EXCLUDE.VMLOCALSNAPSHOT 380 define virtual mount point for 539
exclude data deduplication files 86 deleted 210
exclude options excluding from backup processing 374
exclude.archive 113 GPFS, multinode cluster environment 151, 349
exclude.attribute.symlink 113 image backup of 178
exclude.backup 113 QFS, restrictions 151
exclude.compression 113 supported 151
exclude.dir 113 filelist option 387
exclude.file 113 filename option 389
exclude.file.backup 113 files
exclude.fs 113 archive a list of 243, 387
exclude.image 113 archive using commands 246
preview 121 archived, overriding management class 272
processing 122 archives, how managed 249
wildcard characters 117, 118 archiving 241, 593
exclude.image option 113 archiving more than one file specification 243
EXCLUDE.VMDISK 378 assigning management classes 206
EXCLUDE.VMLOCALSNAPSHOT 380 authorizing another user to restore or retrieve 236
excluding files back up hard-linked 209
system files 116 back up open 210
using wildcard characters 118 binding management classes to 273
wildcard characters 117 compressing during archive or backup 326
excluding files from backup services 150 definition of changed 158
executable file delete after archive 340
return codes from 263 delete individual archives from server file space 245,
expire command 624 616
extended permissions delete individual backups from server file space 618
archive 246 encryption 150
excluding groups 117, 118
include-exclude
F creating in Unicode format 403
failover including groups 117, 118
client 87 managing growth during compression 325
configuration and use 87 maximum file size for operations 155
configuring the client 90 performing large restore operations 233
determining the replication status 92 processing include-exclude 122
disabling 93 query archive information 638
other components 90 query backup information 640
requirements 88 query user access 637
restore 221 renaming file spaces that are not Unicode to Unicode-
restrictions 89 enabled 315, 698
retrieve 221 restore hard-linked 209
fbbranch option 381 restore or retrieve to another workstation 238
fbclient option 382 restore sparse 209
fbpolicyname option 383 restore, using commands 236
fbreposlocation option 384 restoring 231
fbserver option 385 restoring files belonging to another node 237
fbvolumename option 386 retrieve archived 248
file restore retrieve using commands 248
configuring options 139 retrieving files belonging to another node 237
options 140 sorting list of 142
file space filesonly option 390
delete 171, 239, 622 firewall
determining fsID 342 establishing communications through 68, 397, 526
excluding 114 specifying TCP/IP ports for the web client 582
NAS or client objects 321 using web client through 582
performing an image backup 602 whether server or client initiates sessions through 490
file spaces 156 folders
file specification incremental backup processing overview 158

Index 737
followsymbolic option 391 H
force incremental backup 306
forcefailover option 392 hard links
format archive and retrieve 247
summary of options 294 back up 209
format and language restore 209
summary of options 294 hard mounts, NFS 209
fromdate option 393 hardware requirements, AIX 3
fromnode option 394 hardware requirements, HP-UX Itanium 2 4
fromowner option 395 hardware requirements, Linux on Power Systems 5
fromtime option 395 hardware requirements, Linux System z 6
full backups, creating 200 hardware requirements, Linux x86_64 5
full incremental hardware requirements, Mac OS X 7
comparing with incremental-by-date 162 hardware requirements, Solaris 8
comparing with journal-based, incremental-by-date 162 help
definition 158 displaying online 143
description 158 Internet resources 143
when to use 162 online forum 143
fuzzy backup 269 service and technical support 143
help command 626
host option 397
G HP-UX components
getting started installable 4
changing your password 125 HP-UX Itanium 2 API
client scheduler 125 communication methods 4
command-line session 125 installing 12
displaying online help 125 uninstalling 14
ending a session 125 HP-UX Itanium 2 client
GUI session 125 increasing default limit of data segment size 14
sorting file lists 125 HP-UX Itanium 2 disk space 4
web client session 125 HP-UX Itanium 2 hardware requirements 4
GPFS file system HP-UX Itanium 2 software requirements 4
multinode cluster environment 151, 349 HP-UX Itanium 2 system requirements 4
scheduling 177 httpport option 397
storage pools 223
graphical user interface I
changing password 140
delete individual files or images from server file space IBM Knowledge Center xxi
618 IBM PowerHA SystemMirror cluster
displaying active and inactive backup versions 142, 231 scheduling 175
displaying online help 143 IBM Spectrum Protect
displaying processing status 202 client components
enabling for local backupset restore 428 AIX client 3
enabling local backup set 216 Linux on Power Systems client 4
ending a session 143 Linux on System z client 6
performing image backup 183 Linux x86_64 client 5
starting a session 132 Mac OS X client 7
using to back up objects 166 Oracle Solaris client 7
group backup communication methods
display active and inactive objects 401 AIX client 3
display all members of 493 HP-UX Itanium 2 API 4
overview 172 Linux on Power Systems client 5
specify name of group 396 Linux on System z client 6
specify virtual file space name for 539 Linux x86_64 client 6
specifying full or differential 435 Mac OS X client 7
groupname option 396 Oracle Solaris client 8
GUI installation requirements 7
ending a session 143 online forum 144
overriding management class during archive 272 password 133
performing point-in-time restore 224 upgrading from earlier versions of the product 1
starting a session 132 IBM Spectrum Protect client
authentication 131
IBM Spectrum Protect on Mac OS X client
uninstalling 41

738 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
IBM Spectrum Protect on Oracle Solaris SPARC API include-exclude processing (continued)
installation steps 45 overview 113
uninstalling 46 include.vm option 410
IBM Spectrum Protect on Oracle Solaris x86_64 client INCLUDE.VMDISK 411
installation steps 42 INCLUDE.VMLOCALSNAPSHOT 413
uninstalling 44 include.vmresetcbt option 414
IBM Spectrum Protect password include.vmsnapshotattempts option 416
using 133 include.vmtsmvss option 418
ieobjtype option 399 incrbydate option 420
ifnewer option 399 incremental backup
image associating local snapshot with server file space 504
restoring 213 back up new and changed files with modification date
using chkdsk to repair 213 later than last backup 420
using chkdsk tool to repair 677 by date 167
using fsck to repair 213, 677 client command line 167
image backup client domain 349
considerations 179 command line 167
deleting 618 description 158
excluding files from 374 directories, processing overview 158
include files for; assign management class to 403 folders, overview 158
include.dedup 403 GPFS, multinode cluster environment 151, 349
incremental-by-date image backup 183 memory-conserving algorithm 434
perform 178 new and changed files 158
point-in-time restore 605 new and changed files with modification date later than
revoke access 616 last backup 420
specifying selective or incremental 435 of directories
static, dynamic, snapshot 178 processing overview 158
using command line 185 of folders
using the GUI 183 processing overview 158
using with file system incremental 183 optimizing memory during 150
using with incremental-by-date 182 overview 158
volume device type support 180 process a list of files 387
with incremental backup 181, 605 skip acl update checking 494
image backup, considerations 179 symbolic links 207
image to file using client Java GUI 166
restoring 222 with image backup 181, 605
imagegapsize option 400 incremental command
imagetofile option 401 journal-based backup 631
inactive backup versions incremental option 421
displaying 142, 231, 640 incremental-by-date
restoring 231 client command line 167
inactive option 401 command line 167
inclexcl option 402 comparing with incremental 162
include comparing with incremental, journal-based 162
INCLUDE.VMDISK 411 description 162
INCLUDE.VMLOCALSNAPSHOT 413 of directories
include option processing overview 162
management class 271 overview 158
processing 122 when to use 162
wildcard characters 117, 118 incremental-by-date backup
include VM templates in back ups 552 using client Java GUI 166
include-exclude list using with image backup 182
creating 112 incremental, associating local snapshot with server file
preview 121 space 178
query order of processing 652 input strings
size restriction 122 containing blanks 135
include-exclude options file installation
bottom-up processing 122 backup-archive client 9
overview 150 installation requirements
specifying path and file name of 402 AIX client 3
to manage archives 249 client 3
Unicode-enabled file spaces 402 HP-UX Itanium 2 API 4
include-exclude processing Linux for zSeries client 6
options for 113 Linux on Power Systems 4

Index 739
installation requirements (continued) journal-based backup (continued)
Linux x86_64 client 5 starting the journal daemon 75
Solaris client 7 stopping the journal daemon 75
installation steps when to use 162
IBM Spectrum Protect on Oracle Solaris SPARC API 45 JournalSettings stanza 76
IBM Spectrum Protect on Oracle Solaris x86_64 client
42
Mac OS X client 40
K
installing keyboard 723
AIX client 9 Knowledge Center xxi
HP-UX Itanium 2 API 12
Linux on Power Systems (Big Endian) API 23
Linux on Power Systems (Little Endian) client 15 L
Linux on System z client 36
LAN-based image backup
Linux x86_64 client 26
snapshot image backup 602
Mac OS X client 40
LAN-free data movement
overview 1
enabling communications for 147, 423, 425
Solaris SPARC API 45
options 147
Solaris x86_64 client 42
prerequisites 147
Ubuntu Linux on Power Systems (Little Endian) API 19
shared memory port for 425
Ubuntu Linux on Power Systems (Little Endian) client 19
lanfreecommmethod option 423
Ubuntu x86_64 client 31
lanfreeshmport option 425
installing IBM Spectrum Protect
lanfreessl option 426
cluster environment 95
lanfreetcpport option 425
installing the client management service 47
lanfreetcpserveraddress option 427
instrlogmax option 421
LANG environment variable
instrlogname option 422
setting language locale 58
instrumentation log
language locales
collecting performance information 366
supported 58
controlling the size 421
last access date
specifying path and file name to store performance
specifying whether to update during backup or archive
information 422
158, 457
interactive mode 588
latest option 427
interactive session
Linux Logical Volume Manager
ending 633
snapshot image backup of volumes 178
starting 134, 633
Linux on Power Systems (Big Endian) API
using 633
installing 23
Linux on Power Systems (Little Endian) client
J installing 15
uninstalling 18
Java GUI Linux on Power Systems API
configuration restrictions 133 uninstalling 25
journal based backup Linux on Power Systems client
restoring 161 client components 4
journal based backups communication methods 5
restoring 161 Linux on Power Systems components
journal configuration file installable 4
how to configure 75 Linux on Power Systems disk space 5
journal daemon Linux on Power Systems hardware requirements 5
journal configuration file settings 75 Linux on Power Systems software requirements 5
starting the journal daemon 75 Linux on Power Systems system requirements 5
stopping the journal daemon 75 Linux on System z client
journal database files client components 6
errorlog 76 communication methods 6
journaldir 76 installing 36
journal-based backup uninstalling 39
comparing with incremental, incremental-by-date 162 Linux on System z components
excluding directories 114 installable 6
excluding files 114 Linux System z disk space 6
include-exclude options Linux System z hardware requirements 6
journal-based backup 114 Linux System z software requirements 6
performing traditional full incremental, instead of 443, Linux System z system requirements 6
631 Linux x86_64 client
specifying configuration settings 75

740 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
Linux x86_64 client (continued) management class
client components 5 assigning 206
communication methods 6 management classes
installing 26 assigning to directories 272, 345
uninstalling 30, 35 assigning to files 271
Linux x86_64 components binding archive files to 243
installable 5 binding to files 273
Linux x86_64 disk space 5 default 266
Linux x86_64 hardware requirements 5 displaying 267
Linux x86_64 software requirements 5 displaying information about 653
Linux x86_64 system requirements 5 how IBM Spectrum Protect uses 150
local backup set overriding during archive processing 272
enabling GUI for local restore 216 overriding the default 271
local snapshot processing 271
associating a local snapshot with a server file space 178 questions to consider 270
localbackupset option 428 selecting for files 270
log specifying with include option 271
controlling the size 421 using management class, example 271
DSM_LOG environment variable 372, 422, 482 maxcmdretries option 431
error log, pruning 371 mbobjrefreshthresh 432
errorlogname option 372 mbpctrefreshthresh 433
errorlogretention option 372 memory
instrlogmax option 421 optimizing when constrained 150
intrlogname option 422 memoryefficientbackup option 434
schedlogname option 482, 696 messages
schedlogretention option 482, 696 displaying on screen 538
specifying path and file name 372, 422, 482, 696 stop displaying 464
web client 481 migrating backup-archive clients 1
See also schedule log migration
logical volume web client 1
image backup of 178 web client language files 1
restoring 213, 222 migration of file spaces to Unicode 157
logs mode option 435
dsmsched.log 483 mode parameter 268
dsmsched.pru 483 modes
dsmwebcl.log 483 batch 588
dsmwebcl.pru 483 interactive (loop) 588
truncating application logs 418 modified mode 268
loop command 633 monitor option 438
LVM monitor process command 635
bring up an application after LVM starts 455 myreplicationserver option 438
quiesce an application before LVM starts 461
N
M
NAS
Mac OS X client assigning management class to file systems 403
client components 7 backing up file systems 189
communication methods 7 deleting file spaces 171, 239, 622
installation steps 40 query node command 654
installing 40 restore file systems 229, 679
Mac OS X components restore NAS command 679
installable 7 specifying full or differential backup 435
Mac OS X disk space 7 NAS file systems backup
Mac OS X hardware requirements 7 backup-archive client
Mac OS X software requirements 7 GUI 190
Mac OS X system requirements 7 command line 191
Macintosh client nasnodename option 440
environment prerequisites 7 netapp file server 106
installation requirements 7 Network Attached Storage (NAS)
macro command 634 backup file systems 189
maintenance Network Attached Storage (NAS) file server
auto-update 2 deleting file spaces 171, 239
makesparsefile option 429 Network Data Management Protocol (NDMP) 8
managedservices option 430 Network File System (NFS)

Index 741
Network File System (NFS) (continued) options (continued)
backup file systems 193 autofsrename 315
network-attached storage (NAS automount 316
display nodes for which admin ID has authority 654 backmc 317
network-attached storage (NAS) backup
backup file systems 606 excluding system state 374
cancel backup and restore processes 615, 635 backup, summary 280
deleting file spaces 622 backupsetname 318
display file spaces on server 646 basesnapshotname 319
excluding files from backup 374 cadlistenonport 320
monitoring backup or restore operations 438 central scheduling, summary 292
querying file system images belonging to 640 changingretries 321
restore file systems 229, 679 class 321
specifying for query 534 collocatebyfilespec 322
specifying node name for operations 440 command processing, summary 294
specifying whether to save table of contents for each file commmethod 323
system backup 531 commrestartduration 324
new for backup-archive client V8.1.9 xxv commrestartinterval 325
NFS communication, summary 278
backing up file systems 193 compressalways 325
hard mounts 209 compression 326
soft mounts 209 console 328
virtual mount points 206 createnewbase 329
nfstimeout option 209, 441 csv file 330
NLSPATH environment variable datacenter 333
displaying help browser menu in your language locale datastore 333
58 dateformat 334
to display help browser menu in your language locale 58 dedupcachepath 337
no query restore 234 dedupcachesize 338
node deduplication 338
specifying type to query 534 defaultserver 339
node name 54 deletefiles 340
Node name field 237 description 341
nodename option 442 detail 342
nojournal option 443 diagnostics 297
noprompt option 443 diffsnapshot 343
nrtablepath option 444 diffsnapshotname 344
numberformat dirmc 345
specifying 445 dirsonly 346
numberformat option 445 disablenqr 347
diskbuffsize 347
diskcachelocation 348
O domain 349
online help domain.image 353
displaying 143 domain.nas 354
online forum 143 domain.vmfull 355
service and technical support 143 dontload 361
open registration dynamicimage 362
permissions 112 efsdecrypt 363
using 112 enablearchiveretentionprotection 363
operating system requirements enablededupcache 365
clients 3 enableinstrumentation 366
optfile option 447 enablelanfree 367
options encryptiontype 150, 368
absolute 306 encryptkey
afmskipuncachedfiles 307 encryptkey=generate 369
archive, summary 280 encryptkey=prompt 369
archmc 308 encryptkey=save 369
archsymlinkasfile 308 errorlogmax 371
asnodename 309 errorlogname 372
auditlogging 311 errorlogretention 373
auditlogname 312 exclude
authorization options 294 exclude.archive 113, 374
autodeploy 314 exclude.attribute.symlink 113, 374

742 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
options (continued) options (continued)
exclude (continued) lanfreessl 426
exclude.backup 113, 374 lanfreetcpport 425
exclude.compression 113, 374 lanfreetcpserveraddress 427
exclude.dir 113, 374 latest 427
exclude.encrypt 374 localbackupset 428
exclude.file 113, 374 makesparsefile 429
exclude.file.backup 113, 374 managedservices 430
exclude.fs 113, 374 maxcmdretries 431
exclude.fs.nas 374 mbobjrefreshthresh 432
exclude.image 113, 374 mbpctrefreshthresh 433
wildcard characters 117, 118 memoryefficientbackup 434
exclude.dedup 374 mode 435
EXCLUDE.VMDISK 378 monitor 438
EXCLUDE.VMLOCALSNAPSHOT 380 myreplicationserver 438
fbbranch 381 nasnodename 440
fbclient 382 nfstimeout 441
fbpolicyname 383 nodename 442
fbreposlocation 384 nojournal 443
fbserver 385 noprompt 443
fbvolumename 386 nrtablepath 444
filelist 387 numberformat 445
filename 389 optfile 447
filesonly 390 order of processing (precedence) 297
followsymbolic 391 password 447
forcefailover 392 passwordaccess 449
format and language, summary 294 passworddir 450
format, summary 294 pick 451
fromdate 393 pitdate 452
fromnode 394 pittime 453
fromowner 395 postnschedulecmd 453
fromtime 395 postschedulecmd 453
general rules when entering with commands 298 postsnapshotcmd 455
groupname 396 prenschedulecmd 456
host 397 preschedulecmd 456
httpport 397 preservelastaccessdate 457
ieobjtype 399 preservepath 458
ifnewer 399 presnapshotcmd 461
imagegapsize 400 queryschedperiod 462
imagetofile 401 querysummary 463
inactive 401 quiet 464
inclexcl 402 quotesareliteral 465
include removeoperandlimit 466
wildcard characters 117, 118 replace 466
include.archive 403 replserverguid 467
include.attribute.symlink 403 replservername 469
include.backup 403 replsslport 470
include.compression 403 repltcpport 472
include.encrypt 403 repltcpserveraddress 474
include.file 403 resourceutilization 475
include.fs.nas 403 restore and retrieve, summary 289
include.image 403 retryperiod 477
include.vm 410 revokeremoteaccess 478
INCLUDE.VMDISK 411 schedcmddisabled 479
INCLUDE.VMLOCALSNAPSHOT 413 schedcmduser (server defined only) 260
include.vmresetcbt 414 schedgroup 480
include.vmsnapshotattempts 416 schedlogmax 481
include.vmtsmvss 418 schedlogname 482
incrbydate 420 schedlogretention 483
incremental 421 schedmode 485
instrlogmax 421 schedrestretrdisabled 486
instrlogname 422 scrolllines 487
lanfreecommmethod 423 scrollprompt 488
lanfreeshmport 279, 425 servername 489

Index 743
options (continued) options (continued)
sessioninitiation 490 vmdefaultnetwork 551
setwindowtitle 491 vmenabletemplatebackups 552
shmport 492 vmlimitperdatastore 554
showmembers 493 vmlimitperhost 555
skipacl 493 vmmaxbackupsessions 556
skipaclupdatecheck 494 vmmaxparallel 558
snapdiff 104, 494 vmmaxparallelrestoresessions 560
snapdiffchangelogdir 499 vmmaxparallelrestorevms 561
snapdiffhttps 501 vmmaxrestoresessions 559
snapshotcachesize 502 vmmc 564
snapshotproviderfs 503 vmnocbtcontinue 564
snapshotproviderimage 504 vmnoprdmdisks 565
snapshotroot 504 vmnovrdmdisks 566
specifying in commands 297 vmpreferdagpassive 567
srvoptsetencryptiondisabled 506 vmprocessvmwithprdm 569
srvprepostscheddisabled 507 vmprocesswithindependent 568
srvprepostsnapdisabled 508 vmskipctlcompression 570
ssl 509 vmskipmaxvirtualdisks 570
sslacceptcertfromserv 510 vmskipmaxvmdks 571
sslrequired 512 vmtagdatamover 572
stagingdirectory 514 vmtagdefaultdatamover 574
subdir 515 vmtimeout 581
system state vmverifyifaction 576
exclude from backup processing 374 vmverifyiflatest 578
tagsched 517, 519 vmvstorcompr 579
tapeprompt 520 vmvstortransport 580
tcpadminport 522 web client, summary 296
tcpbuffsize 522 webports 582
tcpcadaddress 523 wildcardsareliteral 583
tcpclientaddress 524 Oracle Solaris client
tcpclientport 524 client components 7
tcpnodelay 525 communication methods 8
tcpport 526 Oracle Solaris components
tcpserveraddress 526 installable 7
tcpwindowsize 527
timeformat 528
toc 531
P
todate 532 parallel backups 202, 554–556, 558
totime 532 parameters
transaction processing, summary 295 yes and no, alternatives 306
txnbytelimit 533 partial incremental
type 534 definition 158
updatectime 535 incremental-by-date
useexistingbase 535 running 167
usereplicationfailover 536 password
v2archive 537 changing 140, 706
verbose 538 number of characters 140
verifyimage 539 setting 447
virtual machine exclude options 378 setting for client 112
virtual machine include options 410 specifying directory location to store encrypted
virtualfsname 539 password file 450
virtualmountpoint 539 specifying whether to generate automatically or set as
virtualnodename 541 user prompt 449
vmbackdir 541 using 133
vmbackuplocation 542 valid characters 140
vmbackupmailboxhistory 544 password location 130
vmbackuptype 544 password option 447
vmchost 545 password store 130
vmcpw 546 passwordaccess option 449
vmcuser 548 passworddir option 450
vmdatastorethreshold 548 performance
vmdefaultdvportgroup 550 improving speed of backups, restores, archives,
vmdefaultdvswitch 551 retrieves 279

744 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
performance (continued) QFS file system (continued)
transaction options 295 restrictions 151
transaction processing 533 query
performing traditional full incremental backup 631 amount of information that displays on screen 487
permissions backups, establish point-in-time 452, 453
access, saving standard and extended 246 based on date and time of backup, archive 393, 395
pick option 451 description for 341
PIHDW plugin 361 display active and inactive objects 401
pitdate 452 files for another node 394
pittime option 453 group
plug-in library command 648
for image or NAS backup or restore 59 display members of 493
point-in-time restore include-exclude list 652
image backup 605 NAS or client objects 321
policies, storage management 265 nodes to which client has proxy authority 244
policy domains nodes to which client has proxy node authority 172
default policy domain 265 process directories only (not files) 346
standard policy domain 265 scrolling preferences after displaying information on
policy sets screen 488
active policy set 265 system information 658
portable media query access command 637
restoring backup sets 216 query archive command 638
postnschedulecmd option 453 query backup command 640
postsnapshotcmd option 455 query backupset command 643, 645
Preferences editor query filespace command 646
excluding domains from back up 166 query group command 648
prenschedulecmd option 456 query image command 650
preschedulecmd option 456 query inclexcl command 652
preservelastaccessdate option 457 query mgmtclass command 267, 653
preservepath option 458 query node command 654
Presnapshotcmd option 461 query options command 655
preview query restore command 656
include-exclude list 121 query schedule
restore vm 681, 691 enhanced 258
preview archive command 635 query schedule command 657
preview backup command 636 query schedule command, enhanced 657
processing aliases 408 query session command 657
processing options query systeminfo command
authorization 294 encryption processing 658
backup and archive 280 query VM command 659
central scheduling 292 queryschedperiod option 462
communication 278 querysummary option 463
diagnostics 297 quiesce applications 418
error processing 295 quiet option 464
format 294 quotesareliteral option 465
format and language 294
overview 277
restore and retrieve 289
R
specifying in commands 297 raw logical volume
transaction processing 295 image backup of 178
using 125, 128, 277 restoring 213
web client 296 rebinding files to a different management class 273
processing symbolic links 408 registering
processing symbolic links and aliases 377 client with server 111
processing time using closed registration 112
estimating 166 using open registration 112
protecting Btrfs file systems 187 removeoperandlimit option 466
protecting Btrfs subvolumes 188 replace option 466
proxied session restrictions 173, 244 replserverguid option 467
publications xxi replservername option 469
replsslport option 470
Q repltcpport option 472
repltcpserveraddress option 474
QFS file system resourceutilization option 475

Index 745
restart restore command restore (continued)
restart interrupted restore 236 raw logical volume 213
restartable restore 234 replace existing file with latest backup 399
restartable restore sessions, display 656 restartable 234
restore sorting file list 142
active version 231 standard (also known as classic) 234
authorizing another user 236 starting a web client session 136
backup set starting a web user interface session 137
supported tape devices 668, 672 summary of options 289
backup sets symbolic links
overview 216 UNIX and Linux restrictions 664
backups, establish point-in-time 452, 453 to different workstation 541
based on date and time of backup 393, 395 using commands 236
btrfs 186 using fsck tool to repair 677
classic (also known as standard) 234 whether to prompt before overwriting existing files 466
configuring options 139 restore backupset command 668, 672
create list of backup versions to 451 restore backupset command considerations 218, 671
data using command line 232 restore command
disk 238 performing large operations 233
display active and inactive objects 401 restore group command 675
during failover 221 restore hard links 209
enable SELinux 240 restore image
Encrypted File Systems (EFS) 227 btrfs 186
file 139, 140 restore image command 677
files and directories 231 restore maximum file size 155
files belonging to another node 237 restore NAS command 679
files for another node 394 restore sparse files 209
files for another user 395 restore vm command
files to another workstation 238 preview 681, 691
from file spaces that are not Unicode-enabled 668 restoring data from retention set
from portable media using command line 226
overview 216 using GUI 226
group restoring point-in-time
command 675 using command line 224
GUI, displaying active and inactive versions 142 using GUI 224
image restoring retained data 226
considerations 677 restrictions
enable detection of bad sectors on target volume asnodename option 309
539 asnodename session settings 310
to a file 401 specifying full path with client acceptor daemon 447
using chkdsk tool to repair 213 within a proxied session 173, 244
using DSM_DIR to point to plug-in library 59 retain extra versions attribute 268
using fsck tool to repair 213 retain only versions attribute 268
image to file 222 retain versions attribute 270
image, suppress confirmation prompt 443 retention grace period
improving speed using share memory 279 archive 266, 273
inactive version 231 backup 266, 273
list of files 387 retrieve
local backup set using the GUI 216 archive copies 247
logical volume 213, 222 archived files using commands 248
most recent backup version 427 authorizing another user 236
NAS based on date and time of archive 393, 395
using DSM_DIR to point to plug-in library 59 btrfs 186
NAS file systems description for 341
backup-archive client GUI 229 during failover 221
command line 230 files belonging to another node 237
no query 234 files for another node 394
non-root users on RHEL 5 240 files to another workstation 238
options 140 hard links 247
overview 213 improving speed using share memory 279
performing large operations 233 list of files 387
primary tasks 213 primary tasks 241
process directories only (not files) 346 process directories only (not files) 346
processing status window 231

746 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
retrieve (continued) scheduler (continued)
replace existing file with latest archive if existing file is managed by client acceptor daemon 430
newer 399 number of hours between contacts to server for
running 248 scheduled work 462
sorting file list 142 number of minutes between attempts to process
starting a web client session 136 scheduled commands 477
starting a web user interface session 137 options for 260
summary of options 289 polling mode or prompted mode 485
symbolic links 246 resolving memory retention after scheduled backups
to different workstation 541 430
whether to prompt before overwriting existing files 466 starting 66
retrieve command 693 whether server or client initiates sessions through
retrieve maximum file size 155 firewall 490
retryperiod option 477 whether to disable execution of restore or retrieve
return codes for operations 263 operations 486
revokeremoteaccess option 478 scheduler comparison
root user client acceptor versus traditional scheduler 64
acquiring root user access 49 scheduling
root user tasks client node proxy 174
creating default client user-options file 56 client node proxy backup 172
setting up 54 GPFS file system 177
running a snapshot difference backup IBM PowerHA SystemMirror cluster 175
with HTTPS 164 scrolllines option 487
running a snapshot differential backup scrollprompt option 488
with HTTPS 164 Secure Sockets Layer (SSL)
establishing communications with 70
selective backup
S associating local snapshot with server file space 178
SAN client command line 167
restoring backup sets using 672 command line 167
schedcmddisabled option 479 overview 158, 165, 167
schedcmduser option (server defined only) 260 symbolic links 207
schedgroup option 480 using the client Java GUI 166
schedlogmax option 481 selective command 698
schedlogname option 482 self-contained application protection 418
schedlogretention option 483 serialization
schedmode option 485 copy serialization
schedrestretrdisabled option 486 dynamic 269
schedule command 696 shared static 269
schedule log static 269
controlling the size 481 server
specifying number of days to keep entries and whether communicating with 54
to save pruned entries 483 establishing communications through firewall 68
specifying path and file name to store schedule log establishing communications with 54
information 482 establishing communications with Secure Sockets Layer
scheduled (automated) backups (SSL) 70
closing files before back up 210 identify to begin a stanza containing options for 489
displaying scheduled work 258, 259 specifying name of server to contact for services 489
options for 260 TCP/IP address of IBM Spectrum Protect server 526
process commands after backup 453 TCP/IP port address for 526
process commands before backup 456 server options
restart applications after back up 210 Sslfipsmode 512
starting 66 servername option 489
scheduled commands service and technical support 143
enabling-disabling 260 session information, displaying 657
scheduled events, displaying 657 sessioninitiation option 490
scheduled services set access command
defining schedules for UID other than zero 260 restore-retrieve authorization 236
disabling scheduled commands 479 set event command 703
restrictions for NAS file systems 189 set netappsvm 106
scheduler set password command 706
configuring 63 set vmtags command 711
displaying scheduled work 258, 259 setting
event logging 259 user privileges 137

Index 747
setting environment variables SSL (Secure Socket Layer)
API, UNIX and Linux establishing communications with 70, 72
DSMI_CONFIG 61 ssl option 509
DSMI_DIR 61 sslacceptcertfromserv option 510
DSMI_LOG 61 Sslfipsmode option 512
setting language locale 58 sslrequired option 512
setting up stagingdirectory option 514
required root user tasks 54 standard (classic) restore 234
setwindowtitle 491 standard management class
shared dynamic serialization 269, 321 copy destination 270
shared memory communication method copy frequency 268
options 279 copy group name 268
shared static serialization 269, 321 copy mode
shell scripts absolute 269
return codes from 263 modified 269
using commands in 263 copy serialization 269
shmport option 492 copy type 268
showmembers option 493 deduplicate data attribute 270
skipacl option 493 default values 267
skipaclupdatecheck option 494 retain extra versions 268
snapdiff option 104, 494 retain only version 268
snapdiffchangelogdir option 499 retain versions 270
snapdiffhttps option 501 versions data deleted
snapshot difference active versions 268
with HTTPS 163 inactive versions 268
snapshot differential backup versions data exists 268
with HTTPS 163 standard policy domain 265
snapshot differential backup with HTTPS connection 501 start the client scheduler at startup 256
snapshot-differential-incremental backup 494 starting
snapshotcachesize option 502 automatically
snapshotproviderfs option 503 overview 1
snapshotproviderimage option 504 starting a session
snapshotroot option 504 batch mode 134
snapshots interactive mode 134
configuring 104 static serialization 269
soft mounts, NFS 209 storage
software requirements, AIX 3 displaying restartable restore sessions 656
software requirements, HP-UX Itanium 2 4 Storage Agent
software requirements, Linux on Power Systems 5 for LAN-free data movement 147
software requirements, Linux System z 6 using for LAN-free data movement 367
software requirements, Linux x86/x86_64 5 storage area network
software requirements, Mac OS X 7 for LAN-free data movement 147
software requirements, Solaris 8 restoring backup sets using 367, 672
Software updates 47 using for LAN-free data movement 367
Solaris disk space 8 storage management policies
Solaris hardware requirements 8 assigning management classes to files 206
Solaris software requirements 8 copy groups 266
Solaris SPARC API default management class 265
installing 45 display on backup-archive client GUI 206
installing in Solaris zones 45 include-exclude list 266
Solaris system requirements 8 management classes 266
Solaris x86_64 client policy domains
installing 42 default 265
installing in Solaris zones 42 standard 265
Solaris zones 165 policy sets
sparse files active policy set 265
back up 209 storage pools
restore 209 GPFS 223
specifying how to restore or retrieve 429 subdir option 515
special file systems 151, 206 subdirectories
specifying whether to update last access date 457 archive 243
srvoptsetencryptiondisabled option 506 include in backup 167
srvprepostscheddisabled option 507 support
srvprepostsnapdisabled option 508 gathering system information for 328, 389, 658

748 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
supported language locales 58 Tivoli Storage Manager FastBack installation requirements 8
swing-enabled browser toc option 531
necessary to run web client 136, 137 todate option 532
symbolic links totime option 532
archiving and retrieving 246 traditional full incremental backup 160
back up 207 transaction processing
backing up 408 summary of options 295
exclude from backup 408 txnbytelimit option 533
exclude options 408 TSM.sth file 369
processing 408 tsmjbbd.ini
restoring configuring 75
UNIX and Linux restrictions 664 txnbytelimit option 533
symbolic links and aliases type option 534
backing up 377, 408
exclude from backup 377, 408
exclude options 377, 408
U
processing 377, 408 Ubuntu Linux on Power Systems (Little Endian) API
syntax diagram installing 19
reading xxii uninstalling 22
repeating values xxii Ubuntu Linux on Power Systems (Little Endian) client
required choices xxii installing 19
system files uninstalling 22
excluding 116 Ubuntu x86_64 client
system information installing 31
gathering 328, 389 Unicode
system requirements, AIX 3 migrating file spaces to 157
system requirements, HP-UX Itanium 2 4 renaming file spaces that are not Unicode to Unicode-
system requirements, Linux on Power Systems 5 enabled 315, 698
system requirements, Linux System z 6 restore from file spaces that are not Unicode-enabled
system requirements, Linux x86_64 5 668
system requirements, Mac OS X 7 uninstalling
system requirements, Solaris 8 AIX client 12
system state HP-UX Itanium 2 API 14
display active and inactive objects 401 IBM Spectrum Protect on Mac OS X client 41
IBM Spectrum Protect on Oracle Solaris SPARC API 46
T IBM Spectrum Protect on Oracle Solaris x86_64 client
44
tagsched option 517, 519 Linux on Power Systems (Little Endian) client 18
tapeprompt option 520 Linux on Power Systems API 25
tasks Linux on System z client 39
assigning management classes to directories 272 Linux x86_64 client 30, 35
closed registration 111 Ubuntu Linux on Power Systems (Little Endian) API 22
display management classes 267 Ubuntu Linux on Power Systems (Little Endian) client 22
GUI, override management class 272 UNIX
open registration 111 file systems, ACL support 151
password, change 140 saving standard access permissions 246
root user 49 UNIX and Linux
sessions, ending 140 cluster environment
TCP/IP communication method installing IBM Spectrum Protect 95
options 278 restrictions
tcpadminport option 522 restoring symbolic links 664
tcpbuffsize option 522 updatectime option 535
tcpcadaddress option 523 updating the client automatically 2
tcpclientaddress option 524 upgrading backup-archive clients 1
tcpclientport option 524 upgrading the backup-archive client from earlier versions of
tcpnodelay option 525 the product 1
tcpserveraddress option 526 useexistingbase option 535
tcpwindowsize option 527 user privileges
time format setting 137
specifying 528 usereplicationfailover option 536
timeformat option 528 using multiple sessions 202
Tivoli Storage Manager FastBack configuration 94
Tivoli Storage Manager FastBack data backup 202
Tivoli Storage Manager FastBack data restore 202

Index 749
V VMware tagging (continued)
represented as data protection settings 713
v2archive option 537 supported data protection tags 713
verbose option 538 tips for configuring backup policies 722
verifyimage option 539 VMware tagging support
versions data enable 572
deleted attribute 268 VMware virtual machine backups
deleted parameter 268 types 197
exists attribute 268 volume label
exists parameter 268 duplicate names 156
virtual machine volume name 156
exclude options 378 volume naming precautions
include options 410 dual boot systems 156
virtual mount point, setting 166 UNIX mount point 156
virtualfsname option 539 vStorage backup server
virtualmountpoint option 539 off-host backup 199
virtualnodename option
restore or retrieve to another workstation 238
VM 197
W
vmbackdir option 541 web client
vmbackuplocation option 542 configuration overview 62
vmbackupmailboxhistory 544 configuring 62
vmbackuptype option 544, 564 enable to run in a swing-enabled browser 136
vmchost option 545 establishing communications through firewall 397
vmcpw option 546 restrict administrator from accessing client running web
vmctlmc option client 478
options restrictions for NAS file systems 189
vmctlmc 547 specifying TCP/IP port address for 397
vmcuser option 548 starting 136
vmdatastorethreshold summary of options 296
option 548 supported browsers 136
vmdefaultdvportgroup option 550 unsupported functions 145
vmdefaultdvswitch option 551 using through a firewall 582
See also vmdefaultdvportgroup web client configuration overview 62
vmdefaultnetwork option 551 web user interface
vmenabletemplatebackups option 552 enable to run in a swing-enabled browser 137
vmlimitperdatastore option 554 starting 137
vmlimitperhost option 555 supported browsers 137
vmmaxbackupsessions option 556 webports option 582
vmmaxparallel option 558 wildcard characters
vmmaxparallelrestoresessions option 560 guidelines 592
vmmaxparallelrestorevms option 561 include or exclude files 117
vmmaxrestoresessions option 559 include or exclude groups of files 117
vmnocbtcontinue option 564 specifying a drive specification in dsm.opt 117
vmnoprdmdisks 565 to include or exclude groups of files 118
vmnovrdmdisks 566 using with commands 211
vmpreferdagpassive option 567 using with file specifications 211
vmprocessvmwithprdm 569 wildcardsareliteral option 583
vmprocesswithindependent 568
vmskipctlcompression option 570
vmskipmaxvirtualdisks 570 Z
vmskipmaxvmdks 571
Zettabyte file systems (ZFS)
vmtagdatamover
backup file systems 195
option 572
vmtagdefaultdatamover
option 574
vmtimeout option 581
vmverifyifaction 576
vmverifyiflatest 578
vmvstorcompr option 579
vmvstortransport option 580
VMware tagging
inheritance 720
overview 712

750 IBM Spectrum Protect UNIX and Linux Backup-Archive Clients: Installation and User's Guide
IBM®

Product Number: 5725-W98

5725-W99
5725-X15