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 only be used to back up file systems owned by the local cluster.

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

You can run multiple instances of mmbackup, as long as they are on different file systems.

If you are planning to use Tivoli Storage Manager to back up IBM Spectrum Scale file systems, see the topic Backup considerations for using Tivoli Storage Manager in the IBM Spectrum Scale: Concepts, Planning, and Installation Guide and the topic Configuration reference for using Tivoli Storage Manager with IBM Spectrum Scale in the IBM Spectrum Scale: Administration and Programming Reference.

Parameters

Device

The device name for the file system to be backed up. File system names need not 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 will lead 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 have changed since the last backup was performed. The default is an incremental backup.

A full backup will expire all GPFS 3.2 format TSM inventory if all previous backups have been incremental and the GPFS 3.2 backup format had been 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 the list of nodes that will run parallel instances of the backup process. The TSM Backup-Archive client must be installed on all nodes specified with this parameter. This command supports all defined node classes. The default is to run only on the node where the mmbackup command is running or the current value of the defaultHelperNodes parameter of the mmchconfig command.

For general information on how to specify node names, see Specifying nodes as input to GPFS commands in the IBM Spectrum Scale: Administration and Programming Reference.

-g GlobalWorkDirectory

Specifies the directory to be used for temporary files that need to be shared between the mmbackup worker nodes. Defaults to the value specified with the -s option or /tmp.

-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 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 will be ignored.

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

-q

Performs a query operation prior to 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 will run during parallel inode scan and policy evaluation. The default value is 2.

-n DirThreadLevel

Specifies the number of threads that will be 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 in conjunction 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 in conjunction 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 in conjunction 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 will be automatically computed. Valid values are 100 - 8192.

--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 in conjunction with the -B option. Valid values are 100 - 8192.

--max-expire-count MaxExpireCount

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

--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 in the IBM Spectrum Scale: Administration and Programming Reference. 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) in the IBM Spectrum Scale: Advanced Administration Guide.

--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 TSM 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 will be 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 the same inode space; for example, dependent filesets.

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

Specifies the name of the TSM server or servers to be used for this backup. The TSM servers specified will each be 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 pathname of the log file to pass to TSM 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 TSM 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 the topic MMBACKUP_PROGRESS_CALLOUT environment variable in the IBM Spectrum Scale: Advanced Administration Guide.

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 bitmask 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 alternate 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, as well as all other TSM 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 file system in IBM Spectrum Scale: Administration and Programming Reference.

See also

Location