apchmod(1)

Change permissions on files and directories in PixStor

SYNOPSIS

apchmod [options…] mask[,mask]… paths…

DESCRIPTION

apchmod is a tool for changing the permissions on a file by modifying ACL entries (ACEs).

Permission bits are specified using the same syntax as nfs4_acl(5), see the MASKS section below.

This tool performs partial updates on existing ACEs, for example updating a user’s existing permissions to include write permission

apchmod pixadmin:+W /mmfs1/test

By comparison, apfacl(1) only supports manipulating (add, remove, replace) whole ACEs.

WARNING - this tool doesn’t take into account the type of an ACE. This means, if a permission bit is added to a DENY ACE, it will take away that permission from affected users - i.e. D::pixadmin:r updated with +w gives D::pixadmin:rw.

NOTE - this tool only supports GPFS filesystems with ACL semantics (mmlsfs -k) set to nfs4

OPTION SUMMARY

      mask               permissions changes to apply
      paths              paths to apply permission changes to

    --recursive          apply changes recursively
-v, --verbose            print the ACL after applying changes
    --no-check           don't check the current ACL before applying changes
    --include-symlinks   include symlinks when applying changes recursively
    --test               print the updated ACL without applying the change
-V, --version            show the current version number
-h, --help               show this help message and exit

OPTIONS

  • –recursive

    Apply the permission changes to a directory tree recursively.

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

    No short option is provided to avoid confusion with masks (-r and -R)

  • -v, –verbose

    Display the ACL after applying changes.

    To view the existing ACL, use apfacl(1)

  • –no-check

    By default, apchmod will compare the current file ACL to what the ACL will be after applying updates. If the current ACL is unchanged by the updates, the new ACL will not be applied.

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

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

    When all the target files are expected to be updated, the –no-check flag will make the process faster.

  • –include-symlinks

    Include symlinks when applying changes recursively.

    It is not possible to get or set the ACL on a symlink object itself. ACLs will be read from and written to the target of a symlink.

    By default, apchmod will skip any symlinks it encounters when applying a change recursively.

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

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

  • –test

    Apply the ACL changes in test mode.

    The changes will be performed on the current ACL and the result will be printed to stdout but the result will not be applied to the file(s)

  • -V, –version

    Show the current version number

  • -h, –help

    Prints the help message.

MASKS

The mask format is similar to chmod(1)

[principal:]((=+-)(permissions...))...

That is, an optional principal (user, group, special), followed by one or more permission changes. For example

  pixadmin:=R        set read (alias) permission for the pixadmin user
g:viewonly:-w        remove write permission from the 'viewonly' group
    OWNER@:+x        grant execute permission to the file owner
           +r        grant read permission to everyone
           =RW-cC    set read/write (alias) permissions, without read-acl and write-acl, for all users

If multiple permission changes are specified, e.g. +R-c, the changes will be applied to the file in the order specified (add read then remove read-acl).

Multiple masks can be specified as a comma-separated list, e.g. +w,viewonly:-w. Masks are applied in the order specified (grant write to everyone, then remove write from viewonly).

PRINCIPAL

Principal is a user name or uid, or group name or gid of the form user or g:group.

pixadmin:+x
g:admin:+W

Principal can also be one of the special users OWNER@, GROUP@, and EVERYONE@, which correspond to POSIX user, group, and other, respectively.

OWNER@:+WX
GROUP@:=RW

If there are no existing entries for the specified principle and add (+) or set (=) are specified, a new entry will be added to the ACL with the specified permissions. For remove (-), no new entry will be added. For example

pixadmin:+r -> A::pixadmin:r
pixadmin:=r -> A::pixadmin:r
pixadmin:-r -> (nothing added)

If remove results in an entry having no permissions, it will not be removed.

If principal is omitted, the change will be applied to all existing ACEs, e.g. +r would add read permission to all existing entries. It will not result in any new entries being added.

OPERATIONS

Operations can be any of

=    set the permissions, replacing the current
+    add the permissions to the current
-    remove the permissions from the current

PERMISSIONS

Permissions can be one or more of

a    append - append data to a file or create sub-directories (mkdir)
c    read ACL - read the NFS4 ACL on a file or directory
C    write ACL - write the NFS4 ACL on a file or directory
d    delete - delete a file or directory itself
D    delete child - delete a child file or directory from within a directory (no effect when applied to files)
n    read named - read named attributes of a file or directory
N    write named - write named attributes of a file or directory
o    write owner - change the owner of a file or directory (chown)
r    read - read file data or list directories
t    read attrs - read attributes of a file or directory
T    write attrs - write attributes of a file or directory
w    write - write file date or create files within a directory
x    execute - execute a file or move into a directory (cd)
y    synchronize - allow clients to use synchronous I/O within the server

NOTE - GPFS supports setting read named, write Named, and synchronize, but they have no effect within GPFS

Permissions can also use aliases - see the ALIASES section below.

ALIASES

Aliases are provided for the more simple POSIX read/write/execute permissions

R    rntcy
W    watTNcCy, plus D for directories
X    tcy, plus x for directories

For example, OWNER@:+RW will grant file owner read/write permissions, roughly equivalent to POSIX chmod u+rw

The fact that X doesn’t include execute permission means that one can apply +RX recursively to make files and directories accessible without making files executable. To explicitly make files executable, one would include the lowercase executable bit - +RXx

Note - permissions delete and write owner are not included in any of the aliases. To set all the permissions, one can use +RWXdo for directories and +RWXdDox for files.

WARNING - care should be taken when removing permissions with an alias. For example if a file has A::pixadmin:rntcyx (equivalent to aliases RX), performing apchmod pixadmin:-X would result in A::pixadmin:rn, which is not equivalent to alias R

EXAMPLES

GRANT READ PERMISSION TO ALL ENTRIES

NFSv4 Literal

apchmod +rntcy /mmfs1/test

POSIX alias

apchmod +R /mmfs1/test

SET FILE OWNER PERMISSION

Using the POSIX alias, the following is roughly equivalent to chmod u=r

apchmod OWNER@:=R /mmfs1

REMOVE EXECUTE PERMISSION FROM ‘EVERYONE’

Remove the execute permission from the EVERYONE@ special entry

apchmod EVERYONE@:-x /mmfs1/test

To remove the execute permission from all users

apchmod -x /mmfs1/test

GRANT A USER READONLY PERMISSION

If an entry already exists for the user it will be updated in-place. If an entry doesn’t exist for the user, a new entry will be appended.

apchmod pixadmin:=R /mmfs1/test

REMOVE POSIX READ PERMISSION FROM ALL ENTRIES

apchmod -R /mmfs1/test

Note that unlike chmod(1) or apfacl(1), -R is not a short option for the recursive flag in apchmod(1), as this would cause confusion with ‘remove read’ mask shown above.

To apply the change recursively

apchmod -R /mmfs1/dir --recursive

THREAD SAFETY

apchmod is not thread-safe.

For each file, apchmod 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, apchmod will exit with status 0

On failure, apchmod will exit with status 1. An error message will be printed to stderr.

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

SEE ALSO

apfacl(1), ap_pushacl, chmod(1), mmgetacl(1), mmputacl(1), nfs4_acl(5)