#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
aegis sys <action> options| Action | Purpose |
|---|---|
perms | grant 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
sysone: seeaegis publishin 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
aegis sys perms --path PATH --to USER ... --group GROUP --everyone --fix --check --no-recursive --no-parents --dry-run#Options
| Option | Default | Effect |
|---|---|---|
--path PATH | required | absolute, existing path; resolved before use |
--to USER | none | account that may read and write; repeatable |
--group GROUP | none | group that may read and write |
--everyone | off | open the tree to every account |
--fix | off | let the web account serve the tree |
--check | off | report what is missing, change nothing |
--no-recursive | off | only the path itself, not the tree |
--no-parents | off | leave the ancestor directories alone |
--dry-run | off | print 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:
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 parentrwX is read and write on files, and read, write and traverse ondirectories — X adds execute only where it already makes sense.
d:) is what new files inherit. Without it a file createdtomorrow by the owner is readable only by the owner again, and the vhost breaks a day later for no visible reason.
r or w. /home/john at 750hides /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 ignoredwith it, and the check inspects the web account only (nginx.user), not the accounts named with --to.
--to accounts, then--group, then --everyone, then --fix.
--no-recursive and --no-parents apply to grants. --fix is alwaysrecursive and always writes the parent entries.
--everyone writes no parent entries, so --no-parents changes nothingthere.
--dry-run still resolves and validates the path, and still prints thetable; the action column reads would run setfacl or would run chmod.
/home/../etc is compared as /etc and refused.
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
aegis sys perms --path /home/john/www --checkWhat the web account cannot reach, without touching anything:
✔ /home/john/www: aegis-www can reach itaegis sys perms --path /home/john/www --fix --dry-runThe exact commands --fix would run, in order:
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-runaegis sys perms --path /home/john/www --fixThe same run for real. The table is printed first, then the summary:
✔ 6 change(s) appliedaegis sys perms --path /home/john/www --to johnLets john read and write the tree, with default entries for new files and traversal on /home/john and /home:
✔ 6 change(s) appliedaegis sys perms --path /srv/shared --group devs --no-parents --dry-runThe group entry on its own, with the ancestors left alone:
action path detail───────────────── ─────────── ────────────────would run setfacl /srv/shared -R -m g:devs:rwXℹ 1 change(s) previewed; run again without --dry-runaegis sys perms --path /srv/shared --everyone --dry-runThe whole tree opened to every account:
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:
✖ /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:
ℹ N change(s) previewed; run again without --dry-runIf the requested operations produce no command at all, it prints ℹ nothing changed and exits 0.
Refusals and failures are one ✖ line on stderr:
✖ 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
| Code | Meaning |
|---|---|
0 | the changes were applied (or previewed), or the check found nothing |
1 | refused or missing path, failed command, or problems from --check |
2 | no 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.