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)