From d4ba30251bbc3196d16608592ab54d4bd02d2272 Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Wed, 11 Aug 2021 11:20:50 +1000 Subject: [PATCH] gerrit docs : remove old database docs/update duplicate account info A lot of the current sections here talk about modify the Gerrit database that no longer exists. Remove these. Update the section on duplicate accounts to handle removing the second account via NoteDB and the API. Change-Id: I2139ff33d87bf42e4453f6e7252fcc427594967a --- doc/source/gerrit.rst | 175 +++++++++++------------------------------- 1 file changed, 44 insertions(+), 131 deletions(-) diff --git a/doc/source/gerrit.rst b/doc/source/gerrit.rst index 738476e912..545c3a008c 100644 --- a/doc/source/gerrit.rst +++ b/doc/source/gerrit.rst @@ -453,161 +453,74 @@ API documentation. .. _create-account: https://review.opendev.org/Documentation/cmd-create-account.html -Resetting a Username in Gerrit ------------------------------- - -Initially if a Gerrit username (which is used to associate SSH -connections to an account) has not yet been set, the user can type -it into the Gerrit WebUI... but there is no supported way for the -user to alter or correct it once entered. Further, if a defunct -account has the desired username, a different one will have to be -entered. - -Because of this, often due to the user ending up with `Duplicate -Accounts in Gerrit`_, it may be requested to change the SSH username -of an account. Confirm the account_id number for the account in -question and remove the existing username external_id for that (it -may also be necessary to remove any lingering external_id with the -desired username if confirmed there is a defunct account associated -with it): - -.. code-block:: mysql - - delete from account_external_ids where account_id=NNNN and external_id like 'username:%'; - -After this, the user should be able to re-add their username through -the Gerrit WebUI. +Deleting Accounts in Gerrit +--------------------------- +We can not delete accounts. They can be made inactive. Duplicate Accounts in Gerrit ---------------------------- -From time to time, outside events affecting SSO authentication or -identity changes can result in multiple Gerrit accounts for the same -user. This frequently causes duplication of preferred E-mail -addresses, which also renders the accounts unselectable in some -parts of the WebUI (notably when trying to add reviewers to a change -or members in a group). Gerrit does not provide a supported -mechanism for `Combining Gerrit Accounts`_, and doing so manually is -both time-consuming and error prone. As a result, the OpenStack -infrastructure team does not combine duplicate accounts for users -but can clean up these E-mail address issues upon request. To find -the offending duplicates: +If a user has two accounts, we can not combine them. We can only +deactivate one of them. -.. code-block:: mysql +For example, user ``foo`` has an account ``foo@company.com`` and moves +to a new job, creating a new account ``foo@new.com``. They log-in +with ``foo@new.com``, but then realise what they really wanted to do +was *add* this new address to their existing account +(i.e. ``foo@company.com``). - select account_id from accounts where preferred_email='user@example.com'; +The first step to resolve this is to confirm the ID of the unwanted +account, . As an admin user with a HTTP password set, search for the +new account: -Find out from the user which account_id is the one they're currently -using, and then null out the others with: +.. -.. code-block:: mysql + curl -u you.admin -i -H "Accept: application/json" 'https://review.opendev.org/a/accounts/foo@new.com' - update accounts set preferred_email=NULL, registered_on=registered_on where account_id=OLD; +That will return an ``_acount_id``. For this example, assume it is +``12345``. The user should check in their settings they are *not* +using this account. -Then be sure to set the old account to inactive: +Clone ``All-Users`` to modify the account, and checkout the account +config, which is sharded by the last two digits of the account-id. -.. code-block:: bash +.. - ssh review.opendev.org -p29418 gerrit set-account --inactive OLD + git clone ssh://you.admin@review.opendev.org:29418/All-Users + git fetch refs/users/45/12345 + git checkout FETCH_HEAD -Finally, flush Gerrit's caches so any immediate account lookups will hit -the current DB contents: +Edit the ``[account]`` section of ``account.conf`` to remove +``preferredEmail`` and have a line ``active = false``. Put your admin +account into ``Project Bootstrappers`` (see :ref:`sysadmin`) and +commit this -.. code-block:: bash +.. - ssh review.opendev.org -p29418 gerrit flush-caches --all + git commit -m "Make duplicate account inactive" --author + git push origin HEAD:refs/users/45/12345 +There will still be an OpenID external ID associated with this now +inactive account. This will prevent adding ``foo@new.com`` to another +account until this is removed. -Combining Gerrit Accounts -------------------------- +Check this via the API with -While not supported by Gerrit, a fairly thorough account merge is -documented here (mostly as a demonstration of its unfortunate -complexity). Please note that the OpenStack infrastructure team does -not combine duplicate accounts for users upon request, but this -would be the process to follow if it becomes necessary under some -extraordinary circumstance. +.. -Collect as much information as possible about all affected accounts, -and then go poking around in the tables listed below for additional -ones to determine the account_id number for the current account and -any former accounts which should be merged into it. Then for each -old account_id, perform these update and delete queries: + curl -u you.admin -i -H "Accept: application/json" https://review.opendev.org/a/accounts/12345/external.ids -.. code-block:: mysql +This will give a json result with an ``identity`` URL like +``"identity":"https://login.ubuntu.com/+id/RaND0m``. Use this to +delete the record with another call - delete from account_agreements where account_id=OLD; - delete from account_diff_preferences where id=OLD; - delete from account_external_ids where account_id=OLD; - delete from account_group_members where account_id=OLD; - delete from account_group_members_audit where account_id=OLD; - delete from account_project_watches where account_id=OLD; - delete from account_ssh_keys where account_id=OLD; - delete from accounts where account_id=OLD; - update account_patch_reviews set account_id=NEW where account_id=OLD; - update starred_changes set account_id=NEW where account_id=OLD; - update change_messages set author_id=NEW, written_on=written_on where author_id=OLD; - update changes set owner_account_id=NEW, created_on=created_on where owner_account_id=OLD; - update patch_comments set author_id=NEW, written_on=written_on where author_id=OLD; - update patch_sets set uploader_account_id=NEW, created_on=created_on where uploader_account_id=OLD; - update patch_set_approvals set account_id=NEW, granted=granted where account_id=OLD; +.. -If that last update query results in a collision with an error -like:: + curl -XPOST -u you.admin -i -H "Content-Type: application/json" -d '["https://login.ubuntu.com/+id/RaND0m"]' https://review.opendev.org/a/accounts/12345/external.ids:delete - ERROR 1062 (23000): Duplicate entry 'XXX-YY-NEW' for key 'PRIMARY' - -Then you can manually delete the old approval: - -.. code-block:: mysql - - delete from patch_set_approvals where account_id=OLD and change_id=XXX and patch_set_id=YY; - -And repeat until the update query runs to completion. - -After all the described deletes and updates have been applied, flush -Gerrit's caches so things like authentication will be rechecked -against the current DB contents: - -.. code-block:: bash - - ssh review.opendev.org -p29418 gerrit flush-caches --all - -Make the user aware that these steps have also removed any group -memberships, preferences, SSH keys, CLA -signatures, and so on associated with the old account so some of -these may still need to be added to the new one via the Gerrit WebUI -if they haven't been already. With a careful inspection of all -accounts involved it is possible to merge some information from the -old accounts into new ones by performing update queries similar to -the deletes above, but since this varies on a case-by-case basis -it's left as an exercise for the reader. - - -Deleting a User from Gerrit ---------------------------- - -This isn't normally necessary, but if you find that you need to -completely delete an account from Gerrit, perform the same delete -queries mentioned in `Combining Gerrit Accounts`_ and replace the -update queries for account_patch_reviews and starred_changes with: - -.. code-block:: mysql - - delete from account_patch_reviews where account_id=OLD; - delete from starred_changes where account_id=OLD; - -The other update queries can be ignored, since deleting them in many -cases would result in loss of legitimate review history. - -Refreshing HTML and CSS configuration -------------------------------------- - -When there is a change in HTML headers, or CSS, this can be applied -without the need of restarting Gerrit. To do that, ssh in the Gerrit -instance, and touch GerritSiteHeader.html and/or GerritSite.css, -under /home/gerrit2/review_site/etc directory. +The user should now be able to add ``foo@new.com`` to their old +account. Deactivating a Gerrit account -----------------------------