FS_SETACL(1)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 FS_SETACL 💖

okay bestie, gather round, because we're talking about fs setacl from the AFS Command Reference and it's literally the glow-up tool for your directory permissions 💅

✨ NAME ✨

fs_setacl — sets the ACL for a directory. that's it, that's the whole job, and it ATE 🎀

🦋 SYNOPSIS 🦋

fs setacl -dir <directory>+ -acl <access list entries>+
    [-clear] [-negative] [-id] [-if] [-help]

fs sa -d <directory>+ -a <access list entries>+
    [-c] [-n] [-id] [-if] [-h]

fs seta -d <directory>+ -a <access list entries>+
    [-c] [-n] [-id] [-if] [-h]

three whole aliases, no cap. short queen energy 👑

🌸 DESCRIPTION 🌸

so like, fs setacl takes the access control list (ACL) entries you feed it with the -acl argument and adds them onto the ACL of every single directory you name with -dir. every one. all of them. it's giving "one command, many dirs" fr fr ✨

if your -dir argument points at a pathname in DFS filespace (the kind you reach through the AFS/DFS Migration Toolkit Protocol Translator), it can be a file and not just a directory, lowkey iconic. but heads up: the ACL already has to include an entry for "mask_obj". no "mask_obj", no vibes.

only user and group entries are acceptable values for -acl. do NOT put machine entries (like IP addresses) directly on an ACL. instead, make the machine entry a group member and put the group on the ACL. that's the move 🫶

want to completely erase the existing ACL before you add the new entries? pass the -clear flag and start fresh, main character energy. want to add your entries to the "Negative rights" section of the ACL instead (so you're denying rights to specific users or groups)? that's the -negative flag.

to display an ACL, use the fs listacl command. to copy an ACL from one directory to another, use the fs copyacl command. different tools, different jobs, all slay 💜

⚠️ CAUTIONS ⚠️

okay this is the part where I need you to actually listen, bestie, because this is where people get got 😭

  • if the ACL already grants certain permissions to a user or group, the permissions you specify with fs setacl replace the existing permissions. they do not get added on top. it's a replace, not a merge. periodt.
  • setting negative permissions is generally unnecessary and not recommended. simply omitting a user or group from the "Normal rights" section of the ACL is normally adequate to prevent access. and specifically? it is futile to deny permissions that are granted to members of the system:anyuser group on the same ACL — the user just has to issue the unlog command and boom, they get the denied permissions anyway 💀
  • when you include the -clear option, be SURE to reinstate an entry for each directory's owner that includes at least the "l" (lookup) permission. without that permission it is impossible to resolve the "dot" (".") and "dot dot" ("..") shorthand from within the directory. (the directory's owner does implicitly have the "a" (administer) permission even on a cleared ACL, but they have to know to use it to add other permissions. sneaky little detail.)
fr fr do not clear an ACL and walk away without restoring the owner's l. that's how you lock yourself out of your own house 🙈

💅 OPTIONS 💅

  • -dir <directory>+ — names each AFS directory, or DFS directory or file, for which you're setting the ACL. partial pathnames get interpreted relative to the current working directory.

specify the read/write path to each directory (or DFS file) so you avoid the failure that comes from trying to change a read-only volume. by convention the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, /afs/.example.com). for the full discussion of read/write vs read-only paths through the filespace, go read the fs mkmount reference page 🧚

  • -acl <access list entries>+ — defines a list of one or more ACL entries, each one a pair that names:
    • a user name or group name as listed in the Protection Database, and
    • one or more ACL permissions — indicated either by combining the individual letters, or by one of the four acceptable shorthand words, optionally followed by a single plus (+) or minus (-) character to request a relative ACL change

in that order, separated by a space (so every instance of this argument has two parts). the accepted AFS abbreviations and shorthand words, and what each one means, are:

  • a (administer) — change the entries on the ACL.
  • d (delete) — remove files and subdirectories from the directory, or move them to other directories.
  • i (insert) — add files or subdirectories to the directory by copying, moving, or creating.
  • k (lock) — set read locks or write locks on the files in the directory.
  • l (lookup) — list the files and subdirectories in the directory, stat the directory itself, and issue the fs listacl command to examine the directory's ACL.
  • r (read) — read the contents of files in the directory; issue the "ls -l" command to stat the elements in the directory.
  • w (write) — modify the contents of files in the directory, and issue the UNIX chmod command to change their mode bits.
  • A, B, C, D, E, F, G, H — have no default meaning to the AFS server processes, but they're made available for applications to use in controlling access to the directory's contents in additional ways. these letters must be uppercase.
  • all — equals all seven permissions ("rlidwka").
  • none — no permissions. removes the user/group from the ACL, but does not guarantee they have no permissions if they belong to groups that remain on the ACL. 🙈
  • read — equals the "r" (read) and "l" (lookup) permissions.
  • write — equals all permissions except "a" (administer), that is, "rlidwk".

it is acceptable to mix entries that combine the individual letters with entries that use the shorthand words — but do NOT use both types of notation within an individual pairing of user or group and permissions. pick a lane inside each pair, bestie.

granting the "l" (lookup) and "i" (insert) permissions without granting the "w" (write) and/or "r" (read) permissions is a special case, and grants rights appropriate for "dropbox" directories. see the "DROPBOXES" section for the details 👀

if you're setting ACLs on a pathname in DFS filespace, go see the DFS documentation for the proper format and acceptable values for DFS ACL entries.

  • -clear — removes all existing entries on each ACL before adding the entries specified with -acl. clean slate, new era ✨
  • -negative — places the specified ACL entries in the "Negative rights" section of each ACL, explicitly denying the rights to the user or group — even if entries on the accompanying "Normal rights" section of the ACL grant them permissions.
this argument is not supported for DFS files or directories, because DFS does not implement negative ACL permissions. don't try it, she won't do it 💀
  • -id — places the ACL entries on the Initial Container ACL of each DFS directory, which are the only file system objects for which this flag is supported.
  • -if — places the ACL entries on the Initial Object ACL of each DFS directory, which are the only file system objects for which this flag is supported.
  • -help — prints the online help for this command. all other valid options are ignored. the classic "I just need answers" flag 🫶

🍓 DROPBOXES 🍓

okay so if an accessing user has the "l" (lookup) and "i" (insert) permissions on a directory, but not the "w" (write) and/or "r" (read) permissions, that user is implicitly granted the ability to write and/or read any file they create in that directory — until they close the file. why? so that "dropbox"-style directories can exist, where users can deposit files but cannot modify them later, and cannot modify or read any files deposited by other users. cute concept, right?

but ngl, the dropbox functionality is not perfect, so let's be honest about it:

  • the fileserver does not have knowledge of when a file is opened or closed on the client, and so the fileserver always allows an accessing user to read or write to a file in a "dropbox" directory if they own the file. while the client prevents the user from reading or modifying their deposited file later, this is not enforced on the fileserver, and so it should not be relied on for security 🚨
  • additionally, if "dropbox" permissions are granted to "system:anyuser", unauthenticated users may deposit files in the directory. if an unauthenticated user deposits a file in the directory, the new file will be owned by the unauthenticated user ID, and is thus potentially modifiable by anyone. yeah. yikes.
  • in an effort to try and reduce accidentally publicizing private data, the fileserver may refuse read requests for "dropbox" files from unauthenticated users. as a result, depositing files as an unauthenticated user may arbitrarily fail if "system:anyuser" has been granted dropbox permissions. while this should be rare, it is not completely preventable, and so for this reason relying on unauthenticated users to be able to deposit files in a dropbox is NOT RECOMMENDED.
tl;dr: dropboxes are a vibe, not a security boundary. do not build your whole threat model on them 🙈

🌈 EXAMPLES 🌈

example the first — this one adds two entries to the "Normal rights" section of the current working directory's ACL: the first entry grants "r" (read) and "l" (lookup) permissions to the group pat:friends, while the other one (using the "write" shorthand) gives all permissions except "a" (administer) to the user "smith".

% fs setacl -dir . -acl pat:friends rl smith write

% fs listacl -path .
Access list for . is
Normal rights:
   pat:friends rl
   smith rlidwk

look at those permissions go 🎀

example the second — this one includes the -clear flag, which removes the existing permissions (as displayed with the fs listacl command) from the current working directory's reports subdirectory and replaces them with a new set.

% fs listacl -dir reports
Access list for reports is
Normal rights:
   system:authuser rl
   pat:friends rlid
   smith rlidwk
   pat rlidwka
Negative rights:
   terry rl

% fs setacl -clear -dir reports -acl pat all smith write system:anyuser rl

% fs listacl -dir reports
Access list for reports is
Normal rights:
   system:anyuser rl
   smith rlidwk
   pat rlidwka

out with the old, in with the new 💅 note the Negative rights section vanished too — because -clear clears everything.

example the third — this one uses the -dir and -acl switches because it sets the ACL for more than one directory (both the current working directory and its public subdirectory).

% fs setacl -dir . public -acl pat:friends rli

% fs listacl -path . public
Access list for . is
Normal rights:
   pat rlidwka
   pat:friends rli
Access list for public is
Normal rights:
   pat rlidwka
   pat:friends rli

two directories, one command, absolutely iconic ✨

example the fourth — this one demonstrates the use of the + and - options to modify ACLs relative to the existing set.

% fs setacl dir . -acl pat:friends r-
% fs listacl -path .
Access list for . is
Normal rights:
   pat rlidwka
   pat:friends li
% fs setacl dir . acl pat:friends w+
% fs listacl -path .
Access list for . is
Normal rights:
   pat rlidwka
   pat:friends wli

see how the r- knocked the r right off and left li, and then w+ slid a w in front? relative edits are chef's kiss 👑

bestie this page has a whole second part coming, so hold that thought 🫶

✨ PRIVILEGE REQUIRED ✨

ok so before you go touching ACLs, bestie, we gotta do a vibe check on whether you're even allowed in the building 💅. To run fs setacl you gotta be one of these:

  • you have the a (administer) permission on that directory's ACL, like you literally hold the keys 🔑
  • you're a member of the system:administrators group 👑
  • OR, as a lil special case treat 🎀, you're the UID owner of the top-level directory of the volume that contains this directory

and that last one?? it's giving "emergency backdoor, but make it wholesome" 🌸. It exists so the UID owner of a volume can fix accidental ACL mess-ups without having to go beg a member of system:administrators to come help 😭. No waiting on a group chat reply, no ticket, just repair it yourself.

⚠️ eras tour alert: earlier versions of OpenAFS used to hand this implicit administer permission to the owner of any directory. In current versions of OpenAFS, only the owner of the top-level directory of the volume gets this special permission. So if you're on old docs energy, that's the plot twist 🫠.

✨ SEE ALSO ✨

the girlies you should also be reading, fr fr 🦋:

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0. It was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. shoutout to the whole crew for the conversion arc 🙌

aaaand that's the whole page, bestie 💖 you made it to the end, main character energy fr. this was the OpenAFS manual page for FS_SETACL(1), dated 2026-07-27 ✨ go set some ACLs responsibly, mwah 💅🎀

📦 where this page comes from