| Message ID | 20211107225525.431138-2-sandals@crustytoothpaste.net (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Additional FAQ entries | expand |
On Sun, Nov 7, 2021 at 5:55 PM brian m. carlson <sandals@crustytoothpaste.net> wrote: > Many corporate environments and local systems have proxies in use. Note > the situations in which proxies can be used and how to configure them. > At the same time, note what standards a proxy must follow to work with > Git. Explicitly call out certain classes that are known to routinely > have problems reported various places online, including in the Git for > Windows issue tracker and on Stack Overflow, and recommend against the > use of such software. A couple minor comments; may not be worth a reroll or discussion... > Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> > --- > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt > +[[proxy]] > +Can I use a proxy with Git?:: > + Yes, Git supports the use of proxies. Git honors the standard `http_proxy`, > + `https_proxy`, and `no_proxy` environment variables commonly used on Unix, and > + it also can be configured with `http.proxy` and similar options for HTTPS (see > + linkgit:git-config[1]). The `http.proxy` and related options can be > + customized on a per-URL pattern basis. In addition, Git can in theory > + function normally with transparent proxies that exist on the network. > ++ > +For SSH, Git can support a proxy using `core.gitproxy`. Commonly used tools > +include `netcat` and `socat`. However, they must be configured not to exit when > +seeing EOF on standard input, which usually means that `netcat` will require > +`-q` and `socat` will require a timeout with something like `-t 10`. I've seen this come up on the mailing list a couple times recently, though I haven't really followed along and don't use Git through an SSH proxy, thus I did have to go do some reading to understand what this is talking about. Perhaps people searching out this FAQ entry will already have sufficient context to understand what this is saying, so maybe no additional context is needed here. However, I was wondering if it might make sense for this to give a bit of reason explaining _why_ these tools need to be configured to not exit immediately upon EOF. As it stands now, this solution is a black box; it will work but people won't understand why. Perhaps that doesn't matter since most people consulting a FAQ like this probably just want to get the thing working and don't care about the underlying details. Then again, if the underlying reason is made more readily apparent, maybe this knowledge can become more widespread. > +Note that in all cases, for Git to work properly, the proxy must be completely > +transparent. The proxy cannot modify, tamper with, change, or buffer the > +connection in any way, or Git will almost certainly fail to work. Note that "modify, tamper with, change" sounds like it came from the Department of Redundancy Department. I like the sound of "tamper with" since the image it conveys feels quite suitable here. Perhaps this could be simplified to: The proxy cannot tamper with or buffer the... > +many proxies, including many TLS middleboxes, Windows antivirus and firewall > +programs other than Windows Defender and Windows Firewall, and filtering proxies > +fail to meet this standard, and as a result end up breaking Git. Because of the > +many reports of problems, we recommend against the use of these classes of > +software and devices.
On 2021-11-07 at 23:27:24, Eric Sunshine wrote: > I've seen this come up on the mailing list a couple times recently, > though I haven't really followed along and don't use Git through an > SSH proxy, thus I did have to go do some reading to understand what > this is talking about. Perhaps people searching out this FAQ entry > will already have sufficient context to understand what this is > saying, so maybe no additional context is needed here. However, I was > wondering if it might make sense for this to give a bit of reason > explaining _why_ these tools need to be configured to not exit > immediately upon EOF. As it stands now, this solution is a black box; > it will work but people won't understand why. Perhaps that doesn't > matter since most people consulting a FAQ like this probably just want > to get the thing working and don't care about the underlying details. > Then again, if the underlying reason is made more readily apparent, > maybe this knowledge can become more widespread. I'll try to see if I can stuff in a sentence there about why that's necessary. I think I understand it sufficiently well to summarize it. > "modify, tamper with, change" sounds like it came from the Department > of Redundancy Department. I like the sound of "tamper with" since the > image it conveys feels quite suitable here. Perhaps this could be > simplified to: > > The proxy cannot tamper with or buffer the... I realize this sounds redundant, but I'm trying to avoid the situation where people say, "I'm not _tampering_ with it, since I'm authorized to do this by the company. I'm just modifying it to remove this inappropriate content/malware/data leak." My goal here is to make it crystal clear that if you do this, you'll break things, and provide ammunition for people to go to their IT departments and say, "Look, your proxy prevents me from doing my job. The Git developers say so. Fix it." I can drop one of "change" and "modify", though, since I think they're synonyms.
"brian m. carlson" <sandals@crustytoothpaste.net> writes: > I realize this sounds redundant, but I'm trying to avoid the situation > where people say, "I'm not _tampering_ with it, since I'm authorized to > do this by the company. I'm just modifying it to remove this > inappropriate content/malware/data leak." It might be a good strategy to educate users by leaving a deliberate hole to let them quibble with such an excuse. When it comes to on-the-wire protocol, their management do not have authority to grant them right to tamper with the data and that is not limited to Git.
Hi brian, On Sun, 7 Nov 2021, brian m. carlson wrote: > Many corporate environments and local systems have proxies in use. Note > the situations in which proxies can be used and how to configure them. > At the same time, note what standards a proxy must follow to work with > Git. Explicitly call out certain classes that are known to routinely > have problems reported various places online, including in the Git for Not a big issue, but I think there is an "at" or "to" missing before "various places online". > Windows issue tracker and on Stack Overflow, and recommend against the > use of such software. > > Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> > --- > Documentation/gitfaq.txt | 23 +++++++++++++++++++++++ > 1 file changed, 23 insertions(+) > > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt > index 946691c153..5c21951f7b 100644 > --- a/Documentation/gitfaq.txt > +++ b/Documentation/gitfaq.txt > @@ -241,6 +241,29 @@ How do I know if I want to do a fetch or a pull?:: > ignore the upstream changes. A pull consists of a fetch followed > immediately by either a merge or rebase. See linkgit:git-pull[1]. > > +[[proxy]] > +Can I use a proxy with Git?:: > + Yes, Git supports the use of proxies. Git honors the standard `http_proxy`, > + `https_proxy`, and `no_proxy` environment variables commonly used on Unix, and > + it also can be configured with `http.proxy` and similar options for HTTPS (see > + linkgit:git-config[1]). The `http.proxy` and related options can be > + customized on a per-URL pattern basis. In addition, Git can in theory > + function normally with transparent proxies that exist on the network. > ++ > +For SSH, Git can support a proxy using `core.gitproxy`. Commonly used tools > +include `netcat` and `socat`. The first idea I had after reading this is: where are these examples documented? Certainly not where I expected them, namely at https://git-scm.com/docs/git-config#Documentation/git-config.txt-coregitProxy And then I got puzzled. Why would `gitproxy` be used for the _SSH_ protocol? And I don't think it is used. I think it is only used for connections using the `git://` protocol. I might very easily be wrong, of course. > However, they must be configured not to exit when +seeing EOF on > standard input, which usually means that `netcat` will require +`-q` and > `socat` will require a timeout with something like `-t 10`. IMHO it would make sense to add a concrete example, or maybe even two concrete examples, one for `netcat` and one for `socat`. > ++ > +Note that in all cases, for Git to work properly, the proxy must be completely > +transparent. The proxy cannot modify, tamper with, change, or buffer the > +connection in any way, or Git will almost certainly fail to work. Note that > +many proxies, including many TLS middleboxes, Windows antivirus and firewall > +programs other than Windows Defender and Windows Firewall, and filtering proxies > +fail to meet this standard, and as a result end up breaking Git. Because of the > +many reports of problems, we recommend against the use of these classes of > +software and devices. > + This is good advice. Ciao, Dscho
diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index 946691c153..5c21951f7b 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -241,6 +241,29 @@ How do I know if I want to do a fetch or a pull?:: ignore the upstream changes. A pull consists of a fetch followed immediately by either a merge or rebase. See linkgit:git-pull[1]. +[[proxy]] +Can I use a proxy with Git?:: + Yes, Git supports the use of proxies. Git honors the standard `http_proxy`, + `https_proxy`, and `no_proxy` environment variables commonly used on Unix, and + it also can be configured with `http.proxy` and similar options for HTTPS (see + linkgit:git-config[1]). The `http.proxy` and related options can be + customized on a per-URL pattern basis. In addition, Git can in theory + function normally with transparent proxies that exist on the network. ++ +For SSH, Git can support a proxy using `core.gitproxy`. Commonly used tools +include `netcat` and `socat`. However, they must be configured not to exit when +seeing EOF on standard input, which usually means that `netcat` will require +`-q` and `socat` will require a timeout with something like `-t 10`. ++ +Note that in all cases, for Git to work properly, the proxy must be completely +transparent. The proxy cannot modify, tamper with, change, or buffer the +connection in any way, or Git will almost certainly fail to work. Note that +many proxies, including many TLS middleboxes, Windows antivirus and firewall +programs other than Windows Defender and Windows Firewall, and filtering proxies +fail to meet this standard, and as a result end up breaking Git. Because of the +many reports of problems, we recommend against the use of these classes of +software and devices. + Design ------
Many corporate environments and local systems have proxies in use. Note the situations in which proxies can be used and how to configure them. At the same time, note what standards a proxy must follow to work with Git. Explicitly call out certain classes that are known to routinely have problems reported various places online, including in the Git for Windows issue tracker and on Stack Overflow, and recommend against the use of such software. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> --- Documentation/gitfaq.txt | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)