test veritas logo


vxfs_meta_restore(3)

NAME

vxfs_meta_restore - restore 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_restore(int fd, int cmd, void **buffer, uint64_t *buflen, void **token);

AVAILABILITY

VRTSvxfs

DESCRIPTION

vxfs_meta_restore() restores VxFS-specific metadata for files, directories, and VxFS file systems. The metadata is encapsulated in an opaque buffer that was retrieved previously by the vxfs_meta_backup() function.

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

vxfs_meta_restore() does not restore standard POSIX metadata. The caller should continue to restore 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.

For a full restoration of multiple file systems, the caller may restore all file systems metadata first for all file systems, then restore directories and files, or the caller may restore one file systems 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.

Retrieval of the metadata capsule must be done through vxfs_meta_backup().

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

If the destination SmartTier tier is full, a restore will fail with ENOSPC. To recover from this, the backup application may retry the restore with the NO_DST flag set, which will cause the file to be placed in the default tier for new files.

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_SETEXTFS requires the volume set (vset) composition of the file system to be identical on the restore side as it was on the backup side. If there are differences, such as if tier "gold" is volumes 1, 2, and 3 on the backup side, but volumes 3 and 4 on the restore side, the behavior of VXFS_SETEXTFS is unpredictable.
o VXFS_SETEXTFILE_PRE requires the placement policy of the file system to be identical on the restore side as it was on the backup side. If there are differences, such as if a new rule was added to the placement policy, the behavior of VXFS_SETEXTFILE_PRE is unpredictable.
o If the override file /etc/vx/vxfs_restore_ctl exists, this has the same effect as using the NO_DST flag. The override file may be redefined or eliminated in future releases.
o If it is not possible to guarantee an identical vset composition and identical placement policy on the backup side and restore side, 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 archived metadata capsule. The buffer is allocated by the calling process.
buflen Length of the buffer.
cmd Command that specifies the operation to perform. Possible values for cmd are:
VXFS_LIB_FINI
  Releases resources allocated by VXFS_LIB_INIT. VXFS_LIB_FINI must be the last command submitted to vxfs_meta_restore(). 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 restore operations and allocates required resources. VXFS_LIB_INIT must be the first command submitted to vxfs_meta_restore().
token is initialized in this call. fd, buffer, and buflen are ignored.
VXFS_SETEXTFS
  Prepares a VxFS file system for a full restore, using the archived metadata capsule.
buffer must point to the metadata capsule retrieved earlier through vxfs_meta_backup() with the VXFS_GETEXTFS command. buflen must be the buffer length retrieved previously. buflen may be zero if a zero buflen was returned previously by VXFS_GETEXTFS.
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.
VXFS_SETEXTFS should be invoked only when doing a full restore of a file system. VXFS_SETEXTFS should not be invoked when restoring individual files or directories into an existing filest. If invoked on the mount point of an active file system, VXFS_SETEXTFS will overwrite some, but not all, of the SmartTier metadata associated with that file system.
VXFS_SETEXTFS is meaningful only when the mount point hierarchy in the restore environment is identical to the mount point hierarchy in the backup environment. If VXFS_SETEXTFS is invoked for an ordinary directory that was a mount point on the backup system, vxfs_meta_restore() will return an error.
VXFS_SETEXTFILE_PRE
  Prepares a VxFS file or directory for restore using the archived metadata capsule.
buffer must point to the metadata capsule retrieved earlier through vxfs_meta_backup() with the VXFS_GETEXTFILE command. buflen must be the buffer length retrieved previously. buflen may be zero, if a zero buflen was returned previously by VXFS_GETEXTFILE.
fd must be the file descriptor for the file or directory being restored. token must be the token returned previously by VXFS_LIB_INIT.
VXFS_SETEXTFILE_PRE must be invoked before filling in file data, or before populating a directory. When restoring an entire file system, VXFS_SETEXTFILE_PRE must be invoked for the root directory of the file system along with the other directories.
For regular files, VXFS_SETEXTFILE_PRE will overwrite any pre-existing VxFS-specific metadata.
For directories, VXFS_SETEXTFILE_PRE will overwrite some, but not all, of the pre-existing VxFS-specific metadata. To restore a directory’s metadata state fully, the caller must remove the directory, create a new empty directory of the same name, invoke VXFS_SETEXTFILE_PRE, then repopulate the directory.
VXFS_SETEXTFILE_POST
  Completes a VxFS file or directory restore using the archived metadata capsule. buffer must point to the metadata capsule retrieved previously through vxfs_meta_backup() with the VXFS_GETEXTFILE command. buflen must be the buffer length retrieved previously. buflen may be zero if a zero buflen was returned previously by VXFS_GETEXTFILE. fd must be the file descriptor for the file or directory being restored. token must be the token returned previously by VXFS_LIB_INIT. VXFS_SETEXTFILE_POST must be invoked after filling in file data or after populating a directory. When restoring an entire file system, VXFS_SETEXTFILE_POST must be invoked for the root directory of the file system along with the other directories.
VXFS_NO_DST
  This command may be specified along with the "or" qualifier with any of the other commands to omit SmartTier-related operations from the restore. Other non-SmartTier metadata will still be applied.
fd File descriptor representing the file or directory being restored or the mount point of the file system being restored, depending of the value of cmd.
token A pointer to an opaque handle used by vxfs_meta_restore(). The handle is initialized with the VXFS_LIB_INIT command and released with the VXFS_LIB_FINI command.

RETURN VALUES

vxfs_meta_restore() 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.
EROFS The specified file system is mounted read-only.

SEE ALSO

vxfs_meta_backup(3)


VxFS 8.0 vxfs_meta_restore(3)