test veritas logo


vxfs_meta_backup(3)

NAME

vxfs_meta_backup - retrieve VxFS-specific metadata for backup archive

SYNOPSIS

cc -I /opt/VRTS/include -L /opt/VRTS/lib

-l vxfsutil -ldl

#include <sys/types.h>

#include <vxfsutil.h>

int vxfs_meta_backup(int fd, int cmd, void **buffer, uint64_t *buflen, void **token);

AVAILABILITY

VRTSvxfs

DESCRIPTION

vxfs_meta_backup() retrieves VxFS-specific metadata for files, directories, and VxFS file systems. The metadata is encapsulated in an opaque buffer that can be included in a backup archive and then later be submitted to vxfs_meta_restore().

To use this function, specify -l vxfsutil while linking.

vxfs_meta_backup() does not collect standard POSIX metadata. The caller should continue to collect standard metadata through conventional interfaces.

NOTES

This API can be called only with root privileges.

This API may be used by multiple threads; however, each thread must set up its own session using VXFS_LIB_INIT and VXFS_LIB_FINI, and each thread must use its own token.

The caller may choose to collect all file system metadata first for all file systems and then collect file and directory metadata, or the caller can collect all metadata for a file system and its contents, then move on to the next file system.

The metadata capsule is byte-order independent. The caller does not need to make any adjustments if backing up on one byte-order architecture and restoring on another.

Restore must be done through vxfs_meta_restore().

If vxfs_meta_backup() fails, backup of file data and directory contents may still proceed. The only consequence of API failure is that some VxFS-specific metadata will not be archived; the user data will still be accessible.

As implemented for VxFS 5.0 and later releases, this API backs up only SmartTier metadata and has the following limitations, which may be removed in future releases:

o VXFS_GETEXTFS is not VxFS Storage Checkpoint-aware; if invoked on a VxFS Storage Checkpoint, it will return the file system metadata in effect at the time it is invoked, not the metadata in effect at the time the Storage Checkpoint was taken. If VXFS_GETEXTFS is invoked on a volume snapshot, it will return the file system metadata as of the time of the snapshot.
o The backup application must call vxfs_meta_backup() with VXFS_GETEXTFILE whenever a file is relocated, to update the archived SmartTier metadata. File relocation will update ctime. The backup application may archive the updated metadata separately from the data blocks to avoid re-archiving the data blocks on each relocate.
o If you want to use block-level incremental backups through VxFS Storage Checkpoints or if you want to use mtime-based backups rather than ctime-based backups, the following alternate backup and restore procedure produces correct results:
 
1. On the backup side, back up the files in the conventional manner.
2. On the restore side, restore the files in the conventional manner.
3. Run fsppadm -assign to install the desired placement policy.
4. Run fsppadm -enforce to relocate the files to the desired tiers as needed.

ARGUMENTS

buffer A pointer to the returned metadata capsule. The buffer is allocated by vxfs_meta_backup().
buflen Length of the returned buffer.
cmd Command that specifies the operation to perform. Possible values for cmd are:
VXFS_GETEXTFILE
  Allocates and fills in an opaque capsule of VxFS metadata for the file or directory referenced by fd.
On successful return, the pointer to the buffer and the buffer length are filled in. If buflen is zero on successful return, there is no VxFS-specific metadata to back up.
fd must be the file descriptor for the file or directory being backed up. token must be the token returned previously by VXFS_LIB_INIT.
The metadata capsule for each file and directory must be archived each time the file or directory is backed up. An updated metadata capsule must be archived whenever ctime changes for a file or directory, even if the data blocks are unchanged. VXFS_GETEXTFILE must be invoked for the root directory of the file system, along with the other directories.
VXFS_GETEXTFILE_RELE
  Frees the buffer allocated by VXFS_GETEXTFILE.
buffer and buflen must be the values returned previously. token must be the token returned previously by VXFS_LIB_INIT. fd is ignored.
VXFS_GETEXTFS
  Allocates and fills in an opaque capsule of VxFS metadata for the file system referenced by fd.
On successful return, the pointer to the buffer and the buffer length are filled in. If buflen is zero on successful return, this indicates that there is no VxFS-specific metadata associated with the file system, although there might still be VxFS-specific metadata associated with individual files in the file system.
fd must be the file descriptor for the mount point of the file system. token must be the token returned previously by VXFS_LIB_INIT.
To keep file system metadata consistent with file and directory metadata, the metadata capsule for the file system must be archived each time the file system is backed up, including incremental backups. A synthetic full backup should use the metadata capsule from the most recent incremental backup.
VXFS_GETEXTFS_RELE
  Frees the buffer allocated by VXFS_GETEXTFS.
buffer and buflen must be the values returned previously. token must be the token returned previously by VXFS_LIB_INIT. fd is ignored.
VXFS_LIB_FINI
  Releases resources allocated by VXFS_LIB_INIT. VXFS_LIB_FINI must be the last command submitted to vxfs_meta_backup(). After VXFS_LIB_FINI returns, the token is no longer valid. token must be the token returned previously by VXFS_LIB_INIT. fd, buffer, and buflen are ignored.
VXFS_LIB_INIT
  Initializes the API for backup operations and allocates required resources. VXFS_LIB_INIT must be the first command submitted to vxfs_meta_backup(). token is initialized in this call. fd, buffer, and buflen are ignored.
VXFS_NO_DST
  This command may be specified along with the "or" qualifier with any of the other commands to omit SmartTier-related metadata from the metadata capsule. Other non-SmartTier metadata will still be filled in.
fd File descriptor representing the file or directory being backed up or the mount point of the file system being backed up, depending of the value of cmd.
token A pointer to an opaque handle used by vxfs_meta_backup(). The handle is initialized with the VXFS_LIB_INIT command and released with the VXFS_LIB_FINI command.

RETURN VALUES

vxfs_meta_backup() returns zero on success, non-zero on failure.

ERRORS

EBADF Invalid file descriptor.
EINVAL Invalid command argument, or improperly initialized token.
ENOTSUP The requested operation is not supported by the file system.
ENOMEM Memory could not be allocated.
ENOSYS There is no license installed to allow this operation.
EPERM The effective user ID of the calling process does not have appropriate privileges to perform this operation.

SEE ALSO

vxfs_meta_restore(3)


VxFS 7.4.1 vxfs_meta_backup(3)