Provided by: git-annex_8.20200226-1_amd64 
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/>
git-annex-shell(1)