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)
COPYRIGHT
2022 ArcaPix Limited
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.