1git-annex-shell(1)          General Commands Manual         git-annex-shell(1)
2
3
4

NAME

6       git-annex-shell - Restricted login shell for git-annex only SSH access
7

SYNOPSIS

9       git-annex-shell [-c] command [params ...]
10

DESCRIPTION

12       git-annex-shell  is a restricted shell, similar to git-shell, which can
13       be used as a login shell for SSH accounts.
14
15       Since its syntax is identical to git-shell's,  it  can  be  used  as  a
16       drop-in  replacement  anywhere git-shell is used. For example it can be
17       used as a user's restricted login shell.
18

COMMANDS

20       Any command not listed below is passed through to git-shell.
21
22       Note that the directory parameter should be an absolute path, otherwise
23       it  is  assumed  to  be relative to the user's home directory. Also the
24       first "/~/" or "/~user/" is expanded to the specified home directory.
25
26       configlist directory
27              This outputs a subset of the git configuration, in the same form
28              as  git config --list. This is used to get the annex.uuid of the
29              remote repository.
30
31              When run in a repository that does not yet have  an  annex.uuid,
32              one  will  be created, as long as a git-annex branch has already
33              been pushed to the repository, or if the autoinit= flag is  used
34              to indicate initialization is desired.
35
36       inannex directory [key ...]
37              This  checks if all specified keys are present in the annex, and
38              exits zero if so.
39
40              Exits 1 if the key is certainly not present in the annex.  Exits
41              100 if it's unable to tell (perhaps the key is in the process of
42              being removed from the annex).
43
44       lockcontent directory key
45              This locks a key's content in place in the annex, preventing  it
46              from being dropped.
47
48              Once  the content is successfully locked, outputs "OK". Then the
49              content remains locked until a  newline  is  received  from  the
50              caller or the connection is broken.
51
52              Exits  nonzero  if  the  content is not present, or could not be
53              locked.
54
55       dropkey directory [key ...]
56              This drops the annexed data for the specified keys.
57
58       recvkey directory key
59              This runs rsync in server mode to receive the content of a  key,
60              and stores the content in the annex.
61
62       sendkey directory key
63              This  runs rsync in server mode to transfer out the content of a
64              key.
65
66       transferinfo directory key
67              This is typically run at the same time as sendkey is  sending  a
68              key  to  the remote. Using it is optional, but is used to update
69              progress information for the transfer of the key.
70
71              It reads lines from standard input, each giving  the  number  of
72              bytes that have been received so far.
73
74       commit directory
75              This  commits  any  staged  changes to the git-annex branch.  It
76              also runs the annex-content hook.
77
78       notifychanges directory
79              This is used by git-annex remotedaemon to be notified when  refs
80              in the remote repository are changed.
81
82       gcryptsetup directory gcryptid
83              Sets up a repository as a gcrypt repository.
84
85       p2pstdio directory uuid
86              This  causes  git-annex-shell to communicate using the git-annex
87              p2p protocol over stdio. When supported by git-annex-shell, this
88              allows  multiple  actions  to  be  run over a single connection,
89              improving speed.
90
91              The uuid is the one belonging to the  repository  that  will  be
92              communicating with git-annex-shell.
93

OPTIONS

95       Most  options  are  the same as in git-annex. The ones specific to git-
96       annex-shell are:
97
98       --uuid=UUID
99              git-annex uses this to specify the UUID of the repository it was
100              expecting git-annex-shell to access, as a sanity check.
101
102       -- fields=val fields=val.. --
103              Additional  fields may be specified this way, to retain compati‐
104              bility with past versions of git-annex-shell (that ignore these,
105              but would choke on new dashed options).
106
107              Currently  used  fields  include  remoteuuid=,  associatedfile=,
108              unlocked=, direct=, and autoinit=
109

HOOK

111       After content is received  or  dropped  from  the  repository  by  git-
112       annex-shell,    it    runs   a   hook,   .git/hooks/annex-content   (or
113       hooks/annex-content on a bare repository). The hook  is  not  currently
114       passed any information about what changed.
115

ENVIRONMENT

117       GIT_ANNEX_SHELL_READONLY
118
119              If  set,  disallows  any  action that could modify the git-annex
120              repository.
121
122              Note  that  this  does  not  prevent  passing  commands  on   to
123              git-shell.  For that, you also need ...
124
125       GIT_ANNEX_SHELL_LIMITED
126              If set, disallows running git-shell to handle unknown commands.
127
128       GIT_ANNEX_SHELL_APPENDONLY
129              If  set,  allows data to be written to the git-annex repository,
130              but does not allow data to be removed from it.
131
132              Note  that  this  does  not  prevent  passing  commands  on   to
133              git-shell,  so  you  will  have  to  separately configure git to
134              reject pushes that  overwrite  branches  or  are  otherwise  not
135              appends.  The git pre-receive hook may be useful for accomplish‐
136              ing this.
137
138              It's a good idea to enable annex.securehashesonly in  a  reposi‐
139              tory that's set up this way.
140
141       GIT_ANNEX_SHELL_DIRECTORY
142              If  set, git-annex-shell will refuse to run commands that do not
143              operate on the specified directory.
144

EXAMPLES

146       To make a ~/.ssh/authorized_keys file that only allows  git-annex-shell
147       to  be run, and not other commands, pass the original command to the -c
148       option:
149
150        command="git-annex-shell  -c  \"$SSH_ORIGINAL_COMMAND\"",no-agent-for‐
151       warding,no-port-forwarding,no-X11-forwarding  ssh-rsa AAAAB3NzaC1y[...]
152       user@example.com
153
154       To further restrict git-annex-shell to  a  particular  repository,  and
155       fully lock it down to read-only mode:
156
157        command="GIT_ANNEX_SHELL_DIRECTORY=/srv/annex     GIT_ANNEX_SHELL_LIM‐
158       ITED=true GIT_ANNEX_SHELL_READONLY=true git-annex-shell -c \"$SSH_ORIG‐
159       INAL_COMMAND\"",restrict ssh-rsa AAAAB3NzaC1y[...] user@example.com
160
161       Obviously, ssh-rsa AAAAB3NzaC1y[...] user@example.com needs to replaced
162       with your SSH key. The above also assumes git-annex-shell is  available
163       in  your  $PATH,  use an absolute path if it is not the case. Also note
164       how the above uses the restrict option instead of an explicit  list  of
165       functionality to disallow. This only works in certain OpenSSH releases,
166       starting from 7.1p2.
167
168       To  only  allow   adding   new   objects   to   the   repository,   the
169       GIT_ANNEX_SHELL_APPENDONLY variable can be used as well:
170
171       command="GIT_ANNEX_SHELL_DIRECTORY=/srv/annex    GIT_ANNEX_SHELL_APPEN‐
172       DONLY=true   git-annex-shell   -c   \"$SSH_ORIGINAL_COMMAND\"",restrict
173       ssh-rsa AAAAB3NzaC1y[...] user@example.com
174
175       This  will  not  keep  an  attacker from destroying the git history, as
176       explained above. For this you might want  to  disallow  certain  opera‐
177       tions,  like branch deletion and force-push, with options from git-con‐
178       fig(1). For example:
179
180       git config receive.denyDeletes true git config  receive.denyNonFastFor‐
181       wards true
182
183       With  this  configuration, git commits can still remove files, but they
184       will still be available in the git history and  git-annex  will  retain
185       their  contents.  Changes  to git-annex branch, however, can negatively
186       impact git-annex's location tracking information and might  cause  data
187       loss. To work around this problem, more complex hooks are required, see
188       for example the update-paranoid hook in the git source distribution.
189

SEE ALSO

191       git-annex(1)
192
193       git-shell(1)
194

AUTHOR

196       Joey Hess <id@joeyh.name>
197
198       <http://git-annex.branchable.com/>
199
200                                                            git-annex-shell(1)
Impressum