Access Control Lists and Permission Troubleshooting

1. ACLs extend the group-class decision

An extended access ACL can contain named-user and named-group entries in addition to the file owner, owning group, and other entries. The ACL mask limits the effective permissions of named users, named groups, and the owning-group entry. The file owner entry and other entry are not limited by that mask.

flowchart TB
  P["Process effective UID and groups"] --> O{"Matches file owner?"}
  O -->|yes| UE["Use owner entry"]
  O -->|no| NU{"Named user entry?"}
  NU -->|yes| UM["Named-user entry AND mask"]
  NU -->|no| GM{"Any matching group entries?"}
  GM -->|yes| AG["Union matching groups AND mask"]
  GM -->|no| OT["Use other entry"]
  UE --> R{"Requested access allowed?"}
  UM --> R
  AG --> R
  OT --> R

lab="$HOME/devops-academy/linux/chapter06/lesson05"
mkdir -p -- "$lab"
printf 'deployment=approved
' > "$lab/release.txt"

ls -l -- "$lab/release.txt"
getfacl -p -- "$lab/release.txt"

A plus sign after the mode string in many ls -l implementations indicates additional ACL information. Use getfacl for the authoritative entry set and effective-permission comments.

2. setfacl changes named entries and the mask

The common modify form is setfacl -m SPEC FILE. Entries include u:NAME:PERMS, g:NAME:PERMS, and m::PERMS for the mask. -x removes selected entries and -b removes all extended entries.

file="$HOME/devops-academy/linux/chapter06/lesson05/release.txt"

# Add a named-user entry for an account commonly present on Linux systems.
if getent passwd nobody >/dev/null; then
  setfacl -m u:nobody:r-- -- "$file"
fi

# Add a named group entry only when a supplementary group is available.
primary_group=$(id -gn)
acl_group=$(id -nG | tr ' ' '\n' | awk -v primary="$primary_group" '$0 != primary { print; exit }')
if [ -n "$acl_group" ]; then
  setfacl -m "g:$acl_group:r--" -- "$file"
fi

# Inspect entries and effective permissions.
getfacl -p -- "$file"

# Remove the named nobody entry if it was added.
if getent passwd nobody >/dev/null; then
  setfacl -x u:nobody -- "$file"
fi

By default, setfacl may recalculate the mask to include permissions required by modified entries. Use explicit mask management only when the policy is understood; an unexpectedly narrow mask is a frequent source of “the ACL says rw but access is read-only” incidents.

3. The mask defines effective group-class access

Consider a named entry user:deploy:rw- with mask r--. The stored entry requests read/write, but its effective permission is read-only because write is removed by the mask. getfacl normally prints an #effective: annotation when the mask reduces an entry.

file="$HOME/devops-academy/linux/chapter06/lesson05/mask-demo.txt"
printf 'mask demo
' > "$file"

if getent passwd nobody >/dev/null; then
  setfacl -m u:nobody:rw- -- "$file"
  setfacl -m m::r-- -- "$file"
  getfacl -p -- "$file"
  # Restore a mask that allows the named write permission.
  setfacl -m m::rw- -- "$file"
fi

4. Default ACLs define inherited entries for new children

A directory can carry a default ACL. When a child is created, that default is used to derive the child’s access ACL, constrained by the creating program’s requested mode. Default ACLs are not retroactive and do not automatically repair existing content.

shared="$HOME/devops-academy/linux/chapter06/lesson05/shared"
rm -rf -- "$shared"
mkdir -p -- "$shared"
chmod 2770 -- "$shared"

# Give the owning group inherited read/write on files and traversal on dirs.
setfacl -m d:u::rwx,d:g::rwx,d:o::---,d:m::rwx -- "$shared"

printf 'new artifact
' > "$shared/artifact.txt"
mkdir -- "$shared/release-dir"

getfacl -p -- "$shared"
getfacl -p -- "$shared/artifact.txt"
getfacl -p -- "$shared/release-dir"

For a named team group, add both an access entry on the directory and a default named-group entry, then ensure the default mask permits the intended rights. Always create a test child and inspect it.

5. Troubleshoot permissions from the process outward

target="$HOME/devops-academy/linux/chapter06/lesson05/shared/artifact.txt"

id
namei -l -- "$target"
stat -c 'mode=%A octal=%a owner=%U:%G ids=%u:%g type=%F name=%n' -- "$target"
getfacl -p -- "$target"
findmnt -T "$target" -o TARGET,SOURCE,FSTYPE,OPTIONS
lsattr -- "$target" 2>/dev/null || true
df -h -- "$target"
df -i -- "$target"

6. Hands-on lab: create and diagnose an ACL policy

The getfacl and setfacl tools are commonly provided by an acl package. The lab exits with a clear message if they are unavailable.

set -eu
command -v getfacl >/dev/null || { printf 'Install the acl tools first.
' >&2; exit 1; }
command -v setfacl >/dev/null || { printf 'Install the acl tools first.
' >&2; exit 1; }

lab="$HOME/devops-academy/linux/chapter06/lesson05"
root="$lab/acl-lab"
rm -rf -- "$root"
mkdir -p -- "$root/shared"
printf 'build=42
' > "$root/shared/manifest.txt"
chmod 750 -- "$root/shared"
chmod 640 -- "$root/shared/manifest.txt"

# Add and then deliberately mask a named entry when nobody exists.
if getent passwd nobody >/dev/null; then
  setfacl -m u:nobody:rw-,m::r-- -- "$root/shared/manifest.txt"
fi

{
  printf '=== identity ===
'
  id
  printf '
=== path ===
'
  namei -l -- "$root/shared/manifest.txt"
  printf '
=== stat ===
'
  stat -c '%A %a %U:%G %n' -- "$root/shared/manifest.txt"
  printf '
=== acl before repair ===
'
  getfacl -p -- "$root/shared/manifest.txt"
} > "$lab/acl-diagnosis.txt"

# Repair the ACL mask if the named entry exists.
if getent passwd nobody >/dev/null; then
  setfacl -m m::rw- -- "$root/shared/manifest.txt"
fi

printf '
=== acl after repair ===
' >> "$lab/acl-diagnosis.txt"
getfacl -p -- "$root/shared/manifest.txt" >> "$lab/acl-diagnosis.txt"
cat -- "$lab/acl-diagnosis.txt"

7. Common ACL and troubleshooting mistakes

8. Knowledge check

9. Summary

POSIX ACLs add named identities and default inheritance to the traditional permission model, while the ACL mask defines effective group-class access. Permission troubleshooting must proceed from the real process identity through path traversal, modes, ownership, ACLs, filesystem state, and additional security controls. Preserve evidence, make the smallest repair, and verify the exact operation.

10. Further reading

• Linux man-pages and ACL manuals: acl(5), getfacl(1), and setfacl(1).
• POSIX access-control list model and Linux filesystem ACL documentation.
• Linux man-pages: path_resolution(7), stat(2), and mount(8).
• Filesystem manuals for extended attributes, mount options, and ACL support.