Skip to main content

Environment variables supported by ONTAP

Contributors netapp-aherbin
PDFs

Environment variables are used to communicate information about a backup or restore operation between an NDMP-enabled backup application and a storage system. ONTAP supports environment variables, which have an associated default value. However, you can manually modify these default values.

If you manually modify the values set by the backup application, the application might behave unpredictably. This is because the backup or restore operations might not be doing what the backup application expected them to do. But in some cases, judicious modification might help in identifying or working around problems.

The following tables list the environment variables whose behavior is common to dump and SMTape and those variables that are supported only for dump and SMTape. These tables also contain descriptions of how the environment variables that are supported by ONTAP work if they are used:

Note

In most cases, variables that have the value, Y also accept T and N also accept F.

Environment variables supported for dump and SMTape

Environment variable Valid values Default Description

DEBUG

Y or N

N

Specifies that debugging information is printed.

FILESYSTEM

string

none

Specifies the path name of the root of the data that is being backed up.

NDMP_VERSION

return_only

none

You should not modify the NDMP_VERSION variable. Created by the backup operation, the NDMP_VERSION variable returns the NDMP version.

ONTAP sets the NDMP_VERSION variable during a backup for internal use and to pass to a backup application for informational purposes. The NDMP version of an NDMP session is not set with this variable.

PATHNAME_SEPARATOR

return_value

none

Specifies the path name separator character.

This character depends on the file system being backed up. For ONTAP, the character “/” is assigned to this variable. The NDMP server sets this variable before starting a tape backup operation.

TYPE

dump or smtape

dump

Specifies the type of backup supported to perform tape backup and restore operations.

VERBOSE

Y or N

N

Increases the log messages while performing a tape backup or restore operation.

Environment variables supported for dump

Environment variable Valid values Default Description

ACL_START

return_only

none

Created by the backup operation, the ACL_START variable is an offset value used by a direct access restore or restartable NDMP backup operation.

The offset value is the byte offset in the dump file where the ACL data (Pass V) begins and is returned at the end of a backup. For a direct access restore operation to correctly restore backed-up data, the ACL_START value must be passed to the restore operation when it begins. An NDMP restartable backup operation uses the ACL_START value to communicate to the backup application where the nonrestartable portion of the backup stream begins.

BASE_DATE

0, -1, or DUMP_DATE value

-1

Specifies the start date for incremental backups.

When set to -1, the BASE_DATE incremental specifier is disabled. When set to 0 on a level 0 backup, incremental backups are enabled. After the initial backup, the value of the DUMP_DATE variable from the previous incremental backup is assigned to the BASE_DATE variable.

These variables are an alternative to the LEVEL/UPDATE based incremental backups.

DIRECT

Y or N

N

Specifies that a restore should fast-forward directly to the location on the tape where the file data resides instead of scanning the entire tape.

For direct access recovery to work, the backup application must provide positioning information. If this variable is set to Y, the backup application specifies the file or directory names and the positioning information.

DMP_NAME

string

none

Specifies the name for a multiple subtree backup.

This variable is mandatory for multiple subtree backups.

DUMP_DATE

return_value

none

You do not change this variable directly. It is created by the backup if the BASE_DATE variable is set to a value other than -1.

The DUMP_DATE variable is derived by prepending the 32-bit level value to a 32-bit time value computed by the dump software. The level is incremented from the last level value passed into the BASE_DATE variable. The resulting value is used as the BASE_DATE value on a subsequent incremental backup.

ENHANCED_DAR_ENABLED

Y or N

N

Specifies whether enhanced DAR functionality is enabled. Enhanced DAR functionality supports directory DAR and DAR of files with NT Streams. It provides performance improvements.

Enhanced DAR during restore is possible only if the following conditions are met:

  • ONTAP supports enhanced DAR.

  • File history is enabled (HIST=Y) during the backup.

  • The ndmpd.offset_map.enable option is set to on.

  • ENHANCED_DAR_ENABLED variable is set to Y during restore.

EXCLUDE

pattern_string

none

Specifies files or directories that are excluded when backing up data.

The exclude list is a comma-separated list of file or directory names. If the name of a file or directory matches one of the names in the list, it is excluded from the backup.

The following rules apply while specifying names in the exclude list:

  • The exact name of the file or directory must be used.

  • The asterisk (*), a wildcard character, must be either the first or the last character of the string.

    Each string can have up to two asterisks.

  • A comma in a file or directory name must be preceded with a backslash.

  • The exclude list can contain up to 32 names.

Note

Files or directories specified to be excluded for backup are not excluded if you set NON_QUOTA_TREE to Y simultaneously.

EXTRACT

Y, N, or E

N

Specifies that subtrees of a backed-up data set are to be restored.

The backup application specifies the names of the subtrees to be extracted. If a file specified matches a directory whose contents were backed up, the directory is recursively extracted.

To rename a file, directory, or qtree during restore without using DAR, you must set the EXTRACT environment variable to E.

EXTRACT_ACL

Y or N

Y

Specifies that ACLs from the backed up file are restored on a restore operation.

The default is to restore ACLs when restoring data, except for DARs (DIRECT=Y).

FORCE

Y or N

N

Determines if the restore operation must check for volume space and inode availability on the destination volume.

Setting this variable to Y causes the restore operation to skip checks for volume space and inode availability on the destination path.

If enough volume space or inodes are not available on the destination volume, the restore operation recovers as much data allowed by the destination volume space and inode availability. The restore operation stops when volume space or inodes are not available.

HIST

Y or N

N

Specifies that file history information is sent to the backup application.

Most commercial backup applications set the HIST variable to Y. If you want to increase the speed of a backup operation, or you want to troubleshoot a problem with the file history collection, you can set this variable to N.

Note

You should not set the HIST variable to Y if the backup application does not support file history.

IGNORE_CTIME

Y or N

N

Specifies that a file is not incrementally backed up if only its ctime value has changed since the previous incremental backup.

Some applications, such as virus scanning software, change the ctime value of a file within the inode, even though the file or its attributes have not changed. As a result, an incremental backup might back up files that have not changed. The IGNORE_CTIME variable should be specified only if incremental backups are taking an unacceptable amount of time or space because the ctime value was modified.

Note

The NDMP dump command sets IGNORE_CTIME to false by default. Setting it to true can result in the following data loss:

  1. If IGNORE_CTIME is set to true with a volume level incremental ndmpcopy, it results in the deleting of files, which are moved across qtrees on source.

  2. If IGNORE_CTIME is set to true during a volume level incremental dump, it results in the deleting of files, which are moved across qtrees on source during incremental restore.

To avoid this problem, IGNORE_CTIME must be set to false during volume level NDMP dumps or ndmpcopy.

IGNORE_QTREES

Y or N

N

Specifies that the restore operation does not restore qtree information from backed-up qtrees.

LEVEL

0-31

0

Specifies the backup level.

Level 0 copies the entire data set. Incremental backup levels, specified by values above 0, copy all files (new or modified) since the last incremental backup. For example, a level 1 backs up new or modified files since the level 0 backup, a level 2 backs up new or modified files since the level 1 backup, and so on.

LIST

Y or N

N

Lists the backed-up file names and inode numbers without actually restoring the data.

LIST_QTREES

Y or N

N

Lists the backed-up qtrees without actually restoring the data.

MULTI_SUBTREE_ NAMES

string

none

Specifies that the backup is a multiple subtree backup.

Multiple subtrees are specified in the string, which is a newline-separated, null-terminated list of subtree names. Subtrees are specified by path names relative to their common root directory, which must be specified as the last element of the list.

If you use this variable, you must also use the DMP_NAME variable.

NDMP_UNICODE_ FH

Y or N

N

Specifies that a Unicode name is included in addition to the NFS name of the file in the file history information.

This option is not used by most backup applications and should not be set unless the backup application is designed to receive these additional file names. The HIST variable must also be set.

NO_ACLS

Y or N

N

Specifies that ACLs must not be copied when backing up data.

NON_QUOTA_TREE

Y or N

N

Specifies that files and directories in qtrees must be ignored when backing up data.

When set to Y, items in qtrees in the data set specified by the FILESYSTEM variable are not backed up. This variable has an effect only if the FILESYSTEM variable specifies an entire volume. The NON_QUOTA_TREE variable only works on a level 0 backup and does not work if the MULTI_SUBTREE_NAMES variable is specified.

Note

Files or directories specified to be excluded for backup are not excluded if you set NON_QUOTA_TREE to Y simultaneously.

NOWRITE

Y or N

N

Specifies that the restore operation must not write data to the disk.

This variable is used for debugging.

RECURSIVE

Y or N

Y

Specifies that directory entries during a DAR restore be expanded.

The DIRECT and ENHANCED_DAR_ENABLED environment variables must be enabled (set to Y) as well. If the RECURSIVE variable is disabled (set to N), only the permissions and ACLs for all the directories in the original source path are restored from tape, not the contents of the directories. If the RECURSIVE variable is set to N or the RECOVER_FULL_PATHS variable is set to Y, the recovery path must end with the original path.

Note

If the RECURSIVE variable is disabled and if there is more than one recovery path, all of the recovery paths must be contained within the longest of the recovery paths. Otherwise, an error message is displayed.

For example, the following are valid recovery paths because all of the recovery paths are within foo/dir1/deepdir/myfile:

  • /foo

  • /foo/dir

  • /foo/dir1/deepdir

  • /foo/dir1/deepdir/myfile

The following are invalid recovery paths:

  • /foo

  • /foo/dir

  • /foo/dir1/myfile

  • /foo/dir2

  • /foo/dir2/myfile

RECOVER_FULL_PATHS

Y or N

N

Specifies that the full recovery path will have their permissions and ACLs restored after the DAR.

DIRECT and ENHANCED_DAR_ENABLED must be enabled (set to Y) as well. If RECOVER_FULL_PATHS is set to Y, the recovery path must end with the original path. If directories already exist on the destination volume, their permissions and ACLs will not be restored from tape.

UPDATE

Y or N

Y

Updates the metadata information to enable LEVEL based incremental backup.

Environment variables supported for SMTape

Environment variable Valid values Default Description

BASE_DATE

DUMP_DATE

-1

Specifies the start date for incremental backups.

BASE_DATE is a string representation of the reference Snapshot identifiers. Using the BASE_DATE string, SMTape locates the reference Snapshot copy.

BASE_DATE is not required for baseline backups. For an incremental backup, the value of the DUMP_DATE variable from the previous baseline or incremental backup is assigned to the BASE_DATE variable.

The backup application assigns the DUMP_DATE value from a previous SMTape baseline or incremental backup.

DUMP_DATE

return_value

none

At the end of an SMTape backup, DUMP_DATE contains a string identifier that identifies the Snapshot copy used for that backup. This Snapshot copy could be used as the reference Snapshot copy for a subsequent incremental backup.

The resulting value of DUMP_DATE is used as the BASE_DATE value for subsequent incremental backups.

SMTAPE_BACKUP_SET_ID

string

none

Identifies the sequence of incremental backups associated with the baseline backup.

Backup set ID is a 128-bit unique ID that is generated during a baseline backup. The backup application assigns this ID as the input to the SMTAPE_BACKUP_SET_ID variable during an incremental backup.

SMTAPE_SNAPSHOT_NAME

Any valid Snapshot copy that is available in the volume

Invalid

When the SMTAPE_SNAPSHOT_NAME variable is set to a Snapshot copy, that Snapshot copy and its older Snapshot copies are backed up to tape.

For incremental backup, this variable specifies incremental Snapshot copy. The BASE_DATE variable provides the baseline Snapshot copy.

SMTAPE_DELETE_SNAPSHOT

Y or N

N

For a Snapshot copy created automatically by SMTape, when the SMTAPE_DELETE_SNAPSHOT variable is set to Y, then after the backup operation is complete, SMTape deletes this Snapshot copy. However, a Snapshot copy created by the backup application will not be deleted.

SMTAPE_BREAK_MIRROR

Y or N

N

When the SMTAPE_BREAK_MIRROR variable is set to Y, the volume of type DP is changed to a RW volume after a successful restore.