{"thread":{"id":"56442","subject":"[PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","startedAt":"2021-09-04T15:18:00Z","lastAt":"2021-09-10T22:08:56Z","messageCount":20,"participants":["Konstantin Ryabitsev","Jeff King","Junio C Hamano","Eric Wong","Philippe Blain"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"434697","messageId":"20210904151721.445117-1-konstantin@linuxfoundation.org","threadId":"56442","inReplyTo":null,"subject":"[PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Konstantin Ryabitsev","fromEmail":"konstantin@linuxfoundation.org","sentAt":"2021-09-04T15:17:21Z","receivedAt":"2021-09-04T15:18:00Z","isPatch":true,"sender":{"key":"konstantin@linuxfoundation.org","avatar":"https://gravatar.com/avatar/7cb8827c6de56e1bd2dea16508c6708aa43feed3bf3813bcdacecdf96ceadd79?d=mp&s=160"},"body":"For the server-side to properly respond to v2 protocol requests, the\nwebserver must set the GIT_PROTOCOL environment variable to the value of\nthe Git-Protocol: request header.\n\nLink: https://lore.kernel.org/git/YTNtVJy6sCfQ7T3L@coredump.intra.peff.net/\nReported-by: Philippe Blain <levraiphilippeblain@gmail.com>\nSigned-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>\n---\n Documentation/technical/protocol-v2.txt | 15 +++++++++++++++\n 1 file changed, 15 insertions(+)\n\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt\nindex 1040d85319..7a0e97cc8d 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/technical/protocol-v2.txt\n@@ -81,6 +81,21 @@ A v2 server would reply:\n Subsequent requests are then made directly to the service\n `$GIT_URL/git-upload-pack`. (This works the same for git-receive-pack).\n \n+The web server handling the requests must properly set the GIT_PROTOCOL\n+environment variable when it finds `Git-Protocol` in the request headers.\n+\n+Apache example:\n+\n+   SetEnvIf Git-Protocol \".*\" GIT_PROTOCOL=$0\n+\n+Nginx + uwsgi example:\n+\n+   uwsgi_param GIT_PROTOCOL $http_git_protocol;\n+\n+Nginx + fastcgi example:\n+\n+   fastcgi_param GIT_PROTOCOL $http_git_protocol;\n+\n Capability Advertisement\n ------------------------\n \n\nbase-commit: e0a2f5cbc585657e757385ad918f167f519cfb96\n-- \n2.31.1\n\n"},{"id":"434698","messageId":"YTOW352xtsbvJcKy@coredump.intra.peff.net","threadId":"56442","inReplyTo":"20210904151721.445117-1-konstantin@linuxfoundation.org","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-09-04T15:55:11Z","receivedAt":"2021-09-04T15:55:19Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Sep 04, 2021 at 11:17:21AM -0400, Konstantin Ryabitsev wrote:\n\n> For the server-side to properly respond to v2 protocol requests, the\n> webserver must set the GIT_PROTOCOL environment variable to the value of\n> the Git-Protocol: request header.\n\nThanks for assembling these examples.\n\nI don't mind having these in the technical documentation, but I think\nmost users won't find them there (nor would they even know they need to\nbe looking). Maybe the manpage for git-http-backend would be a better\nspot. We can mention v2 in the \"description\" section, and then there's\nsome example config near the end that could include it.\n\nUnfortunately there isn't any nginx example config there at all yet. If\nyou have kernel.org config you could share, that would be great. But\neven starting with just the \"here's how you do v2\" part would be\nwelcome.\n\n-Peff\n"},{"id":"434935","messageId":"xmqqeea09k8m.fsf@gitster.g","threadId":"56442","inReplyTo":"YTOW352xtsbvJcKy@coredump.intra.peff.net","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-07T20:57:45Z","receivedAt":"2021-09-07T20:57:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> On Sat, Sep 04, 2021 at 11:17:21AM -0400, Konstantin Ryabitsev wrote:\n>\n>> For the server-side to properly respond to v2 protocol requests, the\n>> webserver must set the GIT_PROTOCOL environment variable to the value of\n>> the Git-Protocol: request header.\n>\n> Thanks for assembling these examples.\n>\n> I don't mind having these in the technical documentation, but I think\n> most users won't find them there (nor would they even know they need to\n> be looking). Maybe the manpage for git-http-backend would be a better\n> spot. We can mention v2 in the \"description\" section, and then there's\n> some example config near the end that could include it.\n>\n> Unfortunately there isn't any nginx example config there at all yet. If\n> you have kernel.org config you could share, that would be great. But\n> even starting with just the \"here's how you do v2\" part would be\n> welcome.\n\nTrue, true.\n\nIn the meantime, I'll queue this as-is.\n\nThanks.\n"},{"id":"434949","messageId":"20210907211128.mauwgxupbredgx7w@meerkat.local","threadId":"56442","inReplyTo":"YTOW352xtsbvJcKy@coredump.intra.peff.net","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Konstantin Ryabitsev","fromEmail":"konstantin@linuxfoundation.org","sentAt":"2021-09-07T21:11:28Z","receivedAt":"2021-09-07T21:11:33Z","isPatch":true,"sender":{"key":"konstantin@linuxfoundation.org","avatar":"https://gravatar.com/avatar/7cb8827c6de56e1bd2dea16508c6708aa43feed3bf3813bcdacecdf96ceadd79?d=mp&s=160"},"body":"On Sat, Sep 04, 2021 at 11:55:11AM -0400, Jeff King wrote:\n> Unfortunately there isn't any nginx example config there at all yet. If\n> you have kernel.org config you could share, that would be great. But\n> even starting with just the \"here's how you do v2\" part would be\n> welcome.\n\nI'll see if I can come up with something to put into\nDocumentation/git-http-backend.txt, but I can't right away -- hopefully in\nearly October once a bunch of conferences are over.\n\nBest regards,\n-K\n"},{"id":"435066","messageId":"YTiVDo4m5B5RcfCg@coredump.intra.peff.net","threadId":"56442","inReplyTo":"20210907211128.mauwgxupbredgx7w@meerkat.local","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-09-08T10:48:46Z","receivedAt":"2021-09-08T10:48:49Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Sep 07, 2021 at 05:11:28PM -0400, Konstantin Ryabitsev wrote:\n\n> On Sat, Sep 04, 2021 at 11:55:11AM -0400, Jeff King wrote:\n> > Unfortunately there isn't any nginx example config there at all yet. If\n> > you have kernel.org config you could share, that would be great. But\n> > even starting with just the \"here's how you do v2\" part would be\n> > welcome.\n> \n> I'll see if I can come up with something to put into\n> Documentation/git-http-backend.txt, but I can't right away -- hopefully in\n> early October once a bunch of conferences are over.\n\nIt would be great if you could add nginx examples at some point. But in\nthe meantime, we can do this much easier patch to make sure we don't\nforget about mentioning the protocol bits.\n\n-- >8 --\nSubject: [PATCH] docs/http-backend: mention v2 protocol\n\nThere's a little bit of configuration needed at the webserver level in\norder to get the client's v2 protocol probes to Git. But when we\nintroduced the v2 protocol, we never documented these explicitly.\n\nCommit 9181c4a9ac (Docs: web server must setenv GIT_PROTOCOL for v2,\n2021-09-04) now mentions them in the v2 docs themselves, but users\nconfiguring git-over-http for the first time are more likely to be\nlooking in the git-http-backend manpage. Let's make sure we mention it\nthere, too, and give some examples.\n\nBoth of the included examples here have been tested to work. The one for\nlighttpd is a little less direct than I'd like, but I couldn't find a\nway to directly set an environment variable to the value of a request\nheader. From my reading of the documentation, lighttpd will set\nHTTP_GIT_PROTOCOL automatically, but git-http-backend looks only at\nGIT_PROTOCOL. Arguably http-backend should do this translation itself.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Documentation/git-http-backend.txt | 13 ++++++++++++-\n 1 file changed, 12 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt\nindex 558966aa83..4797bc8aec 100644\n--- a/Documentation/git-http-backend.txt\n+++ b/Documentation/git-http-backend.txt\n@@ -16,7 +16,9 @@ A simple CGI program to serve the contents of a Git repository to Git\n clients accessing the repository over http:// and https:// protocols.\n The program supports clients fetching using both the smart HTTP protocol\n and the backwards-compatible dumb HTTP protocol, as well as clients\n-pushing using the smart HTTP protocol.\n+pushing using the smart HTTP protocol. It also supports Git's\n+more-efficient \"v2\" protocol if properly configured; see the\n+discussion of `GIT_PROTOCOL` in the ENVIRONMENT section below.\n \n It verifies that the directory has the magic file\n \"git-daemon-export-ok\", and it will refuse to export any Git directory\n@@ -76,6 +78,7 @@ Apache 2.x::\n ----------------------------------------------------------------\n SetEnv GIT_PROJECT_ROOT /var/www/git\n SetEnv GIT_HTTP_EXPORT_ALL\n+SetEnvIf Git-Protocol \".*\" GIT_PROTOCOL=$0\n ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/\n ----------------------------------------------------------------\n +\n@@ -203,6 +206,9 @@ $HTTP[\"url\"] =~ \"^/git\" {\n \t\t\"GIT_PROJECT_ROOT\" => \"/var/www/git\",\n \t\t\"GIT_HTTP_EXPORT_ALL\" => \"\"\n \t)\n+\t$REQUEST_HEADER[\"Git-Protocol\"] == \"version=2\" {\n+\t\tsetenv.add-environment += (\"GIT_PROTOCOL\" => \"version=2\")\n+\t}\n }\n ----------------------------------------------------------------\n +\n@@ -264,6 +270,11 @@ a repository with an extremely large number of refs.  The value can be\n specified with a unit (e.g., `100M` for 100 megabytes). The default is\n 10 megabytes.\n \n+Clients may probe for optional protocol capabilities using the\n+`Git-Protocol` HTTP header. In order to support these, the webserver\n+must be configured to pass the contents of that header to\n+`git-http-backend` in the `GIT_PROTOCOL` environment variable.\n+\n The backend process sets GIT_COMMITTER_NAME to '$REMOTE_USER' and\n GIT_COMMITTER_EMAIL to '$\\{REMOTE_USER}@http.$\\{REMOTE_ADDR\\}',\n ensuring that any reflogs created by 'git-receive-pack' contain some\n-- \n2.33.0.621.ga797e945d8\n\n"},{"id":"435067","messageId":"YTiXEEEs36NCEr9S@coredump.intra.peff.net","threadId":"56442","inReplyTo":"YTiVDo4m5B5RcfCg@coredump.intra.peff.net","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-09-08T10:57:20Z","receivedAt":"2021-09-08T10:57:29Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Sep 08, 2021 at 06:48:47AM -0400, Jeff King wrote:\n\n> Both of the included examples here have been tested to work. The one for\n> lighttpd is a little less direct than I'd like, but I couldn't find a\n> way to directly set an environment variable to the value of a request\n> header. From my reading of the documentation, lighttpd will set\n> HTTP_GIT_PROTOCOL automatically, but git-http-backend looks only at\n> GIT_PROTOCOL. Arguably http-backend should do this translation itself.\n\nSo having discovered this, I kind of wonder if these documentation\npatches are barking up the wrong tree. There is no reason we would not\nwant v2 to work out of the box (after all, it does for git://).\n\nThe patch below does that (and could replace both my and Konstantin's\ndocumentation patches).\n\nThis also makes me wonder if we should be documenting the use of\nAcceptEnv for ssh (which sadly I don't think we can make work\nout-of-the-box).\n\n-- >8 --\nSubject: [PATCH] http-backend: handle HTTP_GIT_PROTOCOL CGI variable\n\nWhen a client requests the v2 protocol over HTTP, they set the\nGit-Protocol header. Webservers will generaly make that available to our\nCGI as HTTP_GIT_PROTOCOL in the environment. However, that's not\nsufficient for upload-pack, etc, to respect it; they look in\nGIT_PROTOCOL (without the HTTP_ prefix).\n\nEither the webserver or the CGI is responsible for relaying that HTTP\nheader into the GIT_PROTOCOL variable. Traditionally, our tests have\nconfigured the webserver to do so, but that's a burden on the server\nadmin. We can make this work out of the box by having the http-backend\nCGI copy the contents.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n http-backend.c          | 4 ++++\n t/lib-httpd/apache.conf | 2 --\n 2 files changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/http-backend.c b/http-backend.c\nindex b329bf63f0..2f4b4c11de 100644\n--- a/http-backend.c\n+++ b/http-backend.c\n@@ -739,6 +739,7 @@ static int bad_request(struct strbuf *hdr, const struct service_cmd *c)\n int cmd_main(int argc, const char **argv)\n {\n \tchar *method = getenv(\"REQUEST_METHOD\");\n+\tconst char *proto_header;\n \tchar *dir;\n \tstruct service_cmd *cmd = NULL;\n \tchar *cmd_arg = NULL;\n@@ -789,6 +790,9 @@ int cmd_main(int argc, const char **argv)\n \thttp_config();\n \tmax_request_buffer = git_env_ulong(\"GIT_HTTP_MAX_REQUEST_BUFFER\",\n \t\t\t\t\t   max_request_buffer);\n+\tproto_header = getenv(\"HTTP_GIT_PROTOCOL\");\n+\tif (proto_header)\n+\t\tsetenv(GIT_PROTOCOL_ENVIRONMENT, proto_header, 1);\n \n \tcmd->imp(&hdr, cmd_arg);\n \treturn 0;\ndiff --git a/t/lib-httpd/apache.conf b/t/lib-httpd/apache.conf\nindex afa91e38b0..71761e3299 100644\n--- a/t/lib-httpd/apache.conf\n+++ b/t/lib-httpd/apache.conf\n@@ -81,8 +81,6 @@ PassEnv GIT_TRACE\n PassEnv GIT_CONFIG_NOSYSTEM\n PassEnv GIT_TEST_SIDEBAND_ALL\n \n-SetEnvIf Git-Protocol \".*\" GIT_PROTOCOL=$0\n-\n Alias /dumb/ www/\n Alias /auth/dumb/ www/auth/dumb/\n \n-- \n2.33.0.621.ga797e945d8\n\n"},{"id":"435122","messageId":"20210908165057.GA14162@dcvr","threadId":"56442","inReplyTo":"YTiXEEEs36NCEr9S@coredump.intra.peff.net","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Eric Wong","fromEmail":"e@80x24.org","sentAt":"2021-09-08T16:50:57Z","receivedAt":"2021-09-08T16:51:00Z","isPatch":true,"sender":{"key":"e@80x24.org","avatar":null},"body":"Jeff King <peff@peff.net> wrote:\n> On Wed, Sep 08, 2021 at 06:48:47AM -0400, Jeff King wrote:\n> \n> > Both of the included examples here have been tested to work. The one for\n> > lighttpd is a little less direct than I'd like, but I couldn't find a\n> > way to directly set an environment variable to the value of a request\n> > header. From my reading of the documentation, lighttpd will set\n> > HTTP_GIT_PROTOCOL automatically, but git-http-backend looks only at\n> > GIT_PROTOCOL. Arguably http-backend should do this translation itself.\n> \n> So having discovered this, I kind of wonder if these documentation\n> patches are barking up the wrong tree. There is no reason we would not\n> want v2 to work out of the box (after all, it does for git://).\n\nAgreed.\n\n> The patch below does that (and could replace both my and Konstantin's\n> documentation patches).\n\n<snip>\n\n> -- >8 --\n> Subject: [PATCH] http-backend: handle HTTP_GIT_PROTOCOL CGI variable\n> \n> When a client requests the v2 protocol over HTTP, they set the\n> Git-Protocol header. Webservers will generaly make that available to our\n\n\"generally\"\n\n> CGI as HTTP_GIT_PROTOCOL in the environment. However, that's not\n> sufficient for upload-pack, etc, to respect it; they look in\n> GIT_PROTOCOL (without the HTTP_ prefix).\n> \n> Either the webserver or the CGI is responsible for relaying that HTTP\n> header into the GIT_PROTOCOL variable. Traditionally, our tests have\n> configured the webserver to do so, but that's a burden on the server\n> admin. We can make this work out of the box by having the http-backend\n> CGI copy the contents.\n\nAgreed.  I've completely overlooked GIT_PROTOCOL support, so far...\n\nThis seems to be the right thing to do; I think I'll add support\nfor it when I spawn git-http-backend in something I work on.\n(I also don't currently pass all HTTP headers in env when\nspawning CGI, maybe I should *shrug*)\n"},{"id":"435281","messageId":"xmqqee9x1wvh.fsf@gitster.g","threadId":"56442","inReplyTo":"YTiXEEEs36NCEr9S@coredump.intra.peff.net","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-09T17:28:50Z","receivedAt":"2021-09-09T17:28:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> On Wed, Sep 08, 2021 at 06:48:47AM -0400, Jeff King wrote:\n>\n>> Both of the included examples here have been tested to work. The one for\n>> lighttpd is a little less direct than I'd like, but I couldn't find a\n>> way to directly set an environment variable to the value of a request\n>> header. From my reading of the documentation, lighttpd will set\n>> HTTP_GIT_PROTOCOL automatically, but git-http-backend looks only at\n>> GIT_PROTOCOL. Arguably http-backend should do this translation itself.\n\nNice.\n\nThese headers get HTTP_* prefixed as a security measure when servers\nexpose them to their configuration mechanisms because these names\nare attacker controlled.  I had a flawed mental model in which the\nservers' configuration controls which one of these resulting HTTP_*\nheaders are passed to CGI and externals selectively, but if servers\npass all HTTP_* environment variables to CGI and externals without\nany filtering, the patch you gave here is the most logical solution.\n\nWill queue.\n\n> -- >8 --\n> Subject: [PATCH] http-backend: handle HTTP_GIT_PROTOCOL CGI variable\n>\n> When a client requests the v2 protocol over HTTP, they set the\n> Git-Protocol header. Webservers will generaly make that available to our\n> CGI as HTTP_GIT_PROTOCOL in the environment. However, that's not\n> sufficient for upload-pack, etc, to respect it; they look in\n> GIT_PROTOCOL (without the HTTP_ prefix).\n>\n> Either the webserver or the CGI is responsible for relaying that HTTP\n> header into the GIT_PROTOCOL variable. Traditionally, our tests have\n> configured the webserver to do so, but that's a burden on the server\n> admin. We can make this work out of the box by having the http-backend\n> CGI copy the contents.\n>\n> Signed-off-by: Jeff King <peff@peff.net>\n> ---\n>  http-backend.c          | 4 ++++\n>  t/lib-httpd/apache.conf | 2 --\n>  2 files changed, 4 insertions(+), 2 deletions(-)\n>\n> diff --git a/http-backend.c b/http-backend.c\n> index b329bf63f0..2f4b4c11de 100644\n> --- a/http-backend.c\n> +++ b/http-backend.c\n> @@ -739,6 +739,7 @@ static int bad_request(struct strbuf *hdr, const struct service_cmd *c)\n>  int cmd_main(int argc, const char **argv)\n>  {\n>  \tchar *method = getenv(\"REQUEST_METHOD\");\n> +\tconst char *proto_header;\n>  \tchar *dir;\n>  \tstruct service_cmd *cmd = NULL;\n>  \tchar *cmd_arg = NULL;\n> @@ -789,6 +790,9 @@ int cmd_main(int argc, const char **argv)\n>  \thttp_config();\n>  \tmax_request_buffer = git_env_ulong(\"GIT_HTTP_MAX_REQUEST_BUFFER\",\n>  \t\t\t\t\t   max_request_buffer);\n> +\tproto_header = getenv(\"HTTP_GIT_PROTOCOL\");\n> +\tif (proto_header)\n> +\t\tsetenv(GIT_PROTOCOL_ENVIRONMENT, proto_header, 1);\n>  \n>  \tcmd->imp(&hdr, cmd_arg);\n>  \treturn 0;\n> diff --git a/t/lib-httpd/apache.conf b/t/lib-httpd/apache.conf\n> index afa91e38b0..71761e3299 100644\n> --- a/t/lib-httpd/apache.conf\n> +++ b/t/lib-httpd/apache.conf\n> @@ -81,8 +81,6 @@ PassEnv GIT_TRACE\n>  PassEnv GIT_CONFIG_NOSYSTEM\n>  PassEnv GIT_TEST_SIDEBAND_ALL\n>  \n> -SetEnvIf Git-Protocol \".*\" GIT_PROTOCOL=$0\n> -\n>  Alias /dumb/ www/\n>  Alias /auth/dumb/ www/auth/dumb/\n"},{"id":"435282","messageId":"xmqqa6kl1wjs.fsf@gitster.g","threadId":"56442","inReplyTo":"xmqqee9x1wvh.fsf@gitster.g","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-09T17:35:51Z","receivedAt":"2021-09-09T17:35:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n>> @@ -789,6 +790,9 @@ int cmd_main(int argc, const char **argv)\n>>  \thttp_config();\n>>  \tmax_request_buffer = git_env_ulong(\"GIT_HTTP_MAX_REQUEST_BUFFER\",\n>>  \t\t\t\t\t   max_request_buffer);\n>> +\tproto_header = getenv(\"HTTP_GIT_PROTOCOL\");\n>> +\tif (proto_header)\n>> +\t\tsetenv(GIT_PROTOCOL_ENVIRONMENT, proto_header, 1);\n\nSince this overwrites (I noticed the \"1\" at the end), the server\noperator cannot force a particular protocol with their server\nconfiguration, no?\n\nWould a weaker form to use 0 (set if there isn't any, but keep the\nvalue if somebody else already has set it) work OK?  Would that have\na downside?\n"},{"id":"435286","messageId":"64a5aaf1-64af-3599-8520-ff3b55411e2a@gmail.com","threadId":"56442","inReplyTo":"YTiXEEEs36NCEr9S@coredump.intra.peff.net","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2021-09-09T17:50:18Z","receivedAt":"2021-09-09T17:50:22Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Peff,\n\nLe 2021-09-08 à 06:57, Jeff King a écrit :\n> On Wed, Sep 08, 2021 at 06:48:47AM -0400, Jeff King wrote:\n> \n>> Both of the included examples here have been tested to work. The one for\n>> lighttpd is a little less direct than I'd like, but I couldn't find a\n>> way to directly set an environment variable to the value of a request\n>> header. From my reading of the documentation, lighttpd will set\n>> HTTP_GIT_PROTOCOL automatically, but git-http-backend looks only at\n>> GIT_PROTOCOL. Arguably http-backend should do this translation itself.\n> \n> So having discovered this, I kind of wonder if these documentation\n> patches are barking up the wrong tree. There is no reason we would not\n> want v2 to work out of the box (after all, it does for git://).\n> \n> The patch below does that (and could replace both my and Konstantin's\n> documentation patches).\n\nI agree it's nice to make it work out of the box, without the web server\nadmin having to configure anything. But, I'm not sure we should completely\ndrop the documentation patches: your patch will only affect future versions\nof git-http-backend, and users of previous versions will be left without\nany documentation as to how to configure it for protocol v2. So I would think we should\nkeep the documentation patches, maybe with a mention \"this should not be necessary\nin Git 2.34 and later versions\" or something like that (since your\ncommit message mentions that it \"generally\" should work like that depending\non the web servers).\n\n> \n> This also makes me wonder if we should be documenting the use of\n> AcceptEnv for ssh (which sadly I don't think we can make work\n> out-of-the-box).\n\nI think it would be a good idea to document it, yes. FWIW I found out about\nit at https://docs.gitlab.com/ee/administration/git_protocol.html.\n\nCheers,\nPhilippe.\n"},{"id":"435369","messageId":"xmqqilz9ugz2.fsf@gitster.g","threadId":"56442","inReplyTo":"64a5aaf1-64af-3599-8520-ff3b55411e2a@gmail.com","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-10T05:39:29Z","receivedAt":"2021-09-10T05:39:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philippe Blain <levraiphilippeblain@gmail.com> writes:\n\n> I agree it's nice to make it work out of the box, without the web server\n> admin having to configure anything. But, I'm not sure we should completely\n> drop the documentation patches: your patch will only affect future versions\n> of git-http-backend, and users of previous versions will be left without\n> any documentation as to how to configure it for protocol v2. So I would think we should\n> keep the documentation patches, maybe with a mention \"this should not be necessary\n> in Git 2.34 and later versions\" or something like that (since your\n> commit message mentions that it \"generally\" should work like that depending\n> on the web servers).\n\nThanks, exactly my thought on the need for docs.\n"},{"id":"435402","messageId":"YTtECuP2/A6+EI4J@coredump.intra.peff.net","threadId":"56442","inReplyTo":"xmqqa6kl1wjs.fsf@gitster.g","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-09-10T11:39:54Z","receivedAt":"2021-09-10T11:39:57Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Sep 09, 2021 at 10:35:51AM -0700, Junio C Hamano wrote:\n\n> Junio C Hamano <gitster@pobox.com> writes:\n> \n> >> @@ -789,6 +790,9 @@ int cmd_main(int argc, const char **argv)\n> >>  \thttp_config();\n> >>  \tmax_request_buffer = git_env_ulong(\"GIT_HTTP_MAX_REQUEST_BUFFER\",\n> >>  \t\t\t\t\t   max_request_buffer);\n> >> +\tproto_header = getenv(\"HTTP_GIT_PROTOCOL\");\n> >> +\tif (proto_header)\n> >> +\t\tsetenv(GIT_PROTOCOL_ENVIRONMENT, proto_header, 1);\n> \n> Since this overwrites (I noticed the \"1\" at the end), the server\n> operator cannot force a particular protocol with their server\n> configuration, no?\n> \n> Would a weaker form to use 0 (set if there isn't any, but keep the\n> value if somebody else already has set it) work OK?  Would that have\n> a downside?\n\nYeah, I wondered about that while writing it, but struggled to think of\na reason why the server operator would want to set it at all.\n\nBut maybe as a workaround for some misbehaving client (e.g., recognizing\nit by a user-agent header). Or we could even perhaps use this in our\ntests to test the v2-client-to-v0-server fallback behavior.\n\nI'll re-roll with that change, plus some documentation changes adapted\nto this new approach.\n\n-Peff\n"},{"id":"435403","messageId":"YTtEJ8qSEfwzYkgo@coredump.intra.peff.net","threadId":"56442","inReplyTo":"xmqqilz9ugz2.fsf@gitster.g","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-09-10T11:40:23Z","receivedAt":"2021-09-10T11:40:28Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Sep 09, 2021 at 10:39:29PM -0700, Junio C Hamano wrote:\n\n> Philippe Blain <levraiphilippeblain@gmail.com> writes:\n> \n> > I agree it's nice to make it work out of the box, without the web server\n> > admin having to configure anything. But, I'm not sure we should completely\n> > drop the documentation patches: your patch will only affect future versions\n> > of git-http-backend, and users of previous versions will be left without\n> > any documentation as to how to configure it for protocol v2. So I would think we should\n> > keep the documentation patches, maybe with a mention \"this should not be necessary\n> > in Git 2.34 and later versions\" or something like that (since your\n> > commit message mentions that it \"generally\" should work like that depending\n> > on the web servers).\n> \n> Thanks, exactly my thought on the need for docs.\n\nOK. I'll try to cook something up here.\n\n-Peff\n"},{"id":"435408","messageId":"YTtleYs48A1NpUpp@coredump.intra.peff.net","threadId":"56442","inReplyTo":"YTtECuP2/A6+EI4J@coredump.intra.peff.net","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-09-10T14:02:33Z","receivedAt":"2021-09-10T14:02:36Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Sep 10, 2021 at 07:39:54AM -0400, Jeff King wrote:\n\n> I'll re-roll with that change, plus some documentation changes adapted\n> to this new approach.\n\nHere's what I came up with. I think this should replace both\njk/http-backend-handle-proto-header and kr/doc-webserver-config-for-v2.\nThe latter does give some specific nginx tips which I didn't carry over,\nbut they shouldn't be necessary after the change in http-backend. If we\ndo want to include them, they can be mentioned as optional if we later\nadd an nginx example config to the http-backend manpage.\n\n  [1/5]: t5551: test v2-to-v0 http protocol fallback\n  [2/5]: http-backend: handle HTTP_GIT_PROTOCOL CGI variable\n  [3/5]: docs/http-backend: mention v2 protocol\n  [4/5]: docs/git: discuss server-side config for GIT_PROTOCOL\n  [5/5]: docs/protocol-v2: point readers transport config discussion\n\n Documentation/git-http-backend.txt      | 26 ++++++++++++++++++++++++-\n Documentation/git-upload-pack.txt       |  8 ++++++++\n Documentation/git.txt                   | 15 ++++++++++++++\n Documentation/technical/protocol-v2.txt |  8 +++++++-\n http-backend.c                          |  4 ++++\n t/lib-httpd/apache.conf                 |  7 +++++--\n t/t5551-http-fetch-smart.sh             |  9 +++++++++\n 7 files changed, 73 insertions(+), 4 deletions(-)\n\n-Peff\n"},{"id":"435409","messageId":"YTtl+gB0V+fe1hOJ@coredump.intra.peff.net","threadId":"56442","inReplyTo":"YTtleYs48A1NpUpp@coredump.intra.peff.net","subject":"[PATCH 1/5] t5551: test v2-to-v0 http protocol fallback","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-09-10T14:04:42Z","receivedAt":"2021-09-10T14:04:46Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"Since we use the v2 protocol by default, the connection of a v2 client\nto a v2 server is well covered by the test suite. And with the\nGIT_TEST_PROTOCOL_VERSION knob, we can easily test a v0 client\nconnecting to a v2-aware server (which will then just speak v0). But we\nhave no regular tests that a v2 client, when encountering a non-v2-aware\nserver, will correctly fall back to using v0.\n\nIn theory this is a job for the cross-version tests in t/interop, but:\n\n  - they cover only git:// and file:// clones\n\n  - they are not part of the usual test suite, so nobody ever runs them\n    anyway\n\nSince using v2 over http requires configuring the web server to pass\nalong the Git-Protocol header, we can easily create a situation where\nthe server does not respect the v2 probe, and the conversation falls\nback to v0.\n\nThis works just fine. This new test is not about fixing any particular\nbug, but just making sure that the system works (and continues to work)\nas expected.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\nNot strictly necessary for this series, but it seemed like a good chance\nto beef up test coverage, and make sure the setenv() overwrite flag in\nthe next patch was set sensibly. :)\n\n t/lib-httpd/apache.conf     | 5 +++++\n t/t5551-http-fetch-smart.sh | 9 +++++++++\n 2 files changed, 14 insertions(+)\n\ndiff --git a/t/lib-httpd/apache.conf b/t/lib-httpd/apache.conf\nindex afa91e38b0..1321357d8b 100644\n--- a/t/lib-httpd/apache.conf\n+++ b/t/lib-httpd/apache.conf\n@@ -117,6 +117,11 @@ Alias /auth/dumb/ www/auth/dumb/\n \tSetEnv GIT_EXEC_PATH ${GIT_EXEC_PATH}\n \tSetEnv GIT_HTTP_EXPORT_ALL\n </LocationMatch>\n+<LocationMatch /smart_v0/>\n+\tSetEnv GIT_EXEC_PATH ${GIT_EXEC_PATH}\n+\tSetEnv GIT_HTTP_EXPORT_ALL\n+\tSetEnv GIT_PROTOCOL\n+</LocationMatch>\n ScriptAlias /smart/incomplete_length/git-upload-pack incomplete-length-upload-pack-v2-http.sh/\n ScriptAlias /smart/incomplete_body/git-upload-pack incomplete-body-upload-pack-v2-http.sh/\n ScriptAliasMatch /error_git_upload_pack/(.*)/git-upload-pack error.sh/\ndiff --git a/t/t5551-http-fetch-smart.sh b/t/t5551-http-fetch-smart.sh\nindex 4f87d90c5b..cffc47a8e3 100755\n--- a/t/t5551-http-fetch-smart.sh\n+++ b/t/t5551-http-fetch-smart.sh\n@@ -558,4 +558,13 @@ test_expect_success 'http auth forgets bogus credentials' '\n \texpect_askpass both user@host\n '\n \n+test_expect_success 'client falls back from v2 to v0 to match server' '\n+\tGIT_TRACE_PACKET=$PWD/trace \\\n+\tGIT_TEST_PROTOCOL_VERSION=2 \\\n+\tgit clone $HTTPD_URL/smart_v0/repo.git repo-v0 &&\n+\t# check for v0; there the HEAD symref is communicated in the capability\n+\t# line; v2 uses a different syntax on each ref advertisement line\n+\tgrep symref=HEAD:refs/heads/ trace\n+'\n+\n test_done\n-- \n2.33.0.731.g24eb83922d\n\n"},{"id":"435410","messageId":"YTtmOfCzvxYrBxso@coredump.intra.peff.net","threadId":"56442","inReplyTo":"YTtleYs48A1NpUpp@coredump.intra.peff.net","subject":"[PATCH 2/5] http-backend: handle HTTP_GIT_PROTOCOL CGI variable","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-09-10T14:05:45Z","receivedAt":"2021-09-10T14:05:50Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"When a client requests the v2 protocol over HTTP, they set the\nGit-Protocol header. Webservers will generally make that available to\nour CGI as HTTP_GIT_PROTOCOL in the environment. However, that's not\nsufficient for upload-pack, etc, to respect it; they look in\nGIT_PROTOCOL (without the HTTP_ prefix).\n\nEither the webserver or the CGI is responsible for relaying that HTTP\nheader into the GIT_PROTOCOL variable. Traditionally, our tests have\nconfigured the webserver to do so, but that's a burden on the server\nadmin. We can make this work out of the box by having the http-backend\nCGI copy the contents of HTTP_GIT_PROTOCOL to GIT_PROTOCOL.\n\nThere are no new tests here. By removing the SetEnvIf line from our\ntest Apache config, we're now relying on this behavior of http-backend\nto trigger the v2 protocol there (and there are numerous tests that fail\nif this doesn't work).\n\nThere is one subtlety here: we copy HTTP_GIT_PROTOCOL only if there is\nno existing GIT_PROTOCOL variable. That leaves the webserver admin free\nto override the client's decision if they choose. This is unlikely to be\nuseful in practice, but is more flexible. And indeed, it allows the\nv2-to-v0 fallback test added in the previous commit to continue working.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n http-backend.c          | 4 ++++\n t/lib-httpd/apache.conf | 2 --\n 2 files changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/http-backend.c b/http-backend.c\nindex b329bf63f0..92ceb31f9a 100644\n--- a/http-backend.c\n+++ b/http-backend.c\n@@ -739,6 +739,7 @@ static int bad_request(struct strbuf *hdr, const struct service_cmd *c)\n int cmd_main(int argc, const char **argv)\n {\n \tchar *method = getenv(\"REQUEST_METHOD\");\n+\tconst char *proto_header;\n \tchar *dir;\n \tstruct service_cmd *cmd = NULL;\n \tchar *cmd_arg = NULL;\n@@ -789,6 +790,9 @@ int cmd_main(int argc, const char **argv)\n \thttp_config();\n \tmax_request_buffer = git_env_ulong(\"GIT_HTTP_MAX_REQUEST_BUFFER\",\n \t\t\t\t\t   max_request_buffer);\n+\tproto_header = getenv(\"HTTP_GIT_PROTOCOL\");\n+\tif (proto_header)\n+\t\tsetenv(GIT_PROTOCOL_ENVIRONMENT, proto_header, 0);\n \n \tcmd->imp(&hdr, cmd_arg);\n \treturn 0;\ndiff --git a/t/lib-httpd/apache.conf b/t/lib-httpd/apache.conf\nindex 1321357d8b..180a41fe96 100644\n--- a/t/lib-httpd/apache.conf\n+++ b/t/lib-httpd/apache.conf\n@@ -81,8 +81,6 @@ PassEnv GIT_TRACE\n PassEnv GIT_CONFIG_NOSYSTEM\n PassEnv GIT_TEST_SIDEBAND_ALL\n \n-SetEnvIf Git-Protocol \".*\" GIT_PROTOCOL=$0\n-\n Alias /dumb/ www/\n Alias /auth/dumb/ www/auth/dumb/\n \n-- \n2.33.0.731.g24eb83922d\n\n"},{"id":"435411","messageId":"YTtnCfE48oW1qs9J@coredump.intra.peff.net","threadId":"56442","inReplyTo":"YTtleYs48A1NpUpp@coredump.intra.peff.net","subject":"[PATCH 3/5] docs/http-backend: mention v2 protocol","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-09-10T14:09:13Z","receivedAt":"2021-09-10T14:09:16Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"Historically there was a little bit of configuration needed at the\nwebserver level in order to get the client's v2 protocol probes to Git.\nBut when we introduced the v2 protocol, we never documented these.\n\nAs of the previous commit, this should mostly work out of the box\nwithout any explicit configuration. But it's worth documenting this to\nmake it clear how we expect it to work, especially in the face of\nwebservers which don't provide all headers over the CGI interface. Or\nanybody who runs across this documentation but has an older version of\nGit (or _used_ to have an older version, and wonders why they still have\na SetEnvIf line in their Apache config and whether it's still\nnecessary).\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\nI used the vague \"older versions of Git\" here, which might not be as\nhelpful as we could be.  But it seemed presumptuous to say \"before\n2.34\", since we don't know the fate of the topic, nor even that we for\nsure will call the next version 2.34.\n\nI guess we could swap out \"older versions\" for \"before 2.34\" later,\nafter the topic graduates and the release gets closer, but it does seem\nlike something that we'd easily forget to do. I dunno.\n\n Documentation/git-http-backend.txt | 26 +++++++++++++++++++++++++-\n 1 file changed, 25 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt\nindex 558966aa83..0c5c0dde19 100644\n--- a/Documentation/git-http-backend.txt\n+++ b/Documentation/git-http-backend.txt\n@@ -16,7 +16,9 @@ A simple CGI program to serve the contents of a Git repository to Git\n clients accessing the repository over http:// and https:// protocols.\n The program supports clients fetching using both the smart HTTP protocol\n and the backwards-compatible dumb HTTP protocol, as well as clients\n-pushing using the smart HTTP protocol.\n+pushing using the smart HTTP protocol. It also supports Git's\n+more-efficient \"v2\" protocol if properly configured; see the\n+discussion of `GIT_PROTOCOL` in the ENVIRONMENT section below.\n \n It verifies that the directory has the magic file\n \"git-daemon-export-ok\", and it will refuse to export any Git directory\n@@ -77,6 +79,18 @@ Apache 2.x::\n SetEnv GIT_PROJECT_ROOT /var/www/git\n SetEnv GIT_HTTP_EXPORT_ALL\n ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/\n+\n+# This is not strictly necessary using Apache and a modern version of\n+# git-http-backend, as the webserver will pass along the header in the\n+# environment as HTTP_GIT_PROTOCOL, and http-backend will copy that into\n+# GIT_PROTOCOL. But you may need this line (or something similar if you\n+# are using a different webserver), or if you want to support older Git\n+# versions that did not do that copying.\n+#\n+# Having the webserver set up GIT_PROTOCOL is perfectly fine even with\n+# modern versions (and will take precedence over HTTP_GIT_PROTOCOL,\n+# which means it can be used to override the client's request).\n+SetEnvIf Git-Protocol \".*\" GIT_PROTOCOL=$0\n ----------------------------------------------------------------\n +\n To enable anonymous read access but authenticated write access,\n@@ -264,6 +278,16 @@ a repository with an extremely large number of refs.  The value can be\n specified with a unit (e.g., `100M` for 100 megabytes). The default is\n 10 megabytes.\n \n+Clients may probe for optional protocol capabilities (like the v2\n+protocol) using the `Git-Protocol` HTTP header. In order to support\n+these, the contents of that header must appear in the `GIT_PROTOCOL`\n+environment variable. Most webservers will pass this header to the CGI\n+via the `HTTP_GIT_PROTOCOL` variable, and `git-http-backend` will\n+automatically copy that to `GIT_PROTOCOL`. However, some webservers may\n+be more selective about which headers they'll pass, in which case they\n+need to be configured explicitly (see the mention of `Git-Protocol` in\n+the Apache config from the earlier EXAMPLES section).\n+\n The backend process sets GIT_COMMITTER_NAME to '$REMOTE_USER' and\n GIT_COMMITTER_EMAIL to '$\\{REMOTE_USER}@http.$\\{REMOTE_ADDR\\}',\n ensuring that any reflogs created by 'git-receive-pack' contain some\n-- \n2.33.0.731.g24eb83922d\n\n"},{"id":"435412","messageId":"YTtnNLiKyZ3OkQqy@coredump.intra.peff.net","threadId":"56442","inReplyTo":"YTtleYs48A1NpUpp@coredump.intra.peff.net","subject":"[PATCH 4/5] docs/git: discuss server-side config for GIT_PROTOCOL","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-09-10T14:09:56Z","receivedAt":"2021-09-10T14:09:58Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"The v2 protocol requires that the GIT_PROTOCOL environment variable gets\npassed around, but we don't have any documentation describing how this\nis supposed to work. In particular, we need to note what server admins\nmight need to configure to make things work.\n\nThe definition of the GIT_PROTOCOL variable is probably the best place\nfor this, since:\n\n  - we deal with multiple transports (ssh, http, etc).\n    Transport-specific documentation (like the git-http-backend bits\n    added in the previous commit) are helpful for those transports, but\n    this gives a broader overview. Plus we do not have a specific\n    transport endpoint program for ssh, so this is a reasonable place to\n    mention it.\n\n  - the server side of the protocol involves multiple programs. For now,\n    upload-pack is the only endpoint which uses GIT_PROTOCOL, but that\n    will likely expand in the future. We're better off with a central\n    discussion of what the server admin might need to do. However, for\n    discoverability, this patch adds a pointer from upload-pack's\n    documentation.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Documentation/git-upload-pack.txt |  8 ++++++++\n Documentation/git.txt             | 15 +++++++++++++++\n 2 files changed, 23 insertions(+)\n\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 9822c1eb1a..070fc78008 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -44,6 +44,14 @@ OPTIONS\n <directory>::\n \tThe repository to sync from.\n \n+ENVIRONMENT\n+-----------\n+\n+`GIT_PROTOCOL`::\n+\tInternal variable used for handshaking the wire protocol. Server\n+\tadmins may need to configure some transports to allow this\n+\tvariable to be passed. See the discussion in linkgit:git[1].\n+\n SEE ALSO\n --------\n linkgit:gitnamespaces[7]\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 6dd241ef83..e4b82599fc 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -894,6 +894,21 @@ for full details.\n \tContains a colon ':' separated list of keys with optional values\n \t'key[=value]'.  Presence of unknown keys and values must be\n \tignored.\n++\n+Note that servers may need to be configured to allow this variable to\n+pass over some transports. It will be propagated automatically when\n+accessing local repositories (i.e., `file://` or a filesystem path), as\n+well as over the `git://` protocol. For git-over-http, it should work\n+automatically in most configurations, but see the discussion in\n+linkgit:git-http-backend[1]. For git-over-ssh, the ssh server may need\n+to be configured to allow clients to pass this variable (e.g., by using\n+`AcceptEnv GIT_PROTOCOL` with OpenSSH).\n++\n+This configuration is optional. If the variable is not propagated, then\n+clients will fall back to the original \"v0\" protocol (but may miss out\n+on some performance improvements or features). This variable currently\n+only affects clones and fetches; it is not yet used for pushes (but may\n+be in the future).\n \n `GIT_OPTIONAL_LOCKS`::\n \tIf set to `0`, Git will complete any requested operation without\n-- \n2.33.0.731.g24eb83922d\n\n"},{"id":"435413","messageId":"YTtnS/pdwH2yVJJ3@coredump.intra.peff.net","threadId":"56442","inReplyTo":"YTtleYs48A1NpUpp@coredump.intra.peff.net","subject":"[PATCH 5/5] docs/protocol-v2: point readers transport config discussion","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-09-10T14:10:19Z","receivedAt":"2021-09-10T14:10:22Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"We recently added tips for server admins to configure various transports\nto support v2's GIT_PROTOCOL variable. While the protocol-v2 document is\npretty technical and not of interest to most admins, it may be a\nstarting point for them to figure out how to turn on v2. Let's put some\npointers from there to the other documentation.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Documentation/technical/protocol-v2.txt | 8 +++++++-\n 1 file changed, 7 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt\nindex 1040d85319..a703d37e08 100644\n--- a/Documentation/technical/protocol-v2.txt\n+++ b/Documentation/technical/protocol-v2.txt\n@@ -42,7 +42,8 @@ Initial Client Request\n In general a client can request to speak protocol v2 by sending\n `version=2` through the respective side-channel for the transport being\n used which inevitably sets `GIT_PROTOCOL`.  More information can be\n-found in `pack-protocol.txt` and `http-protocol.txt`.  In all cases the\n+found in `pack-protocol.txt` and `http-protocol.txt`, as well as the\n+`GIT_PROTOCOL` definition in `git.txt`. In all cases the\n response from the server is the capability advertisement.\n \n Git Transport\n@@ -58,6 +59,8 @@ SSH and File Transport\n \n When using either the ssh:// or file:// transport, the GIT_PROTOCOL\n environment variable must be set explicitly to include \"version=2\".\n+The server may need to be configured to allow this environment variable\n+to pass.\n \n HTTP Transport\n ~~~~~~~~~~~~~~\n@@ -81,6 +84,9 @@ A v2 server would reply:\n Subsequent requests are then made directly to the service\n `$GIT_URL/git-upload-pack`. (This works the same for git-receive-pack).\n \n+The server may need to be configured to pass this header's contents via\n+the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.txt`.\n+\n Capability Advertisement\n ------------------------\n \n-- \n2.33.0.731.g24eb83922d\n"},{"id":"435485","messageId":"xmqqwnnoqe17.fsf@gitster.g","threadId":"56442","inReplyTo":"YTtleYs48A1NpUpp@coredump.intra.peff.net","subject":"Re: [PATCH] Docs: web server must setenv GIT_PROTOCOL for v2","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-10T22:08:52Z","receivedAt":"2021-09-10T22:08:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> On Fri, Sep 10, 2021 at 07:39:54AM -0400, Jeff King wrote:\n>\n>> I'll re-roll with that change, plus some documentation changes adapted\n>> to this new approach.\n>\n> Here's what I came up with. I think this should replace both\n> jk/http-backend-handle-proto-header and kr/doc-webserver-config-for-v2.\n> The latter does give some specific nginx tips which I didn't carry over,\n> but they shouldn't be necessary after the change in http-backend. If we\n> do want to include them, they can be mentioned as optional if we later\n> add an nginx example config to the http-backend manpage.\n\nAll look sensible.  This topic will appear in the next round of\nintegration, not today's.\n\nThanks.\n"}]}