mmbackup command

Availability

Available with IBM Spectrum Scale™ Standard Edition or higher. Available on AIX® and Linux.

Description

Use the mmbackup command to back up the user data from a GPFS file system or independent fileset to a TSM server or servers. The mmbackup command can be used only to back up file systems that are owned by the local cluster.

The IBM Spectrum Protect Backup-Archive client must be installed and at the same version on all the nodes that are executing the mmbackup command or are named in a node specification with -N. For more information about TSM requirements for the mmbackup command, see IBM Spectrum Scale port usage.

You can run multiple simultaneous instances of mmbackup if they are on different file systems or filesets.

See the topic Backup considerations for using IBM Spectrum Protect in the IBM Spectrum Scale: Concepts, Planning, and Installation Guide and the topic Configuration reference for using IBM Spectrum Protect with IBM Spectrum Scale in the IBM Spectrum Scale: Administration Guide.

Parameters

Device

The device name for the file system to be backed up. File system names do not need to be fully qualified. fs0 is as acceptable as /dev/fs0.

Directory

Specifies either the mount point of a GPFS file system or the path to an independent fileset root to back up. /gpfs/fs0 can be used to specify the GPFS file system called fs0.

Note: A snapshot directory path is not permitted. To back up a snapshot, use -S SnapshotName instead. Do not use a subdirectory path as this leads to inconsistent backups.

-t {full | incremental}

Specifies whether to perform a full backup of all of the files in the file system, or an incremental backup of only those files that changed since the last backup was performed. The default is an incremental backup.

A full backup expires all GPFS 3.2 format TSM inventory if all previous backups were incremental and the GPFS 3.2 backup format was in use previously. If mmbackup on GPFS 3.2 was first used, and then only incremental backups were done on GPFS 3.4 or 3.5, then TSM will still contain 3.2 format backup inventory. This inventory will automatically be marked for expiration by mmbackup after a successful full or incremental backup.

Note: Do not use -t full with an unlinked fileset. Use an EXCLUDE statement to exclude directories or files from the backup operation.

-N {Node[,Node...] | NodeFile | NodeClass}

Specifies a list of nodes to run parallel instances of the backup process for better performance. The IBM Spectrum Protect Backup-Archive client must be installed on each node in the list. All the nodes must be in the same cluster as the node from which the mmbackup command is issued. All node classes are supported. For more information about these options, see Specifying nodes as input to GPFS commands.

If the -N option is not specified, then the command runs parallel instances of the backup process on the nodes that are specified by the defaultHelperNodes attribute of the mmchconfig command. If the defaultHelperNodes attribute is not set, then the command runs only on the node where the mmbackup command is issued. For more information about the defaultHelperNodes attribute, see the topic mmchconfig command.

-g GlobalWorkDirectory

Specifies a global work directory in which one or more nodes can store temporary files during mmbackup command processing. For more information about specifying more than one node to process the command, see the description of the -N option.

The global directory must be in a shared file system, and the file system must be mounted and available for reading and writing by every node that will participate in the mmbackup command processing.

If the -g option is not specified, then the global work directory is the directory that is specified by the sharedTmpDir attribute of the mmchconfig command. For more information, see mmchconfig command. If the sharedTmpDir attribute is not set to a value, then the global work directory depends on the file system format version of the target file system:

• If the target file system is at file system format version 5.0.1 or later (file system format number 19.01 or later), then the global work directory is the directory .mmSharedTmpDir at the root level of the target file system.
• If the target file system is at a file system format version that is earlier than 5.0.1, then the command does not use a global work directory.

If the global work directory that is specified by -g option or by the sharedTmpDir attribute begins with a forward slash (/) then it is treated as an absolute path. Otherwise it is treated as a path that is relative to the mount point of the file system.

If both the -g option and the -s option are specified, then temporary files can be stored in both the specified directories. In general, the local work directory contains temporary files that are written and read by a single node. The global work directory contains temporary files that are written and read by more than one node.

-s LocalWorkDirectory

Specifies the local directory to be used for temporary storage during mmbackup command processing. The default directory is /tmp. A LocalWorkDirectory must exist on each node that is used to run the mmbackup command or specified in a node specification with –N.

-S SnapshotName

Specifies the name of a global snapshot for any backup operations or a fileset-level snapshot if --scope inodespace is also specified for a fileset backup. The snapshot must be created before the mmbackup command is used. Snapshot names can be found with the mmlssnapshot command. If a fileset is not present in the named snapshot and fileset-level backup is invoked with --scope inodespace, an error is returned. If a fileset-level snapshot name is used with a file system backup, an error is returned.

The use of -S SnapshotName is recommended because it provides mmbackup and TSM a consistent view of GPFS from which to perform backup. Deletion of the snapshot used for backup can be performed using the mmdelsnapshot command after mmbackup completes.

-f

Specifies that processing should continue when unlinked filesets are detected. All files that belong to unlinked filesets are ignored.

Note: Because -f has a large impact on performance, avoid using it unless performing a backup operation with unlinked filesets is necessary.

-q

Performs a query operation before beginning mmbackup. The TSM server may have data stored already that is not recognized as having been backed up by mmbackup and its own shadow database. To properly compute the set of files that currently need to be backed up, mmbackup can perform a TSM query and process the results to update its shadow database. Use the -q switch to perform this query and then immediately commence the requested backup operation.

Note: Do not use -q with the --rebuild parameter.

-v

Specifies verbose message output. Use this flag to cause mmbackup to issue more verbose messages about its processing. See also Environment.

-d

Gathers debugging information that is useful to the IBM® Support Center when diagnosing problems.

-a IscanThreads

Specifies the number of threads and sort pipelines each node runs during parallel inode scan and policy evaluation. The default value is 2.

-n DirThreadLevel

Specifies the number of threads that are created and dispatched within each mmapplypolicy process during the directory scan phase. The default value is 24.

-m ExecThreads

Specifies the number of threads created and dispatched within each mmapplypolicy process during the policy execution phase. The default value for mmapplypolicy is 24; however, the default value for mmbackup is 1. This option cannot be used with the --expire-threads and --backup-threads options.

--expire-threads ExpireThreads

Specifies the number of worker threads permitted on each node to perform dsmc expire tasks in parallel. This option cannot be used with the -m option. Valid values are 1 - 32. The default value is 4.

--backup-threads BackupThreads

Specifies the number of worker threads permitted on each node to perform dsmc selective or dsmc incremental tasks in parallel. This option cannot be used with the -m option. Valid values are 1 - 32. The default value is 1.

-B MaxFiles

Specifies the maximum number of objects in a bunch for each invocation of the mmapplypolicy EXEC script. If this option is not specified, the ideal bunch count is automatically computed. Valid values are 100 - 2147483647.

--max-backup-count MaxBackupCount

Specifies the maximum number of objects in a bunch for each dsmc selective or dsmc incremental command. This option cannot be used with the -B option. Valid values are 100 - 2147483647.

--max-expire-count MaxExpireCount

Specifies the maximum number of objects in a bunch for each dsmc expire command. This option cannot be used with the -B option. Valid values are 100 - 2147483647.

--max-backup-size MaxBackupSize

Specifies a policy limit on the content size in kilobytes for each dsmc selective or dsmc incremental command.

--qos QOSClass

Specifies the Quality of Service for I/O operations (QoS) class to which the instance of the command is assigned. If you do not specify this parameter, the instance of the command is assigned by default to the maintenance QoS class. This parameter has no effect unless the QoS service is enabled. For more information, see the topic mmchqos command. Specify one of the following QoS classes:

maintenance

This QoS class is typically configured to have a smaller share of file system IOPS. Use this class for I/O-intensive, potentially long-running GPFS commands, so that they contribute less to reducing overall file system performance.

other

This QoS class is typically configured to have a larger share of file system IOPS. Use this class for administration commands that are not I/O-intensive.

For more information, see the topic Setting the Quality of Service for I/O operations (QoS).

--quote | --noquote

Specifies whether to decorate (or not to decorate) file-list entries with quotation marks. The mmbackup command uses file lists to convey the lists of files to the IBM Spectrum Protect Backup-Archive client program. The file lists may or may not require each file name to be surrounded by quotation marks depending on TSM client configuration options. If certain TSM client configuration options are in use, the quotation marks should not be added to file-list entries. Use the --noquote option in these instances.

--rebuild

Specifies whether to rebuild the mmbackup shadow database from the inventory of the TSM server. This option is similar to the -q option; however, no backup operation proceeds after the shadow database is rebuilt. This option should be used if the shadow database of mmbackup is known to be out of date, but the rebuilding operation must be done at a time when the TSM server is less loaded than during the normal time mmbackup is run.

If there are backup files with the old snapshot name /Device/.snapshots/.mmbuSnapshot in the inventory of the TSM server, those files will be expired from the TSM server after the shadow database is rebuilt and any successful incremental or full backup completes.

Note: Do not use --rebuild with the -q parameter.

--scope {filesystem | inodespace}

Specifies that one of the following traversal scopes be applied to the policy scan and backup candidate selection:

filesystem

Scans all the objects in the file system specified by Device or mounted at the Directory specified. This is the default behavior.

inodespace

Specifies that the scan is limited in scope to objects in the same single inode space from which the Directory is allocated. The scan might span more than one fileset if those filesets share inode space; for example, dependent filesets.

--backup-migrated | --skip-migrated

HSM migrated objects are normally skipped even if they need to be backed up.

--backup-migrated

When specified, HSM migrated objects that need to be backed up are sent for backup. This can cause an HSM recall and other associated costs. When the same IBM Spectrum Protect server instance is used for HSM and backup, this option protects migrated, changed objects more efficiently. These objects are copied internally on the IBM Spectrum Protect server from the HSM storage pool directly to the BACKUP storage pool without incurring object recalls and their local storage costs. After backup, these objects will remain migrated. This occurs only if the object has no ACL or XAttrs attached.

--skip-migrated

When specified, HSM migrated objects that need to be backed up are not sent for backup. The path names of these objects are listed in a file, mmbackup.hsmMigFiles.TSMServer, located in the Directory/Device being backed up. The path names that are listed can then be recalled by the administrator in a staged manner. This is the default action that is taken for HSM migrated objects.

--tsm-servers TSMServer[,TSMServer...]

Specifies the name of the TSM server or servers to be used for this backup. The TSM servers specified are each used for the backup task specified.

If this option is not specified, the mmbackup command will backup to the servers that are specified in the dsm.sys file.

--tsm-errorlog TSMErrorLogFile

Specifies the path name of the log file to pass to IBM Spectrum Protect Backup-Archive client commands.

-L n

Controls the level of information displayed by the mmbackup command. Larger values indicate the display of more detailed information. n should be one of the following values:

0

Displays only serious errors. This is the default.

1

Displays some information as the command runs, but not for each file.

2

Displays each chosen file and the scheduled migration or deletion action.

3

Displays the same information as 2, plus each candidate file and the applicable rule.

4

Displays the same information as 3, plus each explicitly EXCLUDEed or LISTed file, and the applicable rule.

5

Displays the same information as 4, plus the attributes of candidate and EXCLUDEed or LISTed files.

6

Displays the same information as 5, plus non-candidate files and their attributes.

-P PolicyFile

Specifies a customized policy rules file for the backup.

Environment

The behavior of mmbackup can be influenced by several environment variables when set.

Variables that apply to IBM Spectrum Protect Backup-Archive client program dsmc

MMBACKUP_DSMC_MISC

The value of this variable is passed as arguments to dsmc restore and dsmc query {backup,inclexcl,session} commands.

MMBACKUP_DSMC_BACKUP

The value of this variable is passed as arguments to dsmc, dsmc selective, and dsmc incremental commands.

MMBACKUP_DSMC_EXPIRE

The value of this variable is passed as arguments to dsmc expire commands.

Variables that change mmbackup output progress reporting

MMBACKUP_PROGRESS_CONTENT

Controls what progress information is displayed to the user as mmbackup runs. It is a bit field with the following bit meanings:

0x01

Specifies that basic text progress for each server is to be displayed.

0x02

Specifies that additional text progress for phases within each server is to be displayed.

0x04

Specifies that numerical information about files being considered is to be displayed.

MMBACKUP_PROGRESS_INTERVAL

Controls how frequently status callouts are made. The value is the minimum number of seconds between calls to the MMBACKUP_PROGRESS_CALLOUT script or program. It does not affect how frequently messages are displayed, except for the messages of MMBACKUP_PROGRESS_CONTENT category 0x04.

MMBACKUP_PROGRESS_CALLOUT

Specifies the path to a program or script to be called with a formatted argument, as described in MMBACKUP_PROGRESS_CALLOUT environment variable.

Variables that change mmbackup debugging facilities

In case of a failure, certain debugging and data collection can be enabled by setting the specified environment variable value.

DEBUGmmbackup

This variable controls what debugging features are enabled. It is interpreted as a bit mask with the following bit meanings:

0x001

Specifies that basic debug messages are printed to STDOUT. There are multiple components that comprise mmbackup, so the debug message prefixes can vary. Some examples include:

mmbackup:mbackup.sh
DEBUGtsbackup33:

0x002

Specifies that temporary files are to be preserved for later analysis.

0x004

Specifies that all dsmc command output is to be mirrored to STDOUT.

DEBUGmmcmi

This variable controls debugging facilities in the mmbackup helper program mmcmi, which is used when the cluster minReleaseLevel is less than 3.5.0.11.

DEBUGtsbuhelper

This variable controls debugging facilities in the mmbackup helper program tsbuhelper, which is used when the cluster minReleaseLevel is greater than or equal to 3.5.0.11.

Variables that change mmbackup record locations

MMBACKUP_RECORD_ROOT

Specifies an alternative directory name for storing all temporary and permanent records for the backup. The directory name specified must be an existing directory and it cannot contain special characters (for example, a colon, semicolon, blank, tab, or comma).

The directory specified for MMBACKUP_RECORD_ROOT must be accessible from each node specified with the -N option.

Exit status

0

Successful completion. All of the eligible files were backed up.

1

Partially successful completion. Some files, but not all eligible files, were backed up. The shadow database or databases reflect the correct inventory of the TSM server. Invoke mmbackup again to complete the backup of eligible files.

2

A failure occurred that prevented backing up some or all files or recording any progress in the shadow database or databases. Correct any known problems and invoke mmbackup again to complete the backup of eligible files. If some files were backed up, using the -q or --rebuild option can help avoid backing up some files additional times.

Security

You must have root authority to run the mmbackup command.

The node on which the command is issued, and all other IBM Spectrum Protect Backup-Archive client nodes, must be able to execute remote shell commands on any other node in the cluster without the use of a password and without producing any extraneous messages. For more information, see Requirements for administering a GPFS file system.

See also

Location