Aegis documentation

#Host permissions for the web account

nginx does not run as root, and neither does PHP: both use nginx.user (aegis-www on an installed host). A document root that lives in the panel's own tree already belongs to that account. A root that lives somewhere else — /home/john/www is the normal case — belongs to john, and nginx answers 403 while everything in the panel looks correct.

Mode bits cannot express "john and aegis-www, nobody else": they have owner, group and everyone. Granting a second account means a shared group (one more thing to keep in sync) or chmod 777 (every account on the host). Aegis uses POSIX ACLs instead.

#What a grant consists of

ModeCommandsWhen
serve it (fix)setfacl -R -m u:aegis-www:rwX on the tree, d:u:aegis-www:rwX on every directory, u:aegis-www:x on every parentthe panel's own default for a document root
one accountsetfacl -R -m u:NAME:rwX plus default entries, u:NAME:x on the parentsa developer needs write access
everyonechmod -R a+rwXa shared tree, deliberately open

rwX is read and write for files, and read, write and traverse for directories — X adds execute only where it already makes sense.

Default entries matter: without them, 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.

Parent traversal is the bit everyone forgets. /home/john at 750 hides /home/john/www from nginx no matter what the inner tree allows, so every ancestor directory gets x for the account — and only x, never r or w.

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

#From the panel

Management → Permissions asks two questions before it changes anything:

  • Check — what the web account cannot reach, without touching the disk;
  • Preview — the exact commands the chosen mode would run;
  • Apply as a task — queues sys.perms.apply, so every command lands in a
  • task log next to its outcome.

    The form takes a path, a mode and, for the account mode, an account name.

    #From the command line

    bash
    aegis sys perms --path /home/john/www --check        # what is missingaegis sys perms --path /home/john/www --fix --dry-runaegis sys perms --path /home/john/www --fix          # the web account can serve itaegis sys perms --path /home/john/www --to john      # john can read and write itaegis sys perms --path /srv/shared --everyone        # a+rwX, recursive
    FlagMeaning
    --pathabsolute path, already on disk
    --to USERaccount that should read and write it; repeatable
    --group GROUPgroup that should access it (ACL, not a rename)
    --everyoneopen the tree to every account
    --fixmake the web account able to serve it, parents included
    --checkreport what is missing; changes nothing
    --no-recursiveonly the path itself
    --no-parentsleave the ancestors alone
    --dry-runprint the commands, run none

    Command line and panel share 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 one place and something else in the other.

    #Refused paths

    The helper refuses to work on the host's own roots, whatever is asked: /, /etc, /root, /boot, /dev, /proc, /sys, /usr, /bin, /sbin, /lib, /lib64, /run. The path is resolved first, so /home/john/../.. is compared as /home.

    The panel also validates a document root against safe_www_paths from config/web.toml: a prefix allow-list, checked on the resolved path and on a directory boundary, so /home/john/www-extra is not accepted for /home/john/www.

    #Automatic use

    When a vhost is created with a document root outside the panel's own tree (nginx.web_root), the task that creates it grants access as part of the same task: the vhost is useless without it, and an operator who forgot the second step would see a 403 with nothing in the panel to explain it. A root inside the panel's tree is left alone — it already belongs to the web account.

    #What to do when a site answers 403

  • Check the document root: a missing ACL for the web account or a parent
  • without x explains most cases.

  • Preview, then apply fix.
  • If the tree is on a file system without ACL support, setfacl fails and the
  • error says which path it could not change; the only options there are a shared group or everyone.

  • SELinux or AppArmor, when present, can still deny access that the ACL allows;
  • the panel does not manage those policies.