From a8b940fa586d7b214ee36194cf5413e75f2e208f Mon Sep 17 00:00:00 2001
From: James Lopez <james@gitlab.com>
Date: Wed, 17 Oct 2018 11:52:10 +0000
Subject: Add Git protocol v2 docs

---
 doc/administration/git_protocol.md | 97 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 doc/administration/git_protocol.md

(limited to 'doc/administration/git_protocol.md')

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.
-- 
cgit v1.2.3