git-annex/doc/git-annex-shell.mdwn

# 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.

# 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 command that could modify the 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_DIRECTORY

  If set, git-annex-shell will refuse to run commands that do not operate
  on the specified directory.

# SEE ALSO

[[git-annex]](1)

git-shell(1)

# AUTHOR

Joey Hess <id@joeyh.name>

<http://git-annex.branchable.com/>

Warning: Automatically converted into a man page by mdwn2man. Edit with care
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00			`# NAME`

			`git-annex-shell - Restricted login shell for git-annex only SSH access`

			`# SYNOPSIS`

git-annex-shell mostly done now, only needs 2 more subcommands 2010-12-31 00:08:22 +00:00			`git-annex-shell [-c] command [params ...]`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
			`# DESCRIPTION`

git-annex-shell mostly done now, only needs 2 more subcommands 2010-12-31 00:08:22 +00:00			`git-annex-shell is a restricted shell, similar to git-shell, which`
			`can be used as a login shell for SSH accounts.`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
updates 2011-03-04 01:55:56 +00:00			`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.`

add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00			`# COMMANDS`

reformat to work around man page conversion bugs 2011-04-09 18:15:38 +00:00			`Any command not listed below is passed through to git-shell.`

git-annex-shell: GIT_ANNEX_SHELL_READONLY and GIT_ANNEX_SHELL_LIMITED environment variables can be set to limit what commands can be run. This could be used by eg, gitolite. 2011-10-15 23:06:35 +00:00			`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.`

git-annex-shell mostly done now, only needs 2 more subcommands 2010-12-31 00:08:22 +00:00			`* configlist directory`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
updates 2011-03-04 01:55:56 +00:00			`This outputs a subset of the git configuration, in the same form as`
git-annex-shell: Make configlist automatically initialize a remote git repository, as long as a git-annex branch has been pushed to it, to simplify setup of remote git repositories, including via gitolite. 2014-03-26 18:22:21 +00:00			`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`
Simplify setup process for a ssh remote. Now it suffices to run git remote add, followed by git-annex sync. Now the remote is automatically initialized for use by git-annex, where before the git-annex branch had to manually be pushed before using git-annex sync. Note that this involved changes to git-annex-shell, so if the remote is using an old version, the manual push is still needed. Implementation required git-annex-shell be changed, so configlist can autoinit a repository even when no git-annex branch has been pushed yet. Unfortunate because we'll have to wait for it to get deployed to servers before being able to rely on this change in the documentation. Did consider making git-annex sync push the git-annex branch to repos that didn't have a uuid, but this seemed difficult to do without complicating it in messy ways. It would be cleaner to split a command out from configlist to handle the initialization. But this is difficult without sacrificing backwards compatability, for users of old git-annex versions which would not use the new command. 2015-08-05 17:49:54 +00:00			`the repository, or if the autoinit= flag is used to indicate`
			`initialization is desired.`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
git-annex-shell mostly done now, only needs 2 more subcommands 2010-12-31 00:08:22 +00:00			`* inannex directory [key ...]`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
git-annex-shell mostly done now, only needs 2 more subcommands 2010-12-31 00:08:22 +00:00			`This checks if all specified keys are present in the annex,`
			`and exits zero if so.`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
doc/*.mdwn: Various typo fixes 2015-05-30 14:54:14 +00:00			`Exits 1 if the key is certainly not present in the annex.`
document exit codes of inannex 2015-05-19 18:35:56 +00:00			`Exits 100 if it's unable to tell (perhaps the key is in the process of`
			`being removed from the annex).`

git-annex-shell: Added lockcontent command, to prevent dropping of key's content. 2015-10-08 18:47:46 +00:00			`* 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.`

git-annex-shell mostly done now, only needs 2 more subcommands 2010-12-31 00:08:22 +00:00			`* dropkey directory [key ...]`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
git-annex-shell mostly done now, only needs 2 more subcommands 2010-12-31 00:08:22 +00:00			`This drops the annexed data for the specified keys.`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
git-annex-shell mostly done now, only needs 2 more subcommands 2010-12-31 00:08:22 +00:00			`* recvkey directory key`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
git-annex-shell mostly done now, only needs 2 more subcommands 2010-12-31 00:08:22 +00:00			`This runs rsync in server mode to receive the content of a key,`
			`and stores the content in the annex.`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
git-annex-shell mostly done now, only needs 2 more subcommands 2010-12-31 00:08:22 +00:00			`* sendkey directory key`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
git-annex-shell mostly done now, only needs 2 more subcommands 2010-12-31 00:08:22 +00:00			`This runs rsync in server mode to transfer out the content of a key.`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
hooked up git-annex-shell transferinfo Finally done with progressbars! 2012-09-22 03:25:06 +00:00			`* transferinfo directory key`
git-annex-shell transferinfo command TODO: Use this when running sendkey, to feed back transfer info from the client side rsync. 2012-09-21 20:23:25 +00:00
			`This is typically run at the same time as sendkey is sending a key`
hooked up git-annex-shell transferinfo Finally done with progressbars! 2012-09-22 03:25:06 +00:00			`to the remote. Using it is optional, but is used to update`
			`progress information for the transfer of the key.`
git-annex-shell transferinfo command TODO: Use this when running sendkey, to feed back transfer info from the client side rsync. 2012-09-21 20:23:25 +00:00
			`It reads lines from standard input, each giving the number of bytes`
hooked up git-annex-shell transferinfo Finally done with progressbars! 2012-09-22 03:25:06 +00:00			`that have been received so far.`
git-annex-shell transferinfo command TODO: Use this when running sendkey, to feed back transfer info from the client side rsync. 2012-09-21 20:23:25 +00:00
typo 2012-06-24 21:51:08 +00:00			`* commit directory`
add git-annex-shell commit Eventually, git-annex might try running this after making changes to a remote. I have not yet thought of a good way for it to tell which remotes it needs to run it on though. It can't just do it when shutting down a cached ssh connection, because ssh connection caching is optional, and that would not handle local remotes not accessed over ssh either. 2012-02-25 20:31:38 +00:00
			`This commits any staged changes to the git-annex branch.`
git-annex-shell: Runs hooks/annex-content after content is received or dropped. 2012-03-14 16:01:56 +00:00			`It also runs the annex-content hook.`
add git-annex-shell commit Eventually, git-annex might try running this after making changes to a remote. I have not yet thought of a good way for it to tell which remotes it needs to run it on though. It can't just do it when shutting down a cached ssh connection, because ssh connection caching is optional, and that would not handle local remotes not accessed over ssh either. 2012-02-25 20:31:38 +00:00
add missing directory params in 2 places 2015-08-05 13:42:43 +00:00			`* notifychanges directory`
git-annex-shell: Added notifychanges command. This will be used by the remote-daemon to quickly tell when changes have been pushed from some other repository into a ssh remote. Adjusted the remote-daemon protocol to communicate changed shas, rather than git branch refs. This way, it can easily check if a sha is new. This commit was sponsored by Carlos Trijueque Albarran. 2014-04-05 20:04:37 +00:00
typo 2014-04-11 16:12:34 +00:00			This is used by `git-annex remotedaemon` to be notified when
git-annex-shell: Added notifychanges command. This will be used by the remote-daemon to quickly tell when changes have been pushed from some other repository into a ssh remote. Adjusted the remote-daemon protocol to communicate changed shas, rather than git branch refs. This way, it can easily check if a sha is new. This commit was sponsored by Carlos Trijueque Albarran. 2014-04-05 20:04:37 +00:00			`refs in the remote repository are changed.`

add missing directory params in 2 places 2015-08-05 13:42:43 +00:00			`* gcryptsetup directory gcryptid`
git-annex-shell gcryptsetup command This was the least-bad alternative to get dedicated key gcrypt repos working in the assistant. 2013-10-01 21:20:51 +00:00
			`Sets up a repository as a gcrypt repository.`

layout 2011-05-14 16:26:06 +00:00			`# OPTIONS`
reformat to work around man page conversion bugs 2011-04-09 18:15:38 +00:00
git-annex-shell: GIT_ANNEX_SHELL_READONLY and GIT_ANNEX_SHELL_LIMITED environment variables can be set to limit what commands can be run. This could be used by eg, gitolite. 2011-10-15 23:06:35 +00:00			`Most options are the same as in git-annex. The ones specific`
			`to git-annex-shell are:`
reformat to work around man page conversion bugs 2011-04-09 18:15:38 +00:00
git-annex-shell: GIT_ANNEX_SHELL_READONLY and GIT_ANNEX_SHELL_LIMITED environment variables can be set to limit what commands can be run. This could be used by eg, gitolite. 2011-10-15 23:06:35 +00:00			`* --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.`

add fields to git-annex-shell 2012-07-02 04:53:00 +00:00			`* -- fields=val fields=val.. --`

Various typo fixes in doc/.mdwn One of my for f in `ls .mdwn \| sort -R`; do aspell -c $f; sleep 2; done sessions. 3647f704-e510-11e4-bf50-000df06acc56 2015-04-17 14:42:16 +00:00			`Additional fields may be specified this way, to retain compatibility with`
add fields to git-annex-shell 2012-07-02 04:53:00 +00:00			`past versions of git-annex-shell (that ignore these, but would choke`
			`on new dashed options).`

safe recv-key in direct mode Checks the key's size and checksum. This is sorta expensive, but it avoids needing to add another round-trip to the protocol. 2013-01-11 19:43:09 +00:00			`Currently used fields include remoteuuid=, associatedfile=,`
add unlocked flag for git-annex-shell recvkey The direct flag is also set when sending unlocked content, to support old versions of git-annex-shell. At some point, the direct flag will be removed, and only the unlocked flag will be used. 2015-12-26 17:59:27 +00:00			`unlocked=, direct=, and autoinit=`
add fields to git-annex-shell 2012-07-02 04:53:00 +00:00
git-annex-shell: Runs hooks/annex-content after content is received or dropped. 2012-03-14 16:01:56 +00:00			`# 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.`

git-annex-shell: GIT_ANNEX_SHELL_READONLY and GIT_ANNEX_SHELL_LIMITED environment variables can be set to limit what commands can be run. This could be used by eg, gitolite. 2011-10-15 23:06:35 +00:00			`# ENVIRONMENT`

			`* GIT_ANNEX_SHELL_READONLY`

			`If set, disallows any command that could modify the repository.`

note that GIT_ANNEX_SHELL_READONLY does not imply GIT_ANNEX_SHELL_LIMITED 2014-04-11 16:08:31 +00:00			`Note that this does not prevent passing commands on to git-shell.`
			`For that, you also need ...`

git-annex-shell: GIT_ANNEX_SHELL_READONLY and GIT_ANNEX_SHELL_LIMITED environment variables can be set to limit what commands can be run. This could be used by eg, gitolite. 2011-10-15 23:06:35 +00:00			`* GIT_ANNEX_SHELL_LIMITED`

			`If set, disallows running git-shell to handle unknown commands.`
expand 2011-01-04 21:33:24 +00:00
git-annex-shell: GIT_ANNEX_SHELL_DIRECTORY can be set to limit it to operating on a specified directory. 2012-11-05 15:29:12 +00:00			`* GIT_ANNEX_SHELL_DIRECTORY`

			`If set, git-annex-shell will refuse to run commands that do not operate`
			`on the specified directory.`

add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00			`# SEE ALSO`

			`[[git-annex]](1)`

			`git-shell(1)`

			`# AUTHOR`

update my email address and homepage url 2015-01-21 16:50:09 +00:00			`Joey Hess <id@joeyh.name>`
add git-annex-shell command This is not yet complete, as it does not allow starting rsync or scp. 2010-12-30 20:52:24 +00:00
			`<http://git-annex.branchable.com/>`

change footer 2011-12-07 17:17:00 +00:00			`Warning: Automatically converted into a man page by mdwn2man. Edit with care`