Merge branch 'add/git-protocol-v2-docs' into 'master'

Add Git protocol v2 docs

See merge request gitlab-org/gitlab-ce!22227

2 files changed, 98 insertions, 0 deletions

diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md
new file mode 100644
index 00000000000..6b82771baf9
--- /dev/null
+++ b/doc/administration/git_protocol.md
@@ -0,0 +1,97 @@
+---
+description: "Set and configure Git protocol v2"
+---
+
+# Configuring Git Protocol v2
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/46555) in GitLab 11.4.
+
+---
+
+Git protocol v2 improves the v1 wire protocol in several ways and is
+enabled by default in GitLab for HTTP requests. In order to enable SSH,
+further configuration is needed by the administrator.
+
+More details about the new features and improvements are available in
+the [Google Open Source Blog](https://opensource.googleblog.com/2018/05/introducing-git-protocol-version-2.html)
+and the [protocol documentation](https://github.com/git/git/blob/master/Documentation/technical/protocol-v2.txt).
+
+## Requirements
+
+From the client side, `git` `v2.18.0` or newer must be installed.
+
+From the server side, if we want to configure SSH we need to set the `sshd`
+server to accept the `GIT_PROTOCOL` environment,
+
+```
+# /etc/ssh/sshd_config
+AcceptEnv GIT_PROTOCOL
+```
+
+Once configured, restart the SSH daemon. In Ubuntu, run:
+
+```sh
+sudo service ssh restart
+```
+
+## Instructions
+
+In order to use the new protocol, clients need to either pass the configuration
+`-c protocol.version=2` to the git command, or set it globally:
+
+```sh
+git config --global protocol.version 2
+```
+
+### HTTP connections
+
+Verify Git v2 is used by the client:
+
+```sh
+GIT_TRACE_CURL=1 git -c protocol.version=2 ls-remote https://your-gitlab-instance.com/group/repo.git 2>&1 | grep Git-Protocol
+```
+
+You should see that the `Git-Protocol` header is sent:
+
+```
+16:29:44.577888 http.c:657              => Send header: Git-Protocol: version=2
+```
+
+Verify Git v2 is used by the server:
+
+```sh
+GIT_TRACE_PACKET=1 git -c protocol.version=2 ls-remote https://your-gitlab-instance.com/group/repo.git 2>&1 | head
+```
+
+Example response using Git protocol v2:
+
+```sh
+$ GIT_TRACE_PACKET=1 git -c protocol.version=2 ls-remote https://your-gitlab-instance.com/group/repo.git 2>&1 | head
+10:42:50.574485 pkt-line.c:80           packet:          git< # service=git-upload-pack
+10:42:50.574653 pkt-line.c:80           packet:          git< 0000
+10:42:50.574673 pkt-line.c:80           packet:          git< version 2
+10:42:50.574679 pkt-line.c:80           packet:          git< agent=git/2.18.1
+10:42:50.574684 pkt-line.c:80           packet:          git< ls-refs
+10:42:50.574688 pkt-line.c:80           packet:          git< fetch=shallow
+10:42:50.574693 pkt-line.c:80           packet:          git< server-option
+10:42:50.574697 pkt-line.c:80           packet:          git< 0000
+10:42:50.574817 pkt-line.c:80           packet:          git< version 2
+10:42:50.575308 pkt-line.c:80           packet:          git< agent=git/2.18.1
+```
+
+### SSH Connections
+
+Verify Git v2 is used by the client:
+
+```sh
+GIT_SSH_COMMAND="ssh -v" git -c protocol.version=2 ls-remote ssh://your-gitlab-instance.com:group/repo.git 2>&1 |grep GIT_PROTOCOL
+```
+
+You should see that the `GIT_PROTOCOL` environment variable is sent:
+
+```
+debug1: Sending env GIT_PROTOCOL = version=2
+```
+
+For the server side, you can use the [same examples from HTTP](#http-connections), changing the
+URL to use SSH.
diff --git a/doc/administration/index.md b/doc/administration/index.md
index d713247983b..789d6716eb4 100644
--- a/doc/administration/index.md
+++ b/doc/administration/index.md
@@ -131,6 +131,7 @@ created in snippets, wikis, and repos.
 - [Custom Git hooks](custom_hooks.md): Custom Git hooks (on the filesystem) for when webhooks aren't enough.
 - [Git LFS configuration](../workflow/lfs/lfs_administration.md): Learn how to configure LFS for GitLab.
 - [Housekeeping](housekeeping.md): Keep your Git repositories tidy and fast.
+- [Configuring Git Protocol v2](git_protocol.md): Git protocol version 2 support.
 
 ## Monitoring GitLab