git-annex-shell(1)

👑 git-annex-shell 👑

okay bestie, welcome to the git-annex-shell(1) page — it lives in the General Commands Manual section of the git-annex docs, and it is exactly the vibe you think it is: a lil locked-down shell that only lets git-annex in. 💅

---

🌸 NAME 🌸

git-annex-shell — a restricted login shell that exists purely so git-annex can do SSH access and literally nothing else 🫶

---

✨ SYNOPSIS ✨

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

---

🦋 DESCRIPTION 🦋

so git-annex-shell is a restricted shell, kinda like git-shell, and the whole point is that you can use it as a login shell for SSH accounts. it's giving bouncer-at-the-club energy — only approved commands get in. 🚪

and here's the iconic part: its syntax is identical to git-shell's, so it can be a drop-in replacement anywhere git-shell is used. for example, it can be a user's restricted login shell. no cap, you can just swap it in. 🔥

---

🎀 COMMANDS 🎀

Any command that is not listed below gets passed straight through to git-shell. (so if you don't see it here, it's not gone, it's just visiting git-shell 🧚)

⚠️ important note before we get into it: the directory parameter should be an absolute path, otherwise it's assumed to be relative to the user's home directory. also, the first /~/" or "/~user/" is expanded to the specified home directory. (yes literally, that's how it works. iykyk.)

• configlist directory — this outputs a subset of the git configuration, in the same form as git config --list. it's used to get the annex.uuid of the remote repository.
  • and when you run it in a repository that doesn't have an annex.uuid yet, one will be created — as long as a git-annex branch has already been pushed to the repository, or if the autoinit=1 flag is used to say "yes bestie, initialize, i want this." ✨
• p2pstdio directory uuid — this makes git-annex-shell communicate using the git-annex p2p protocol over stdio.
  • the uuid is the one belonging to the repository that will be communicating with git-annex-shell.
• notifychanges directory — this is used by git-annex remotedaemon to get notified when refs in the remote repository are changed. 🔔
• gcryptsetup directory gcryptid — sets up a repository as a gcrypt repository.
• 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).
  • Used only by the gcrypt special remote.
• recvkey directory key — this runs rsync in server mode to receive the content of a key, and stores the content in the annex.
  • Used only by the gcrypt special remote.
• sendkey directory key — this runs rsync in server mode to transfer out the content of a key.
  • Used only by the gcrypt special remote.
• dropkey directory [key ...] — this drops the annexed data for the specified keys.
  • Used only by the gcrypt special remote.

---

💖 OPTIONS 💖

• --uuid=UUID — git-annex uses this to specify the UUID of the repository it was expecting git-annex-shell to access. it's both a sanity check and it allows git-annex shell to proxy access to remotes, when configured by git-annex-update-proxy.

Also the git-annex-common-options(1) can be used. 👑

• -- fields=val fields=val.. -- — additional fields may be specified this way, to retain compatibility with past versions of git-annex-shell (which ignore these, but would choke on new dashed options 😭).
  • the fields currently used are autoinit= and remoteuuid=

---

🌈 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).

ngl, the hook is not currently passed any information about what changed. it just... runs. mysterious main character behavior. 💀

---

🍓 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 🧚

bestie this is the part where it gets real. 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 be 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 the 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/>

---

okay that's the whole page bestie!! 🫶 this was git-annex-shell(1) from the General Commands Manual — go forth and lock down your SSH accounts like the icon you are. mwah. 💖 🎀 ✨