8e5746d0a6
When this is converted to a man page, that doesn't come through well. And a link to a todo page is not really appropriate here anyway.
214 lines
6.9 KiB
Markdown
214 lines
6.9 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= flag is used to indicate
|
|
initialization is desired.
|
|
|
|
* 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).
|
|
|
|
* lockcontent directory key
|
|
|
|
This locks a key's content in place in the annex, preventing it from
|
|
being dropped.
|
|
|
|
Once the content is successfully locked, outputs "OK". Then the content
|
|
remains locked until a newline is received from the caller or the
|
|
connection is broken.
|
|
|
|
Exits nonzero if the content is not present, or could not be locked.
|
|
|
|
* dropkey directory [key ...]
|
|
|
|
This drops the annexed data for the specified keys.
|
|
|
|
* recvkey directory key
|
|
|
|
This runs rsync in server mode to receive the content of a key,
|
|
and stores the content in the annex.
|
|
|
|
* sendkey directory key
|
|
|
|
This runs rsync in server mode to transfer out the content of a key.
|
|
|
|
* transferinfo directory key
|
|
|
|
This is typically run at the same time as sendkey is sending a key
|
|
to the remote. Using it is optional, but is used to update
|
|
progress information for the transfer of the key.
|
|
|
|
It reads lines from standard input, each giving the number of bytes
|
|
that have been received so far.
|
|
|
|
* commit directory
|
|
|
|
This commits any staged changes to the git-annex branch.
|
|
It also runs the annex-content hook.
|
|
|
|
* 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.
|
|
|
|
* p2pstdio directory uuid
|
|
|
|
This causes git-annex-shell to communicate using the git-annex p2p
|
|
protocol over stdio. When supported by git-annex-shell, this allows
|
|
multiple actions to be run over a single connection, improving speed.
|
|
|
|
The uuid is the one belonging to the repository that will be
|
|
communicating with git-annex-shell.
|
|
|
|
# OPTIONS
|
|
|
|
Most options are the same as in git-annex. The ones specific
|
|
to git-annex-shell are:
|
|
|
|
* --uuid=UUID
|
|
|
|
git-annex uses this to specify the UUID of the repository it was expecting
|
|
git-annex-shell to access, as a sanity check.
|
|
|
|
* -- 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 include remoteuuid=, associatedfile=,
|
|
unlocked=, direct=, and autoinit=
|
|
|
|
# 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
|