diff --git a/doc/source/sysadmin.rst b/doc/source/sysadmin.rst index b40d75b24e..76f34638af 100644 --- a/doc/source/sysadmin.rst +++ b/doc/source/sysadmin.rst @@ -122,6 +122,66 @@ following practices must be observed for SSH access: then the old one removed. +Gerrit Admins +============= + +To provide a reasonable firewall from outside authentication systems, +Gerrit administrators keep two accounts: one for normal code review +activity and one for performing Gerrit administration. Following the same +pattern as our Kerberos administrator account logins, the admin account +corresponding to ``$USER`` would be ``$USER.admin`` (Gerrit doesn't allow +``/`` in usernames) so they can be easily identified when auditing +activity. Unlike the normal code review account, the admin account should +have no OpenID so that it is only accessable by API/CLI methods so they +cannot be compromised at the third-party ID provider. + +To create a personal Gerrit admin account from a shell on the server, run +the following command:: + + sudo -u gerrit2 ssh -i ~gerrit2/review_site/etc/ssh_host_rsa_key \ + -p 29418 -l 'Gerrit Code Review' localhost \ + "suexec --as openstack-project-creator -- \ + gerrit create-account --group Administrators --full-name myname.admin \ + --ssh-key 'ssh-rsa AAAA...BCDE myname@computer' myname.admin" + +We ``suexec`` as the ``openstack-project-creator`` account because the +magic ``Gerrit Code Review`` pseudoaccount can't set group memberships so +we need to run that command as a user which is already in the +``Administrators`` group. With an account like this, routine actions like +populating new groups with initial members is still quite simple:: + + ssh -p 29418 myname.admin@review.opendev.org \ + "gerrit set-members some-new-group --add somebody@example.org" + +Another common example is bypassing Zuul to submit a change for merging +directly to a project. In this case we must first add our account to +another group which has permission to set the relevant labels (it doesn't +get that simply by being an administrator), and then do the +commenting/voting/submitting, followed by cleaning up the extra group +membership again at the end:: + + ssh -p 29418 myname.admin@review.opendev.org \ + "gerrit set-members 'Project Bootstrappers' --add myname.admin" + + ssh -p 29418 myname.admin@review.opendev.org \ + "gerrit review 12345,6 --message 'Bypassing Zuul to merge this.' + --code-review 2 --verified 2 --label Workflow=1 --submit" + + ssh -p 29418 myname.admin@review.opendev.org \ + "gerrit set-members 'Project Bootstrappers' --remove myname.admin" + +Note that it's possible to temporarily add your normal OpenID-associated +WebUI account to the ``Administrators`` group or other groups with similar +superuser permissions like ``Project Bootstrappers``, but keep in mind that +an attacker who has quietly gained control of your account at the OpenID +provider could be waiting for that opportunity to take advantage of the +added permissions, or you may simply forget to remove the account afterward +negating the added safety of this account separation. + +For more examples, see the detailed documentation for Gerrit's SSH CLI, +available on our server: +https://review.opendev.org/Documentation/cmd-index.html + GitHub Access =============