gerrit/Documentation/cmd-set-account.txt
Richard Christie 2a29838da3 Relax access to ssh set-account command
This commit modifies access to the set-account to enable users to set
their own account details without needing MODIFY_ACCOUNT. This makes it
similar to the REST API.

All other access should be the same as before, though we now check some
settings we know require admin and catch those early to give clearer
error messages to the user. Previously things failed with:

fatal: administrate server not permitted

without saying which out of potentially multiple settings being changed
required that.

Change-Id: I7e07743209b6cd6c7ececa21e4e5f65ee629bedf
2018-07-02 11:25:53 +01:00

122 lines
3.9 KiB
Plaintext

= gerrit set-account
== NAME
gerrit set-account - Change an account's settings.
== SYNOPSIS
[verse]
--
_ssh_ -p <port> <host> _gerrit set-account_
[--full-name <FULLNAME>] [--active|--inactive]
[--add-email <EMAIL>] [--delete-email <EMAIL> | ALL]
[--preferred-email <EMAIL>]
[--add-ssh-key - | <KEY>]
[--delete-ssh-key - | <KEY> | ALL]
[--generate-http-password]
[--http-password <PASSWORD>]
[--clear-http-password] <USER>
--
== DESCRIPTION
Modifies a given user's settings. This command can be useful to
deactivate an account, set HTTP password, add/delete ssh keys without
going through the UI.
It also allows managing email addresses, which bypasses the
verification step we force within the UI.
== ACCESS
Users can call this to update their own accounts. To update a different
account, a caller must be a member of the privileged 'Administrators'
group, or have been granted
link:access-control.html#capability_modifyAccount[the 'Modify Account' global capability].
For security reasons only the members of the privileged 'Administrators'
group can add or delete SSH keys for a user.
To set the HTTP password for the user account (option --http-password) or
to clear the HTTP password (option --clear-http-password) caller must be
a member of the privileged 'Administrators' group.
== SCRIPTING
This command is intended to be used in scripts.
== OPTIONS
<USER>::
Required; Full name, email-address, SSH username or account id.
--full-name::
Set the display name for the user account.
+
Names containing spaces should be quoted in single quotes (').
This most likely requires double quoting the value, for example
`--full-name "'A description string'"`.
--active::
Set the account state to be active.
--inactive::
Set the account state to be inactive. This prevents the
user from logging in.
--add-email::
Add another email to the user's account. This doesn't
trigger the mail validation and adds the email directly
to the user's account.
May be supplied more than once to add multiple emails to
an account in a single command execution.
--delete-email::
Delete an email from this user's account if it exists.
If the email provided is 'ALL', all associated emails are
deleted from this account.
May be supplied more than once to remove multiple emails
from an account in a single command execution.
--preferred-email::
Sets the preferred email address for the user's account.
The email address must already have been registered
with the user's account before it can be set.
May be supplied with the delete-email option as long as
the emails are not the same.
--add-ssh-key::
Content of the public SSH key to add to the account's
keyring. If `-` the key is read from stdin, rather than
from the command line.
May be supplied more than once to add multiple SSH keys
in a single command execution.
--delete-ssh-key::
Content of the public SSH key to remove from the account's
keyring or the comment associated with this key.
If `-` the key is read from stdin, rather than from the
command line. If the key provided is 'ALL', all
associated SSH keys are removed from this account.
May be supplied more than once to delete multiple SSH
keys in a single command execution.
--generate-http-password::
Generate a new random HTTP password for the user account
similar to the web ui. The password will be output to the
user on success with a line: `New password: <PASSWORD>`.
--http-password::
Set the HTTP password for the user account.
--clear-http-password::
Clear the HTTP password for the user account.
== EXAMPLES
Add an email and SSH key to `watcher`'s account:
----
$ cat ~/.ssh/id_watcher.pub | ssh -p 29418 review.example.com gerrit set-account --add-ssh-key - --add-email mail@example.com watcher
----
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------