Merge branch 'stable-2.14'

* stable-2.14: Documentation: Also consider the use of kerberos authentication over SSH Documentation: add REBASE_ALWAYS as submit type option where omitted Documentation: improve Verified label configuation section Change-Id: Ic10c5cb06800ea9889d48c8d224ead60cfc1e2eb
2017-08-28 10:10:52 +09:00
parent bf634810a7 dc4f8d1723
commit 63a061f00d
19 changed files with 88 additions and 43 deletions
--- a/Documentation/cmd-apropos.txt
+++ b/Documentation/cmd-apropos.txt
@@ -15,7 +15,7 @@ Queries the documentation index and returns results with the title and URL
 from the matched documents.

 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.

 == SCRIPTING
 This command is intended to be used in scripts.
--- a/Documentation/cmd-create-project.txt
+++ b/Documentation/cmd-create-project.txt
@@ -102,6 +102,7 @@ Description values containing spaces should be quoted in single quotes
 * FAST_FORWARD_ONLY: produces a strictly linear history.
 * MERGE_IF_NECESSARY: create a merge commit when required.
 * REBASE_IF_NECESSARY: rebase the commit when required.
+* REBASE_ALWAYS: always rebase the commit including dependencies.
 * MERGE_ALWAYS: always create a merge commit.
 * CHERRY_PICK: always cherry-pick the commit.

--- a/Documentation/cmd-ls-groups.txt
+++ b/Documentation/cmd-ls-groups.txt
@@ -23,7 +23,7 @@ If the caller is a member of the privileged 'Administrators' group,
 all groups are listed.

 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.

 == SCRIPTING
 This command is intended to be used in scripts.
--- a/Documentation/cmd-ls-members.txt
+++ b/Documentation/cmd-ls-members.txt
@@ -16,7 +16,7 @@ group is visible to the user. The users' id, username, full name and email are
 shown tab-separated.

 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.

 == SCRIPTING
 This command is intended to be used in scripts. Output is either an error
--- a/Documentation/cmd-ls-projects.txt
+++ b/Documentation/cmd-ls-projects.txt
@@ -25,7 +25,7 @@ If the caller is a member of the privileged 'Administrators'
 group, all projects are listed.

 == ACCESS
-Any user who has configured an SSH key, or by an user over HTTP.
+Any user who has SSH access to Gerrit.

 == SCRIPTING
 This command is intended to be used in scripts.
--- a/Documentation/cmd-query.txt
+++ b/Documentation/cmd-query.txt
@@ -108,7 +108,7 @@ limit:<n>::
 	will be used to cut the result set.

 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.

 == SCRIPTING
 This command is intended to be used in scripts.
--- a/Documentation/cmd-receive-pack.txt
+++ b/Documentation/cmd-receive-pack.txt
@@ -37,7 +37,7 @@ to 'git push', which will relay them automatically.
 	Deprecated, use `refs/for/branch%cc=address` instead.

 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.

 == EXAMPLES

--- a/Documentation/cmd-review.txt
+++ b/Documentation/cmd-review.txt
@@ -150,7 +150,7 @@ branch.
  invocations of the SSH command are required.

 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.

 == SCRIPTING
 This command is intended to be used in scripts.
--- a/Documentation/cmd-set-members.txt
+++ b/Documentation/cmd-set-members.txt
@@ -49,7 +49,7 @@ The `set-members` command is processing the options in the following
 order: `--remove`, `--exclude`, `--add`, `--include`

 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.

 == SCRIPTING
 This command is intended to be used in scripts.
--- a/Documentation/cmd-set-project.txt
+++ b/Documentation/cmd-set-project.txt
@@ -53,6 +53,7 @@ Description values containing spaces should be quoted in single quotes
 * FAST_FORWARD_ONLY: produces a strictly linear history.
 * MERGE_IF_NECESSARY: create a merge commit when required.
 * REBASE_IF_NECESSARY: rebase the commit when required.
+* REBASE_ALWAYS: always rebase the commit including dependencies.
 * MERGE_ALWAYS: always create a merge commit.
 * CHERRY_PICK: always cherry-pick the commit.

--- a/Documentation/cmd-set-reviewers.txt
+++ b/Documentation/cmd-set-reviewers.txt
@@ -47,7 +47,7 @@ API.
 	Display site-specific usage information

 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.

 == SCRIPTING
 This command is intended to be used in scripts.
--- a/Documentation/cmd-version.txt
+++ b/Documentation/cmd-version.txt
@@ -26,7 +26,7 @@ describe` documentation for details on how `<tagname>` is chosen and how
 `<n>` is computed.

 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.

 == SCRIPTING
 This command is intended to be used in scripts.
--- a/Documentation/config-gerrit.txt
+++ b/Documentation/config-gerrit.txt
@@ -3650,7 +3650,9 @@ Path must be absolute.
 +
 The default submit type for newly created projects. Supported values
 are `MERGE_IF_NECESSARY`, `FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`,
-`MERGE_ALWAYS` and `CHERRY_PICK`.
+`REBASE_ALWAYS`, `MERGE_ALWAYS` and `CHERRY_PICK`.
+
+For more details see link:project-configuration.html#submit_type[Submit Types].
 +
 By default, `MERGE_IF_NECESSARY`.

--- a/Documentation/config-labels.txt
+++ b/Documentation/config-labels.txt
@@ -11,11 +11,10 @@ groups within projects, enabling functionality for that group's members.
 [[label_Code-Review]]
 == Label: Code-Review

-The code review label is the second of two default labels that is
-configured upon the creation of a Gerrit instance.  It may have any
-meaning the project desires.  It was originally invented by the Android
-Open Source Project to mean 'I read the code and it seems reasonably
-correct'.
+The Code-Review label is configured upon the creation of a Gerrit
+instance.  It may have any meaning the project desires.  It was
+originally invented by the Android Open Source Project to mean
+'I read the code and it seems reasonably correct'.

 The range of values is:

@@ -87,8 +86,10 @@ The Verified label was originally invented by the Android Open Source
 Project to mean 'compiles, passes basic unit tests'.  Some CI tools
 expect to use the Verified label to vote on a change after running.

-Administrators can install the Verified label by adding the following
-text to `project.config`:
+During site initialization the administrator may have chosen to
+configure the default Verified label for all projects.  In case it is
+desired to configure it at a later time, administrators can do this by
+adding the following to `project.config` in `All-Projects`:

 ----
  [label "Verified"]
@@ -96,6 +97,7 @@ text to `project.config`:
      value = -1 Fails
      value =  0 No score
      value = +1 Verified
+      copyAllScoresIfNoCodeChange = true
 ----

 The range of values is:
@@ -315,8 +317,8 @@ set and the same code delta as the previous patch set. This means only
 the commit message is different. This can be used to enable sticky
 approvals on labels that only depend on the code, reducing turn-around
 if only the commit message is changed prior to submitting a change.
-For the Verified label that is installed by the link:pgm-init.html[init]
-site program this is enabled by default.
+For the Verified label that is optionally installed by the
+link:pgm-init.html[init] site program this is enabled by default.

 Defaults to false.

--- a/Documentation/error-permission-denied.txt
+++ b/Documentation/error-permission-denied.txt
@@ -3,15 +3,20 @@
 With this error message an SSH command to Gerrit is rejected if the
 SSH authentication is not successful.

-The link:http://en.wikipedia.org/wiki/Secure_Shell[SSH] protocol uses link:http://en.wikipedia.org/wiki/Public-key_cryptography[Public-key Cryptography] for authentication.
-This means for a successful SSH authentication you need your private
-SSH key and the corresponding public SSH key must be known to Gerrit.
+The link:http://en.wikipedia.org/wiki/Secure_Shell[SSH] protocol can use
+link:http://en.wikipedia.org/wiki/Public-key_cryptography[Public-key Cryptography]
+for authentication.
+In general configurations, Gerrit will authenticate you by the public keys
+known to you. Optionally, it can be configured by the administrator to allow
+for link:config-gerrit.html#sshd.kerberosKeytab[kerberos] authentication
+instead.

-If you are facing this problem, do the following:
+In any case, verify that you are using the correct username for the SSH command
+and that it is typed correctly (case sensitive). You can look up your username
+in the Gerrit Web UI under 'Settings' -> 'Profile'.
+
+If you are facing this problem and using an SSH keypair, do the following:

-. Verify that you are using the correct username for the SSH command
-  and that it is typed correctly (case sensitive). You can look up
-  your username in the Gerrit Web UI under 'Settings' -> 'Profile'.
 . Verify that you have uploaded your public SSH key for your Gerrit
  account. To do this go in the Gerrit Web UI to 'Settings' ->
  'SSH Public Keys' and check that your public SSH key is there. If
@@ -21,6 +26,19 @@ If you are facing this problem, do the following:
  described below. From the trace you should see which private SSH
  key is used.

+Debugging kerberos issues can be quite hard given the complexity of the
+protocol. In case you are using kerberos authentication, do the following:
+
+. Verify that you have acquired a valid initial ticket. On a Linux machine, you
+  can acquire one using the `kinit` command. List all your tickets using the
+  `klist` command. It should list all principals for which you have acquired a
+  ticket and include a principal name corresponding to your Gerrit server, for
+  example `HOST/gerrit.mydomain.tld@MYDOMAIN.TLD`.
+  Note that tickets can expire and require you to re-run `kinit` periodically.
+. Verify that your SSH client is using kerberos authentication. For OpenSSH
+  clients this can be controlled using the `GSSAPIAuthentication` setting.
+  For more information see
+  link:user-upload.html#configure_ssh_kerberos[SSH kerberos configuration].

 == Test SSH authentication

--- a/Documentation/intro-user.txt
+++ b/Documentation/intro-user.txt
@@ -56,8 +56,8 @@ For git operations Gerrit supports the link:user-upload.html#ssh[SSH]
 and the link:user-upload.html#http[HTTP/HTTPS] protocols.

 [NOTE]
-To use SSH you must link:user-upload.html#configure_ssh[generate an SSH
-key pair and upload the public SSH key to Gerrit].
+To use SSH you may need to link:user-upload.html#ssh[configure your SSH public
+key in your `Settings`].

 [[code-review]]
 == Code Review Workflow
--- a/Documentation/rest-api-changes.txt
+++ b/Documentation/rest-api-changes.txt
@@ -6418,7 +6418,7 @@ change.
 |Field Name      ||Description
 |`submit_type`   ||
 Submit type used for this change, can be `MERGE_IF_NECESSARY`,
-`FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `MERGE_ALWAYS` or
+`FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `REBASE_ALWAYS`, `MERGE_ALWAYS` or
 `CHERRY_PICK`.
 |`strategy`     |optional|
 The strategy of the merge, can be `recursive`, `resolve`,
--- a/Documentation/rest-api-projects.txt
+++ b/Documentation/rest-api-projects.txt
@@ -2582,7 +2582,7 @@ limit] of this project as a link:#max-object-size-limit-info[
 MaxObjectSizeLimitInfo] entity.
 |`submit_type`               ||
 The default submit type of the project, can be `MERGE_IF_NECESSARY`,
-`FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `MERGE_ALWAYS` or
+`FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `REBASE_ALWAYS`, `MERGE_ALWAYS` or
 `CHERRY_PICK`.
 |`match_author_to_committer_date` |optional|
 link:#inherited-boolean-info[InheritedBooleanInfo] that indicates whether
@@ -2660,7 +2660,7 @@ If set to `0`, the max object size limit is removed. +
 If not set, this setting is not updated.
 |`submit_type`                             |optional|
 The default submit type of the project, can be `MERGE_IF_NECESSARY`,
-`FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `MERGE_ALWAYS` or
+`FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `REBASE_ALWAYS`, `MERGE_ALWAYS` or
 `CHERRY_PICK`. +
 If not set, the submit type is not updated.
 |`state`                                   |optional|
@@ -2966,8 +2966,8 @@ Whether a permission-only project should be created.
 Whether an empty initial commit should be created.
 |`submit_type`               |optional|
 The submit type that should be set for the project
-(`MERGE_IF_NECESSARY`, `REBASE_IF_NECESSARY`, `FAST_FORWARD_ONLY`,
-`MERGE_ALWAYS`, `CHERRY_PICK`). +
+(`MERGE_IF_NECESSARY`, `REBASE_IF_NECESSARY`, `REBASE_ALWAYS`,
+`FAST_FORWARD_ONLY`, `MERGE_ALWAYS`, `CHERRY_PICK`). +
 If not set, `MERGE_IF_NECESSARY` is set as submit type unless
 link:config-gerrit.html#repository.name.defaultSubmitType[
 repository.<name>.defaultSubmitType] is set to a different value.
--- a/Documentation/user-upload.txt
+++ b/Documentation/user-upload.txt
@@ -9,8 +9,8 @@ Gerrit supports three methods of uploading changes:
 All three methods rely on authentication, which must first be configured
 by the uploading user.

-Gerrit supports two methods of authenticating the uploading user.  SSH
-public key, and HTTP/HTTPS.
+Gerrit supports two protocols for uploading changes; SSH and HTTP/HTTPS. These
+may not all be available for you, depending on the server configuration.

 [[http]]
 == HTTP/HTTPS
@@ -41,13 +41,15 @@ not configured, the password can be obtained by clicking on `Generate Password`.
 [[ssh]]
 == SSH

-Each user uploading changes to Gerrit must configure one or more SSH
-public keys.  The per-user SSH key list can be accessed over the web
-within Gerrit by `Settings`, and then accessing the `SSH Public Keys`
-tab.
+To upload changes over SSH, Gerrit supports two forms of authentication: a
+user's public key or kerberos.

-[[configure_ssh]]
-=== Configuration
+Unless your Gerrit instance is configured to support
+link:config-gerrit.html#sshd.kerberosKeytab[kerberos] in your domain, only
+public key authentication can be used.
+
+[[configure_ssh_public_keys]]
+=== Public keys

 To register a new SSH key for use with Gerrit, paste the contents of
 your `id_rsa.pub` or `id_dsa.pub` file into the text box and click
@@ -79,10 +81,29 @@ key's passphrase.  Consult `man ssh-agent`, or your SSH client's
 documentation, for more details on configuration of the agent
 process and how to add the private key.

+[[configure_ssh_kerberos]]
+=== Kerberos
+
+A kerberos-enabled server configuration allows for zero configuration in an
+existing single-sign-on environment.
+
+Your SSH client should be configured to enable kerberos authentication. For
+OpenSSH clients, this is controlled by the option `GSSAPIAuthentication` which
+should be set to `yes`.
+
+Some Linux distributions have packaged OpenSSH to enable this by default (e.g.
+Debian, Ubuntu). If this is not the case for your distribution, enable it for
+Gerrit with this entry in your local SSH configuration:
+
+----
+Host gerrit.mydomain.tld
+    GSSAPIAuthentication yes
+----
+
 [[test_ssh]]
 === Testing Connections

-To verify your SSH key is working correctly, try using an SSH client
+To verify your SSH authentication is working correctly, try using an SSH client
 to connect to Gerrit's SSHD port.  By default Gerrit runs on
 port 29418, using the same hostname as the web server: