Aegis documentation

#sys

aegis sys holds operations on the host itself — the things that are neither an application nor a service. It currently has one action, perms, which grants or inspects access to a directory tree with POSIX ACLs.

perms exists because mode bits cannot say "this account and the web account, nobody else". A document root under /home/john belongs to john; nginx runs as nginx.user (aegis-www on an installed host) and answers 403. A shared group is one more thing to keep in sync, and chmod 777 opens the tree to the whole machine. An ACL names the accounts instead, and ownership never changes.

The panel's Management → Permissions page calls the same implementation (app/core/sys/perms.py for the modes, app/core/sys/acl.py for the commands), so a mode cannot mean one thing in the panel and another on the command line.

#aegis sys

bash
aegis sys <action> options
ActionPurpose
permsgrant or inspect access to one path

sys has no bare form: aegis sys without an action is a usage error and exits 2. aegis sys --help lists the actions.

Linking the launcher is a top-level command, not a sys one: see aegis publish in the introduction.

#aegis sys perms

Grants read and write on a tree to named accounts, a group, or everybody; makes the web account able to serve it; or reports what the web account cannot reach. Every command it runs is printed in a three-column table, so a preview and a real run look the same; --check is the one mode that reports instead of changing.

Destructive. Changes permissions on a tree, and --everyone makes it readable and writable by every account on the host.

#Syntax

bash
aegis sys perms --path PATH --to USER ... --group GROUP --everyone                --fix --check --no-recursive --no-parents --dry-run

#Options

OptionDefaultEffect
--path PATHrequiredabsolute, existing path; resolved before use
--to USERnoneaccount that may read and write; repeatable
--group GROUPnonegroup that may read and write
--everyoneoffopen the tree to every account
--fixofflet the web account serve the tree
--checkoffreport what is missing, change nothing
--no-recursiveoffonly the path itself, not the tree
--no-parentsoffleave the ancestor directories alone
--dry-runoffprint the commands, run none

At least one of --to, --group, --everyone, --fix or --check is required; without one the command exits 2.

#What a grant changes

--fix and --to USER write three kinds of command:

bash
setfacl -R -m u:USER:rwX PATH             # the treesetfacl -m d:u:USER:rwX DIR               # every directory in itsetfacl -m u:USER:x PARENT                # every existing parent
  • rwX is read and write on files, and read, write and traverse on
  • directories — X adds execute only where it already makes sense.

  • The default entry (d:) is what new files inherit. Without it a file created
  • tomorrow by the owner is readable only by the owner again, and the vhost breaks a day later for no visible reason.

  • The parent entry is traversal only, never r or w. /home/john at 750
  • hides /home/john/www from nginx whatever the inner tree allows.

    --group GROUP writes setfacl -R -m g:GROUP:rwX PATH and the parent calls, but no default entries: new files inside the tree do not inherit the group.

    --everyone writes chmod -R a+rwX PATH (or chmod a+rwX PATH with --no-recursive) and nothing else — no ACL, no parent entries.

    The account or group must already exist on the host. setfacl refuses an unknown name and the command exits 1 with the tool's message.

    The parent entries are always written as user entries (u:NAME:x), also when the grant came from --group. A group name that is not also an account name is therefore rejected on the parent call and the command exits 1 after reporting it; --no-parents skips those calls entirely.

    #How the flags combine

  • --check returns before anything is changed. The other flags are ignored
  • with it, and the check inspects the web account only (nginx.user), not the accounts named with --to.

  • When several grants are given, they run in this order: --to accounts, then
  • --group, then --everyone, then --fix.

  • --no-recursive and --no-parents apply to grants. --fix is always
  • recursive and always writes the parent entries.

  • --everyone writes no parent entries, so --no-parents changes nothing
  • there.

  • --dry-run still resolves and validates the path, and still prints the
  • table; the action column reads would run setfacl or would run chmod.

  • A path is resolved through symlinks before the refusal list is checked, so
  • /home/../etc is compared as /etc and refused.

  • Ownership is never changed. A file that must be writable by the web account
  • gets an ACL entry; chown would move it away from the account that owns the project.

    The command runs setfacl and chmod with the privileges of the caller; changing a tree that belongs to another account needs root, which is how the panel runs it.

    #Examples

    bash
    aegis sys perms --path /home/john/www --check

    What the web account cannot reach, without touching anything:

    text
    ✔ /home/john/www: aegis-www can reach it
    bash
    aegis sys perms --path /home/john/www --fix --dry-run

    The exact commands --fix would run, in order:

    text
    action             path                    detail─────────────────  ──────────────────────  ─────────────────────would run setfacl  /home/john/www          -R -m u:aegis-www:rwXwould run setfacl  /home/john/www          -m d:u:aegis-www:rwXwould run setfacl  /home/john/www/blog     -m d:u:aegis-www:rwXwould run setfacl  /home/john/www/uploads  -m d:u:aegis-www:rwXwould run setfacl  /home/john              -m u:aegis-www:xwould run setfacl  /home                   -m u:aegis-www:xℹ 6 change(s) previewed; run again without --dry-run
    bash
    aegis sys perms --path /home/john/www --fix

    The same run for real. The table is printed first, then the summary:

    text
    ✔ 6 change(s) applied
    bash
    aegis sys perms --path /home/john/www --to john

    Lets john read and write the tree, with default entries for new files and traversal on /home/john and /home:

    text
    ✔ 6 change(s) applied
    bash
    aegis sys perms --path /srv/shared --group devs --no-parents --dry-run

    The group entry on its own, with the ancestors left alone:

    text
    action             path         detail─────────────────  ───────────  ────────────────would run setfacl  /srv/shared  -R -m g:devs:rwXℹ 1 change(s) previewed; run again without --dry-run
    bash
    aegis sys perms --path /srv/shared --everyone --dry-run

    The whole tree opened to every account:

    text
    action             path         detail─────────────────  ───────────  ────────would run chmod    /srv/shared  -R a+rwXℹ 1 change(s) previewed; run again without --dry-run

    #Output

    --check with nothing wrong prints ✔ PATH: WEB can reach it on stdout. With problems it prints one ✖ line per problem on stderr and exits 1 — parents first, the tree last:

    text
    ✖ /home/john: no execute bit for aegis-www✖ /home/john/www: no ACL entry for aegis-www (reachable through 'other' at most, never writable)

    A run, or a preview, prints the table on stdout and then one summary line — ✔ N change(s) applied for a run, and for a preview:

    text
    ℹ N change(s) previewed; run again without --dry-run

    If the requested operations produce no command at all, it prints ℹ nothing changed and exits 0.

    Refusals and failures are one ✖ line on stderr:

    text
    ✖ the path must be absolute: www✖ no such path: /srv/gone✖ refusing to change permissions on /etc✖ nothing to do: pass --to, --group, --everyone, --fix or --check✖ setfacl failed on /srv/shared: setfacl: /srv/shared: Operation not supported

    #Exit codes

    CodeMeaning
    0the changes were applied (or previewed), or the check found nothing
    1refused or missing path, failed command, or problems from --check
    2no operation was requested

    #Refused paths

    Whatever is asked, the resolved path may not be one of the host's own roots: /, /etc, /root, /boot, /dev, /proc, /sys, /usr, /bin, /sbin, /lib, /lib64, /run. The path must also be absolute and already exist, including for --check and --dry-run.

    On a file system without ACL support setfacl fails and the error names the path it could not change. There --everyone is the only grant this command can apply; a shared group would have to be arranged with chgrp and mode bits outside it.

    See Permissions for the panel side of the same operation, and Conventions for how sys.perms.apply records a write as a task.