d2576e5f1a
For NotifyChanges and also for the fallthrough case where git-annex-shell passes a command off to git-shell, proxying is currently ignored. So every remote that is accessed via a proxy will be treated as the same git repository. Every other command listed in cmdsMap will need to check if Annex.proxyremote is set, and if so handle the proxying appropriately. Probably only P2PStdio will need to support proxying. For now, everything else refuses to work when proxying. The part of that I don't like is that there's the possibility a command later gets added to the list that doesn't check proxying. When proxying is not enabled, it's important that git-annex-shell not leak information that it would not have exposed before. Such as the names or uuids of remotes. I decided that, in the case where a repository used to have proxying enabled, but no longer supports any proxies, it's ok to give the user a clear error message indicating that proxying is not configured, rather than a confusing uuid mismatch message. Similarly, if a repository has proxying enabled, but not for the requested repository, give a clear error message. A tricky thing here is how to handle the case where there is more than one remote, with proxying enabled, with the specified uuid. One way to handle that would be to plumb the proxyRemoteName all the way through from the remote git-annex to git-annex-shell, eg as a field, and use only a remote with the same name. That would be very intrusive though. Instead, I decided to let the proxy pick which remote it uses to access a given Remote. And so it picks the least expensive one. The client after all doesn't necessarily know any details about the proxy's configuration. This does mean though, that if the least expensive remote is not accessible, but another remote would have worked, an access via the proxy will fail.
196 lines
6.2 KiB
Markdown
196 lines
6.2 KiB
Markdown
# NAME
|
|
|
|
git-annex-shell - Restricted login shell for git-annex only SSH access
|
|
|
|
# SYNOPSIS
|
|
|
|
git-annex-shell [-c] command [params ...]
|
|
|
|
# DESCRIPTION
|
|
|
|
git-annex-shell is a restricted shell, similar to git-shell, which
|
|
can be used as a login shell for SSH accounts.
|
|
|
|
Since its syntax is identical to git-shell's, it can be used as a drop-in
|
|
replacement anywhere git-shell is used. For example it can be used as a
|
|
user's restricted login shell.
|
|
|
|
# COMMANDS
|
|
|
|
Any command not listed below is passed through to git-shell.
|
|
|
|
Note that the directory parameter should be an absolute path, otherwise
|
|
it is assumed to be relative to the user's home directory. Also the
|
|
first "/~/" or "/~user/" is expanded to the specified home directory.
|
|
|
|
* configlist directory
|
|
|
|
This outputs a subset of the git configuration, in the same form as
|
|
`git config --list`. This is used to get the annex.uuid of the remote
|
|
repository.
|
|
|
|
When run in a repository that does not yet have an annex.uuid, one
|
|
will be created, as long as a git-annex branch has already been pushed to
|
|
the repository, or if the autoinit=1 flag is used to indicate
|
|
initialization is desired.
|
|
|
|
* p2pstdio directory uuid
|
|
|
|
This causes git-annex-shell to communicate using the git-annex p2p
|
|
protocol over stdio.
|
|
|
|
The uuid is the one belonging to the repository that will be
|
|
communicating with git-annex-shell.
|
|
|
|
* notifychanges directory
|
|
|
|
This is used by `git-annex remotedaemon` to be notified when
|
|
refs in the remote repository are changed.
|
|
|
|
* gcryptsetup directory gcryptid
|
|
|
|
Sets up a repository as a gcrypt repository.
|
|
|
|
* inannex directory [key ...]
|
|
|
|
This checks if all specified keys are present in the annex,
|
|
and exits zero if so.
|
|
|
|
Exits 1 if the key is certainly not present in the annex.
|
|
Exits 100 if it's unable to tell (perhaps the key is in the process of
|
|
being removed from the annex).
|
|
|
|
Used only by the gcrypt special remote.
|
|
|
|
* recvkey directory key
|
|
|
|
This runs rsync in server mode to receive the content of a key,
|
|
and stores the content in the annex.
|
|
|
|
Used only by the gcrypt special remote.
|
|
|
|
* sendkey directory key
|
|
|
|
This runs rsync in server mode to transfer out the content of a key.
|
|
|
|
Used only by the gcrypt special remote.
|
|
|
|
* dropkey directory [key ...]
|
|
|
|
This drops the annexed data for the specified keys.
|
|
|
|
Used only by the gcrypt special remote.
|
|
|
|
# OPTIONS
|
|
|
|
* --uuid=UUID
|
|
|
|
git-annex uses this to specify the UUID of the repository it was expecting
|
|
git-annex-shell to access. This is both a sanity check, and allows
|
|
git-annex shell to proxy access to remotes, when configured
|
|
by [[git-annex-update-proxy]].
|
|
|
|
* Also the [[git-annex-common-options]](1) can be used.
|
|
|
|
* -- fields=val fields=val.. --
|
|
|
|
Additional fields may be specified this way, to retain compatibility with
|
|
past versions of git-annex-shell (that ignore these, but would choke
|
|
on new dashed options).
|
|
|
|
Currently used fields are autoinit= and remoteuuid=
|
|
|
|
# HOOK
|
|
|
|
After content is received or dropped from the repository by git-annex-shell,
|
|
it runs a hook, `.git/hooks/annex-content` (or `hooks/annex-content` on a bare
|
|
repository). The hook is not currently passed any information about what
|
|
changed.
|
|
|
|
# ENVIRONMENT
|
|
|
|
* GIT_ANNEX_SHELL_READONLY
|
|
|
|
If set, disallows any action that could modify the git-annex
|
|
repository.
|
|
|
|
Note that this does not prevent passing commands on to git-shell.
|
|
For that, you also need ...
|
|
|
|
* GIT_ANNEX_SHELL_LIMITED
|
|
|
|
If set, disallows running git-shell to handle unknown commands.
|
|
|
|
* GIT_ANNEX_SHELL_APPENDONLY
|
|
|
|
If set, allows data to be written to the git-annex repository,
|
|
but does not allow data to be removed from it.
|
|
|
|
Note that this does not prevent passing commands on to git-shell,
|
|
so you will have to separately configure git to reject pushes that
|
|
overwrite branches or are otherwise not appends. The git pre-receive
|
|
hook may be useful for accomplishing this.
|
|
|
|
It's a good idea to enable annex.securehashesonly in a repository
|
|
that's set up this way.
|
|
|
|
* GIT_ANNEX_SHELL_DIRECTORY
|
|
|
|
If set, git-annex-shell will refuse to run commands that do not operate
|
|
on the specified directory.
|
|
|
|
# EXAMPLES
|
|
|
|
To make a `~/.ssh/authorized_keys` file that only allows git-annex-shell
|
|
to be run, and not other commands, pass the original command to the -c
|
|
option:
|
|
|
|
command="git-annex-shell -c \"$SSH_ORIGINAL_COMMAND\"",no-agent-forwarding,no-port-forwarding,no-X11-forwarding ssh-rsa AAAAB3NzaC1y[...] user@example.com
|
|
|
|
To further restrict git-annex-shell to a particular repository,
|
|
and fully lock it down to read-only mode:
|
|
|
|
command="GIT_ANNEX_SHELL_DIRECTORY=/srv/annex GIT_ANNEX_SHELL_LIMITED=true GIT_ANNEX_SHELL_READONLY=true git-annex-shell -c \"$SSH_ORIGINAL_COMMAND\"",restrict ssh-rsa AAAAB3NzaC1y[...] user@example.com
|
|
|
|
Obviously, `ssh-rsa AAAAB3NzaC1y[...] user@example.com` needs to
|
|
replaced with your SSH key. The above also assumes `git-annex-shell`
|
|
is available in your `$PATH`, use an absolute path if it is not the
|
|
case. Also note how the above uses the `restrict` option instead of an
|
|
explicit list of functionality to disallow. This only works in certain
|
|
OpenSSH releases, starting from 7.1p2.
|
|
|
|
To only allow adding new objects to the repository, the
|
|
`GIT_ANNEX_SHELL_APPENDONLY` variable can be used as well:
|
|
|
|
command="GIT_ANNEX_SHELL_DIRECTORY=/srv/annex GIT_ANNEX_SHELL_APPENDONLY=true git-annex-shell -c \"$SSH_ORIGINAL_COMMAND\"",restrict ssh-rsa AAAAB3NzaC1y[...] user@example.com
|
|
|
|
This will not keep an attacker from destroying the git history, as
|
|
explained above. For this you might want to disallow certain
|
|
operations, like branch deletion and force-push, with options from
|
|
git-config(1). For example:
|
|
|
|
git config receive.denyDeletes true
|
|
git config receive.denyNonFastForwards true
|
|
|
|
With this configuration, git commits can still remove files,
|
|
but they will still be available in the git history and git-annex will
|
|
retain their contents. Changes to `git-annex` branch, however, can
|
|
negatively impact git-annex's location tracking information and might
|
|
cause data loss. To work around this problem, more complex hooks
|
|
are required, see for example the `update-paranoid` hook in the git
|
|
source distribution.
|
|
|
|
|
|
# SEE ALSO
|
|
|
|
[[git-annex]](1)
|
|
|
|
git-shell(1)
|
|
|
|
# AUTHOR
|
|
|
|
Joey Hess <id@joeyh.name>
|
|
|
|
<http://git-annex.branchable.com/>
|
|
|
|
Warning: Automatically converted into a man page by mdwn2man. Edit with care
|