Control-panel roles and logins

Every Octopus instance runs its own Ægir control panel (Hostmaster), and every login to that panel carries one or more roles. The roles, and the permission each one holds, are not something the instance decides for itself: they are a Features export shipped by BOA in the hosting_custom_settings module, and the export is re-applied on every install and upgrade pass and once a night. This page is the operator reference for that matrix — where it comes from, what each role grants, how the tenant's own login is built, how a login comes to see a site, the backup-download gate, and the procedure for giving a tenant's colleague a panel login of their own. The tenant-facing version is logins and roles.

Where the matrix comes from, and why it cannot be edited on the box

hosting_custom_settings (package Features, enabled on every instance) exports eight roles and 232 permissions, and those permissions are granted across ten roles: the eight it creates, plus Drupal's own authenticated user and anonymous user, which every site already has. drush8 @hostmaster fr hosting_custom_settings -y re-asserts it on three occasions:

• in the nightly maintenance (night/10-account.sh), followed by two cache clears;
• on every Octopus install pass and on every upgrade pass, after the module set is enabled (satellite.sh.inc).

So a permission ticked or a role created by hand at admin/people/permissions is gone by the next morning, and a fresh instance carries the identical matrix from its first pass. This is deliberate: the matrix is a security boundary shared by the whole fleet, and the way to change it is a change to the export in the hosting_custom_settings fork, shipped with BOA — not an edit on one box. Custom per-tenant roles are not supported.

The export also stays honest on a box where some CMS modules are dark: the module strips from the comparison every permission whose owning module is disabled (hook_user_default_permissions_alter and hook_system_info_alter), so drush8 @hostmaster fl reports the feature as Default whether or not the Backdrop, Grav and Textpattern modules are on. And because Features reverts the permission component before the role component, the module re-runs the permission rebuild once more after a pass that walked both (hook_features_post_restore), so a role that the export introduces is created with its grants in one pass rather than empty until the next night.

The roles

Counts are the export's on a box with every CMS module enabled; on a box where the Backdrop, Grav or Textpattern modules are dark, their task permissions are absent from both sides of the comparison, so the numbers a role-list shows are lower for the roles that hold them and the feature still reads Default. aegir site operator holds none of them, so its 37 is the count on every box.

To read a role's grants on a box, as the instance user (or through su from root, the pattern used throughout this page):

su -s /bin/bash - o1 -c "cd /data/disk/o1 && drush8 @hostmaster rls 'aegir site operator'"

role-list (rls) lists every role without an argument, one role's permissions with a role name, and the roles holding a permission with --filter=<permission>.

aegir client in full

The tenant's own login holds it, and a colleague's login may hold it alone. Grouped by what the panel shows:

Two of those grants read wider than they are. The platform bulk actions are inert without view platform, because the Platforms list — the only place they are offered — is refused to the role; and the site bulk-operations form is hidden by hosting_site_views_pre_build from everyone without administer sites, so a client-role login never sees it either. Task control, on the other hand, is exactly as wide as it reads: cancel own tasks and retry failed tasks cover every task of a type the login may create, on every site it can view — a task the account owner queued included — and nothing on any other Client's site.

What the role does not hold: create delete task (admin and root only — Delete Site is the one task no colleague login can queue), administer tasks (admin and root only — it puts every task node on the instance in the login's reach through the hosting task realm, cancels any task, and re-runs one whatever its type), view platform, create platform, edit platform, delete platform, create dlock task, create dunlock task, create client, edit client users, administer users, administer sites, administer platforms, administer clients.

aegir site operator in full

Granted (37):

Withheld from the client set, and why:

Verified on a box: with the role and client membership alone, the site page offers Verify, Clone, Migrate, Flush all caches and the other granted tasks and no Backup, Restore, Reset password or Delete button; hosting_confirm/<nid>/site_login-reset and hosting_confirm/<nid>/site_backup answer 403; the Backups tab lists the backups with no Get, Export, Delete or Restore button and no Create a new backup link, and node/<nid>/backup/export/<bid>, /download/<bid>, /delete/<bid> and /restore/<bid> answer 403; a Reset password task queued by a client-role login leaves the operator seeing Go to <site> where the client sees Log in to <site>.

How the tenant's own login is built

On the instance's first pass (_LOCAL_STATUS=INIT), satellite.sh.inc:

1. Creates the tenant's Client node (title Octopus<random>, email = _CLIENT_EMAIL) and records it as hosting_default_client. Because BOA sets hosting_client_register_user 1, saving a client node with an email creates a panel user for that address with the aegir client role and a random password; hosting_client_send_welcome is 0, so nothing is mailed.
2. Renames that user to <oN>.ftp and sets its password to the shell password (_satellite_set_client_login), so the welcome email states one credential pair for both worlds. Matched by _CLIENT_EMAIL, uid > 1 guard.
3. Adds the roles admin, aegir account manager and aegir client to the same user (urol by --mail), and seeds the userprotect table: the uid 0 defaults protect every account that has no row of its own against edit and cancel by other accounts (up_edit=1, up_cancel=1), and the tenant's own account gets a row of its own — up_status, up_roles and up_cancel set, up_edit not.

The result, readable on any instance:

su -s /bin/bash - o1 -c "cd /data/disk/o1 && drush8 @hostmaster sqlq \"select u.uid, u.name, group_concat(r.name) from users u left join users_roles ur on ur.uid=u.uid left join role r on r.rid=ur.rid where u.uid>0 group by u.uid\""

Expect uid 1 admin with administrator, and uid 2 <oN>.ftp with aegir client,aegir account manager,admin. Both are attached to a client in hosting_client_user: uid 1 to client 1 (admin), the tenant to the default client.

Two consequences worth knowing when a tenant asks:

• The tenant's login holds administer users, so it can open the People list and add a user there — but the Roles field on the account form needs administer permissions, which no exported role but root holds, so the new user gets only authenticated user and sees nothing; and the userprotect defaults keep the tenant from editing or cancelling any other account. Creating a login that does something is therefore always the operator's step (below).
• The tenant can create further Clients. Creating one with an email address creates a client-role user for it (random, unusable password, no mail), which the tenant cannot then edit; the operator finishes it with upwd, or creates the login outright.

How a login comes to see a site

Under the client feature, hosting_site_node_access and hosting_platform_node_access return IGNORE for every operation but create, and node access is decided by grants (hosting_client.access.inc):

• Membership is the hosting_client_user table — the Allowed users list on a Client's edit form. A user may be attached to several Clients.
• Sites and clients carry a grant in the realm hosting site / hosting client with gid = the client nid; tasks inherit their parent's. A login holding view site gets the gids of the Clients it is attached to; a login holding administer sites gets gid 1, i.e. every site. So view site alone shows nothing until the user is attached to a Client, and attaching a user to a Client is what puts that Client's sites in front of it.
• Platforms carry a grant per Client named in the platform's client access list (hosting_platform_client_access, the Clients tab on a platform node) plus the admin grant. A platform with an empty list is offered to every Client on the site form (p.pid IS NULL in the accessible-platforms query), but its own page and the Platforms list show it only to logins holding administer platforms. A site-operator login therefore lists the platforms whose client access names its Client, and can still create a site on any platform open to all.
• Task pages and logs need access task logs and view access on the task's node (hosting_task_log_access); a task on a site outside the login's Clients is refused by nid. Queueing a task on a site needs create <type> task and view access on the site (the site branch of hosting_task_menu_access). Retrying (hosting_task_retry_access) needs retry failed tasks, create <type> task for the task's own type, and view access on the node the task ran on — the retry form carries the task nid as a hidden value, so a nid on another Client's site, or of a type the login could not queue, is refused; a site-operator login cannot re-run a backup or login-reset task, a client-role login can re-run any task on its Clients' sites, whoever queued it. Cancelling (hosting_task_cancel_access) follows the same triple with cancel own tasks. administer tasks — admin and root only — short-circuits both: it cancels any queued task on the instance and re-runs a task whatever its type, which is why no tenant-facing role carries it.
• Every queued task records the login behind it in hosting_task.queued_by; the task page prints Queued by and the task lists carry the column.

The backup-download gate

hosting_site_backup_manager gates its routes by node_access('view') alone and creates its export tasks directly, so any login able to view a site could take its archive. hosting_custom_settings defines the permission download site backups (restrict access set) and re-points the routes in hook_menu_alter:

download site backups is granted to admin, administrator, aegir client and root, and withheld from aegir site operator. administrator holds neither create backup-delete task nor create restore task, so the Backups tab's Delete and Restore answer 403 for it — the same answer the site page gives it. The tab (node/%node/backups) and its AJAX refresh list every backup for anyone who can view the site; the two page callbacks are wrapped so the buttons of denied actions, and the Create a new backup link without create backup task, are not rendered. The access callbacks are the boundary; the stripping is presentation.

Giving a tenant's colleague a panel login

The tenant asks for a login, names the person, the role — Client or Site operator — and the Client the person works under. As root, with the instance user o1 and the new login jane:

1. Create the user with a password of your choosing (the panel's self-service reset link is switched off, so this is the password the person gets):

   SHCopy

   su -s /bin/bash - o1 -c "cd /data/disk/o1 && drush8 @hostmaster ucrt jane [email protected] --password='<password>'"
   

2. Give it the role — one of the two:

   SHCopy

   su -s /bin/bash - o1 -c "cd /data/disk/o1 && drush8 @hostmaster urol 'aegir site operator' jane"
   

   SHCopy

   su -s /bin/bash - o1 -c "cd /data/disk/o1 && drush8 @hostmaster urol 'aegir client' jane"
   

3. Attach it to the Client. The tenant can do this in the panel — the Client's edit form, Associate a user to this Client — with their own login, which holds edit client users. From the shell, find the client node and insert the membership row (the same statement the panel writes):

   SHCopy

   su -s /bin/bash - o1 -c "cd /data/disk/o1 && drush8 @hostmaster sqlq \"select nid, title from node where type='client'\""
   

   SHCopy

   su -s /bin/bash - o1 -c "cd /data/disk/o1 && drush8 @hostmaster sqlq \"insert ignore into hosting_client_user (user, client) values (<uid>, <client nid>)\""
   

   The uid is in the users table (select uid from users where name='jane').

4. Check it before handing the password over:

   SHCopy

   su -s /bin/bash - o1 -c "cd /data/disk/o1 && drush8 @hostmaster uli --name=jane --no-browser"
   

   Open the link: the Sites list shows the Client's sites and no others; for a site operator the site page has no Backup, Restore, Reset password or Delete button and the Backups tab no Get, Export, Delete or Restore.

5. Hand it over through the tenant, by whatever channel they use for passwords. The person changes the password on their own account page; it never expires.

Later changes, all as the instance user through the same su pattern:

Never give a colleague login the admin role to save time: it carries administer users, create delete task and the platform operations, and the tenant's own login already holds it. Never hand out uid 1.

Which shell account matches which role

Panel roles and shell accounts are separate systems that meet at the Client: the two shell accounts a tenant can give an outsider are built from the Client that owns the sites (manage_ltd_users.sh), not from any panel login. Match them by the power they carry:

The developer account's own page carries the same rule under Before you start: platform developer account.

Verifying the matrix on a box

The same checks the delivery proof runs, as the instance user:

drush8 @hostmaster fl | grep -i custom_settings
drush8 @hostmaster sqlq "select count(*) from role where name='aegir site operator'"
drush8 @hostmaster sqlq "select count(*) from role_permission rp join role r on r.rid=rp.rid where r.name='aegir site operator'"
drush8 @hostmaster sqlq "select group_concat(r.name order by r.name) from role_permission rp join role r on r.rid=rp.rid where rp.permission='download site backups'"

Expect Default, 1, 37 and admin,administrator,aegir client,root. The site-operator set holds no Backdrop, Grav or Textpattern permission, so 37 is its count on every box, dark CMS modules or not: a lower number is the export not landing, never a dark module. A feature reading Overridden means a hand edit is pending its revert: drush8 @hostmaster fr hosting_custom_settings -y re-applies the export at once.

Related

• Logins and roles — the tenant-facing page.
• Platform developer account — the operator procedure for oN.<client>-dev.
• Shell extras — the ordinary per-Client sub-account.
• lshell + manage_ltd_users — the restricted shell and the worker behind every tenant account.
• Hosting module suite — the modules whose permissions the export covers.