This is itended to become part of the USAGE document

[access control list plugin]

ACL's enable application of a superset of most of the "normal" permissions, to an item in a filesystem. Fine-tuning of *NIX read (r), write (w) and/or traverse|execute (x) permission is possible for particular users and/or particular groups. As such, ACL's are mainly relevant in contexts where there are various users, such as corporate systems.

Not all *NIX operating systems support ACL's. If the system does do so, not all items (or none at all) in the filesystem need actually have an ACL. Any item in a supporting filesystem may have an "access-ACL" that determines the effective r, w, and/or x permission(s) of the item.  On a system where _POSIX_ACL_EXTENDED is defined, any directory may also or instead have a "default-ACL" that governs the initial access-ACL for items created within that directory.

Two standard formats are used for human-readable ACL display.

This is an example of one ACL in the long text form:
    user::rw-
    user:lisa:rw-         #effective:r--
    group::r--
    group:444:rw-     #effective:r--
    mask::r--
    other::r--

These are two examples of the short text form:
    u::rw-,u:lisa:rw-,g::r--,g:444:rw-,m::r--,o::r--
    g:444:rw,u:lisa:rw,u::wr,g::r,o::r,m::r

An ACL consists of a series of ACL-entries. In the above examples, each line (in the long-form) and each comma-separated block (in the short-form) represents an ACL-entry. An ACL-entry contains
   * an entry tag type, largely represented by the first part of the entry (user, g, mask, o etc) (see below for a description of these types),
  * for two types of entry tag, a "qualifier", represented by the second part of the entry (a UID or GID - lisa, 444), and
  * a set of permissions represented by the third part of the entry (r w x).

The ACL_USER_OBJ entry denotes access rights for the item's owner. A valid ACL contains exactly one such entry. Typically, the "normal" rwx permissions defined for the item's owner would be used for the permissions of the ACL_USER_OBJ entry.

The ACL_GROUP_OBJ entry denotes default access rights for members of the item's group. A valid ACL contains exactly one such entry. Typically, the "normal" rwx permissions defined for the item's group would be used for the permissions of the ACL_GROUP_OBJ entry. If the ACL has no ACL_MASK entry, then the permissions defined for the item's group correspond to the permissions of the ACL_GROUP_OBJ entry. If the ACL does have an ACL_MASK entry, then the permissions defined for the item's group correspond to the permissions of the [ACL_GROUP_OBJ entry masked by (and'ed with) that?] ACL_MASK entry.

The ACL_OTHER entry denotes access rights for processes that do not match any other entry in the ACL. The "normal" "other" rwx permissions defined for the item would typically be used for the permissions of the ACL_OTHER entry. A valid ACL contains exactly one such entry.

ACL_USER entries denote the maximum access rights for the user identified by the entry's qualifier. This type of entry may appear zero or more times in an ACL. This type of entry has a qualifier denoting the identifier of a user (UID as a name or number). The actual permissions defined for the user correspond to the permissions of the ACL_USER entry masked by (and'ed with) the ACL_MASK entry.

ACL_GROUP entries denote access the maximum rights for groups identified by the entry's qualifier. This type of entry may appear zero or more times in an ACL. This type of entry has a qualifier denoting the identifier of a group (GID as a name or number). The actual permissions defined for the group correspond to the permissions of the ACL_GROUP entry masked by (and'ed with) the ACL_MASK entry.

An ACL_MASK entry denotes the maximum access rights that can be granted by entries of type ACL_USER, ACL_GROUP_OBJ, or ACL_GROUP. An ACL that contains entry(ies) of ACL_USER or ACL_GROUP tag types must contain exactly one entry of the ACL_MASK tag type. If an ACL contains no entries of ACL_USER or ACL_GROUP tag types, then an ACL_MASK entry is optional.

A qualifier denotes the identifier of a user or a group (UID or GID as a name or number), for entries with tag types of ACL_USER or ACL_GROUP, respectively. All user-ID qualifiers must be unique among all entries of ACL_USER tag type, and all group-ID qualifiers must be unique among all entries of ACL_GROUP tag type. Entries with tag types other than ACL_USER or ACL_GROUP have no defined qualifiers, and in human-readable form, their respective qualifiers are empty or blank.

You might get some further useful insight from the likes of:
   www.vanemery.com/Linux/ACL/linux-acl.html
   rofi.roger-ferrer.org/eiciel/doc

Whew !!!

There is a lot of ways that changes can be made using this plugin. You can add ACL(s) to any item that has none, and change any existing ACL in many ways, but (because the file system doesn't allow it) you can't entirely remove an existing ACL from an item. You can't add and remove things at the same time - you'd need to run the process twice to achieve that effect.

ACL entries for the current item are represented on separate lines in the dialog. Entries can be added or removed using the buttons at the bottom of the dialog, and can be edited in place.

What is the whole-flag for? Since in some cases (ACL_USER, ACL_GROUP, ACL_MASK) you can add that entire entry to, or remove that entire entry from, the ACL, or (if the entry exists already for an item being processed) you can just add to or remove from that entry's permissions. So we need to distinguish what is intended. If the entry's WHOLE setting is in effect, then as you'd expect, the specified change(s) for that entry apply to it as a whole, not just to its permissions. For other types of entries, the whole-flag is ignored, when setting or adding at least. A global whole-flag (below the displayed ACL), if set, has the same effect as setting each relevant whole-flag for all the entries in the ACL (at implementation-time, and whether or not the individual entries' whole-flags are set).

Among other things, this arrangement means you will want to set the whole-flag for entries being added to an ACL.

A common error when adding ACL_USER or ACL_GROUP entry(ies) - there must also be a ACL_MASK entry if there is any ACL_USER or ACL_GROUP entry in an ACL.

If the item currently being processed is a directory, you may choose to apply changes recursively. In that case, you may choose to apply changes to directories or to non-directories or to everything. Any changes to a directory (whether or not recursion is in effect) may be to its access-ACL and/or to its default-ACL, or to neither of those ACL's, depending on what has been selected. Remember - to apply changes to directories, you need to activate _all_ the relevant options.

This is how the change-process works in the plugin:

Each entry in the proposed new ACL is processed in turn. A WHOLE setting is deternined by whether the global whole-flag is set, or othewise, whether a whole-flag is set for the specific entry.

After all WHOLE settings are known, the ACL (if any) of the item being updated is interrogated.

If the chosen action is SET:
  * if a WHOLE setting is in effect:
    - if a matching existing entry is found, replace its permissions
    - if no matching existing entry is found, and if valid to do so, add this entry and its permissions
    - if no matching existing entry found, and not valid to add it, continue
  * if a WHOLE setting is NOT in effect:
    - if a matching existing entryis found, replace its permissions
    - if no matching existing entry is found, continue

If the chosen action is ADD:
  * if a WHOLE setting is in effect:
   - if matching existing entry is found, add specified permissions to it
   - if no matching existing entry is found, and if valid to do so, add this entry and its permissions
   - if no matching existing entry is found, and not valid to add it, continue
  * if a WHOLE setting is NOT in effect:
   - if matching existing entry is found, add permissions to it
   - if no matching existing entry is found, continue

If the chosen action is REMOVE:
  * if a WHOLE setting is in effect:
   - if matching existing entry is found, and if valid to do so, remove it
   - if matching existing entry is found, and if not valid to remove it entirely, remove specified permissions
   - if no matching existing entry is found, continue
  * if a WHOLE setting is NOT in effect:
   - if matching existing entry is found, remove specified permissions from it
   - if no matching existing entry is found, continue

Finally, a caveat. Not all operating systems (or more particularly their libraries used to manage ACL's) support the same level of functionality. This plugin has been developed on the assumption that there is reasonably-full functionality, more-or-less the full capability of the aborted POSIX standard for ACL's. Linux meets this requirement, others will just have to experiment.