1git-annex-shell(1) General Commands Manual git-annex-shell(1)
2
6 git-annex-shell - Restricted login shell for git-annex only SSH access
7
9 git-annex-shell [-c] command [params ...]
10
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 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
20 Any command not listed below is passed through to git-shell.
21 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 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 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 inannex directory [key ...]
37 This checks if all specified keys are present in the annex, and
38 exits zero if so.
39 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 lockcontent directory key
45 This locks a key's content in place in the annex, preventing it
46 from being dropped.
47 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 Exits nonzero if the content is not present, or could not be
53 locked.
54 dropkey directory [key ...]
56 This drops the annexed data for the specified keys.
57 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 sendkey directory key
63 This runs rsync in server mode to transfer out the content of a
64 key.
65 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 It reads lines from standard input, each giving the number of
72 bytes that have been received so far.
73 commit directory
75 This commits any staged changes to the git-annex branch. It
76 also runs the annex-content hook.
77 notifychanges directory
79 This is used by git-annex remotedaemon to be notified when refs
80 in the remote repository are changed.
81 gcryptsetup directory gcryptid
83 Sets up a repository as a gcrypt repository.
84 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 The uuid is the one belonging to the repository that will be
92 communicating with git-annex-shell.
93
95 Most options are the same as in git-annex. The ones specific to git-
96 annex-shell are:
97 --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 -- 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 Currently used fields include remoteuuid=, associatedfile=,
108 unlocked=, direct=, and autoinit=
109
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
117 GIT_ANNEX_SHELL_READONLY
118 If set, disallows any action that could modify the git-annex
120 repository.
121 Note that this does not prevent passing commands on to
123 git-shell. For that, you also need ...
124 GIT_ANNEX_SHELL_LIMITED
126 If set, disallows running git-shell to handle unknown commands.
127 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 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 It's a good idea to enable annex.securehashesonly in a reposi‐
139 tory that's set up this way.
140 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
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 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 To further restrict git-annex-shell to a particular repository, and
155 fully lock it down to read-only mode:
156 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 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 To only allow adding new objects to the repository, the
169 GIT_ANNEX_SHELL_APPENDONLY variable can be used as well:
170 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 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 git config receive.denyDeletes true git config receive.denyNonFastFor‐
181 wards true
182 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
191 git-annex(1)
192 git-shell(1)
194
196 Joey Hess <id@joeyh.name>
197 <http://git-annex.branchable.com/>
199 git-annex-shell(1)