2005-07-14 09:08:37 +02:00
|
|
|
git-upload-pack(1)
|
|
|
|
|
==================
|
|
|
|
|
|
|
|
|
|
NAME
|
|
|
|
|
----
|
2007-01-19 00:53:37 +01:00
|
|
|
git-upload-pack - Send objects packed back to git-fetch-pack
|
2005-07-14 09:08:37 +02:00
|
|
|
|
|
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
|
--------
|
2011-07-02 04:38:26 +02:00
|
|
|
[verse]
|
2016-05-31 11:57:08 +02:00
|
|
|
'git-upload-pack' [--[no-]strict] [--timeout=<n>] [--stateless-rpc]
|
|
|
|
|
[--advertise-refs] <directory>
|
2018-10-22 22:45:43 +02:00
|
|
|
|
2005-07-14 09:08:37 +02:00
|
|
|
DESCRIPTION
|
|
|
|
|
-----------
|
2010-01-10 00:33:00 +01:00
|
|
|
Invoked by 'git fetch-pack', learns what
|
2005-07-14 09:08:37 +02:00
|
|
|
objects the other side is missing, and sends them after packing.
|
|
|
|
|
|
|
|
|
|
This command is usually not invoked directly by the end user.
|
2010-01-10 00:33:00 +01:00
|
|
|
The UI for the protocol is on the 'git fetch-pack' side, and the
|
2005-07-14 09:08:37 +02:00
|
|
|
program pair is meant to be used to pull updates from a remote
|
2010-01-10 00:33:00 +01:00
|
|
|
repository. For push operations, see 'git send-pack'.
|
2005-07-14 09:08:37 +02:00
|
|
|
|
|
|
|
|
OPTIONS
|
|
|
|
|
-------
|
2007-02-20 03:01:44 +01:00
|
|
|
|
2016-05-31 11:57:08 +02:00
|
|
|
--[no-]strict::
|
2023-10-08 08:45:05 +02:00
|
|
|
Do not try <directory>/.git/ if <directory> is not a Git directory.
|
2007-02-20 03:01:44 +01:00
|
|
|
|
2008-06-08 03:36:09 +02:00
|
|
|
--timeout=<n>::
|
2007-02-20 03:01:44 +01:00
|
|
|
Interrupt transfer after <n> seconds of inactivity.
|
|
|
|
|
|
2016-05-31 11:57:08 +02:00
|
|
|
--stateless-rpc::
|
|
|
|
|
Perform only a single read-write cycle with stdin and stdout.
|
|
|
|
|
This fits with the HTTP POST request processing model where
|
|
|
|
|
a program may read the request, write a response, and must exit.
|
|
|
|
|
|
2021-08-05 03:25:43 +02:00
|
|
|
--http-backend-info-refs::
|
|
|
|
|
Used by linkgit:git-http-backend[1] to serve up
|
|
|
|
|
`$GIT_URL/info/refs?service=git-upload-pack` requests. See
|
2022-08-04 18:28:41 +02:00
|
|
|
"Smart Clients" in linkgit:gitprotocol-http[5] and "HTTP
|
2022-09-11 12:23:20 +02:00
|
|
|
Transport" in the linkgit:gitprotocol-v2[5]
|
2022-08-04 18:28:41 +02:00
|
|
|
documentation. Also understood by
|
2021-08-05 03:25:43 +02:00
|
|
|
linkgit:git-receive-pack[1].
|
2016-05-31 11:57:08 +02:00
|
|
|
|
2005-07-14 09:08:37 +02:00
|
|
|
<directory>::
|
|
|
|
|
The repository to sync from.
|
|
|
|
|
|
docs/git: discuss server-side config for GIT_PROTOCOL
The v2 protocol requires that the GIT_PROTOCOL environment variable gets
passed around, but we don't have any documentation describing how this
is supposed to work. In particular, we need to note what server admins
might need to configure to make things work.
The definition of the GIT_PROTOCOL variable is probably the best place
for this, since:
- we deal with multiple transports (ssh, http, etc).
Transport-specific documentation (like the git-http-backend bits
added in the previous commit) are helpful for those transports, but
this gives a broader overview. Plus we do not have a specific
transport endpoint program for ssh, so this is a reasonable place to
mention it.
- the server side of the protocol involves multiple programs. For now,
upload-pack is the only endpoint which uses GIT_PROTOCOL, but that
will likely expand in the future. We're better off with a central
discussion of what the server admin might need to do. However, for
discoverability, this patch adds a pointer from upload-pack's
documentation.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-09-10 16:09:56 +02:00
|
|
|
ENVIRONMENT
|
|
|
|
|
-----------
|
|
|
|
|
|
|
|
|
|
`GIT_PROTOCOL`::
|
|
|
|
|
Internal variable used for handshaking the wire protocol. Server
|
|
|
|
|
admins may need to configure some transports to allow this
|
|
|
|
|
variable to be passed. See the discussion in linkgit:git[1].
|
|
|
|
|
|
upload-pack: disable lazy-fetching by default
The upload-pack command tries to avoid trusting the repository in which
it's run (e.g., by not running any hooks and not using any config that
contains arbitrary commands). But if the server side of a fetch or a
clone is a partial clone, then either upload-pack or its child
pack-objects may run a lazy "git fetch" under the hood. And it is very
easy to convince fetch to run arbitrary commands.
The "server" side can be a local repository owned by someone else, who
would be able to configure commands that are run during a clone with the
current user's permissions. This issue has been designated
CVE-2024-32004.
The fix in this commit's parent helps in this scenario, as well as in
related scenarios using SSH to clone, where the untrusted .git directory
is owned by a different user id. But if you received one as a zip file,
on a USB stick, etc, it may be owned by your user but still untrusted.
This has been designated CVE-2024-32465.
To mitigate the issue more completely, let's disable lazy fetching
entirely during `upload-pack`. While fetching from a partial repository
should be relatively rare, it is certainly not an unreasonable workflow.
And thus we need to provide an escape hatch.
This commit works by respecting a GIT_NO_LAZY_FETCH environment variable
(to skip the lazy-fetch), and setting it in upload-pack, but only when
the user has not already done so (which gives us the escape hatch).
The name of the variable is specifically chosen to match what has
already been added in 'master' via e6d5479e7a (git: extend
--no-lazy-fetch to work across subprocesses, 2024-02-27). Since we're
building this fix as a backport for older versions, we could cherry-pick
that patch and its earlier steps. However, we don't really need the
niceties (like a "--no-lazy-fetch" option) that it offers. By using the
same name, everything should just work when the two are eventually
merged, but here are a few notes:
- the blocking of the fetch in e6d5479e7a is incomplete! It sets
fetch_if_missing to 0 when we setup the repository variable, but
that isn't enough. pack-objects in particular will call
prefetch_to_pack() even if that variable is 0. This patch by
contrast checks the environment variable at the lowest level before
we call the lazy fetch, where we can be sure to catch all code
paths.
Possibly the setting of fetch_if_missing from e6d5479e7a can be
reverted, but it may be useful to have. For example, some code may
want to use that flag to change behavior before it gets to the point
of trying to start the fetch. At any rate, that's all outside the
scope of this patch.
- there's documentation for GIT_NO_LAZY_FETCH in e6d5479e7a. We can
live without that here, because for the most part the user shouldn't
need to set it themselves. The exception is if they do want to
override upload-pack's default, and that requires a separate
documentation section (which is added here)
- it would be nice to use the NO_LAZY_FETCH_ENVIRONMENT macro added by
e6d5479e7a, but those definitions have moved from cache.h to
environment.h between 2.39.3 and master. I just used the raw string
literals, and we can replace them with the macro once this topic is
merged to master.
At least with respect to CVE-2024-32004, this does render this commit's
parent commit somewhat redundant. However, it is worth retaining that
commit as defense in depth, and because it may help other issues (e.g.,
symlink/hardlink TOCTOU races, where zip files are not really an
interesting attack vector).
The tests in t0411 still pass, but now we have _two_ mechanisms ensuring
that the evil command is not run. Let's beef up the existing ones to
check that they failed for the expected reason, that we refused to run
upload-pack at all with an alternate user id. And add two new ones for
the same-user case that both the restriction and its escape hatch.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
2024-04-16 10:35:33 +02:00
|
|
|
`GIT_NO_LAZY_FETCH`::
|
|
|
|
|
When cloning or fetching from a partial repository (i.e., one
|
|
|
|
|
itself cloned with `--filter`), the server-side `upload-pack`
|
|
|
|
|
may need to fetch extra objects from its upstream in order to
|
|
|
|
|
complete the request. By default, `upload-pack` will refuse to
|
|
|
|
|
perform such a lazy fetch, because `git fetch` may run arbitrary
|
|
|
|
|
commands specified in configuration and hooks of the source
|
|
|
|
|
repository (and `upload-pack` tries to be safe to run even in
|
|
|
|
|
untrusted `.git` directories).
|
|
|
|
|
+
|
|
|
|
|
This is implemented by having `upload-pack` internally set the
|
|
|
|
|
`GIT_NO_LAZY_FETCH` variable to `1`. If you want to override it
|
|
|
|
|
(because you are fetching from a partial clone, and you are sure
|
|
|
|
|
you trust it), you can explicitly set `GIT_NO_LAZY_FETCH` to
|
|
|
|
|
`0`.
|
|
|
|
|
|
2024-04-16 10:52:13 +02:00
|
|
|
SECURITY
|
|
|
|
|
--------
|
|
|
|
|
|
|
|
|
|
Most Git commands should not be run in an untrusted `.git` directory
|
|
|
|
|
(see the section `SECURITY` in linkgit:git[1]). `upload-pack` tries to
|
|
|
|
|
avoid any dangerous configuration options or hooks from the repository
|
|
|
|
|
it's serving, making it safe to clone an untrusted directory and run
|
|
|
|
|
commands on the resulting clone.
|
|
|
|
|
|
|
|
|
|
For an extra level of safety, you may be able to run `upload-pack` as an
|
|
|
|
|
alternate user. The details will be platform dependent, but on many
|
|
|
|
|
systems you can run:
|
|
|
|
|
|
|
|
|
|
git clone --no-local --upload-pack='sudo -u nobody git-upload-pack' ...
|
|
|
|
|
|
2011-07-09 01:14:10 +02:00
|
|
|
SEE ALSO
|
|
|
|
|
--------
|
|
|
|
|
linkgit:gitnamespaces[7]
|
|
|
|
|
|
2005-07-14 09:08:37 +02:00
|
|
|
GIT
|
|
|
|
|
---
|
2008-06-06 09:07:32 +02:00
|
|
|
Part of the linkgit:git[1] suite
|