ap-restore-acl(1)

Restore file permissions from a snapshot

SYNOPSIS

ap-restore-acl paths… -s snapshot [-f fileset] [options…]

DESCRIPTION

ap-restore-acl is a tool for restoring ACLs from a reference snapshot.

If a version of a file doesn’t exist in the reference snapshot, a warning will be logged and the file’s ACL will be left unchanged.

OPTION SUMMARY

      paths              paths to restore permissions on

-s, --snapshot           name of the snapshot to restore from
-f, --fileset            name of a fileset to restore from fileset snapshot
-R, --recursive          apply changes recursively
    --no-check           don't check the current ACL before restoring
    --include-symlinks   include symlinks when restoring ACLs recursively
-v, --verbose            print the ACL after restoration
    --test               print the ACL that would be restored
-V, --version            show the current version number
-h, --help               show this help message and exit

OPTIONS

  • -s, –snapshot

    Name of the snapshot to restore permissions from.

    By default, this is treated as a global snapshots. To restore from a fileset snaphot, use the –fileset flag

  • -f, –fileset

    Name of a fileset, to restore from a fileset snapshot instead of global.

    Typically, creating a fileset snapshot is lighter-weight than creating a global snapshot. So may be preferrable if all the files that need to be restored are within a given fileset.

    Note, if multiple paths are passed to ap-restore-acl, they must all reside within this fileset.

  • -R, –recursive

    Restore the permissions to a directory tree recursively.

    Changes are applied top-down. Symlinks will not be followed.

  • –no-check

    By default, ap-restore-acl will not restore an ACL if it matches the ACL already on the target file.

    This means that change time (ctime) will not be updated for such files.

    The –no-check flag causes this comparison to be skipped - the ACL will be restored regardless of its current value.

    When all the target files are expected to have their ACLs changed, the –no-check flag will make the process faster.

  • –include-symlinks

    Include symlinks when restoring ACLs recursively.

    When an ACL is restored on a symlink, it is actually the target of the symlink which gets updated.

    By default, ap-restore-acl will skip any symlinks it encounters when restoring ACLs recursively.

    This flag will force ap-restore-acl to restore ACLs to symlinks (targets) when –recursive is used. Be aware that broken symlinks, or symlinks pointing to paths outside GPFS will cause errors.

    Also be aware that snapshots of symlinks point to the same path on the live file system that the live copy did. For example if the live symlink pointed to /mmfs1/test, then the snapshot of that symlink would also point to /mmfs1/test. In this case ap-restore-acl will attempt to convert that live target path to the equivalent in the snapshot.

    ap-restore-acl will handle symlinks passed to it on the command line (non-recursively), regardless of whether this flag is used.

  • -v, –verbose

    Display the ACL after applying changes.

    To view the existing ACL, use apfacl(1)

  • –test

    Restore the ACLs in test mode.

    The ACL will be looked up from the reference snapshot, and will be printed to stdout but the ACL will not be applied to the target file

  • -V, –version

    Show the current version number

  • -h, –help

    Prints the help message.

EXAMPLES

RESTORE PERMISSIONS ON A FILE

ap-restore-acl /mmfs1/test -s @GMT-2021.12.05-08.00.00

RESTORE PERMISSIONS RECURSIVELY

ap-restore-acl -R /mmfs1/data -s @GMT-2021.12.05-08.00.00

RESTORE PERMISSIONS FROM A FILESET SNAPSHOT

ap-restore-acl /mmfs1/data/vfx -f vfx -s backup.vfx.1639477147

THREAD SAFETY

ap-restore-acl is not thread-safe.

For each file, ap-restore-acl will load the current ACL, preform the requested changes, then write the whole ACL back to the file. This means that, if two processes try to change the ACL on a file at the same time, the last write will replace any other changes.

EXIT STATUS

On success, ap-restore-acl will exit with status 0

On failure, ap-restore-acl will exit with status 1. An error message will be printed to stderr.

If an error occurs in the middle of a recursive change, ap-restore-acl will exit immediately with status 1. ACL changes will not be applied to any remaining files.

SEE ALSO

apfacl(1), ap_pushacl, apchmod(1), mmgetacl(1), mmputacl(1)