[PATCH 1/2] shell doc: emphasize purpose and security model
The original git-shell(1) manpage emphasized that the shell supports only git transport commands. As the shell gained features, that emphasis and focus in the manual has been lost. Bring it back by splitting the manpage into a few short sections and fleshing out each: - SYNOPSIS, describing how the shell gets used in practice - DESCRIPTION, which gives an overview of the purpose and guarantees provided by this restricted shell - COMMANDS, listing supported commands and restrictions on the arguments they accept - INTERACTIVE USE, describing the interactive mode Also add a "see also" section with related reading. Signed-off-by: Jonathan Nieder --- Changes since v2: - use "command -v" instead of "which" in synopsis to subtly reinforce good habits - use instead of hardcoding "git" username in synopsis - give up on typesetting "git> " in monospace, since the toolchain doesn't seem to like lonely backticks :/ - clarify change description The actual text is pretty much the same. Documentation/git-shell.txt | 66 ++--- 1 file changed, 51 insertions(+), 15 deletions(-) diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index 9b925060..544b21aa 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -9,25 +9,61 @@ git-shell - Restricted login shell for Git-only SSH access SYNOPSIS [verse] -'git shell' [-c ] +'chsh' -s $(command -v git-shell) +'git clone' `@localhost:/path/to/repo.git` +'ssh' `@localhost` DESCRIPTION --- -A login shell for SSH accounts to provide restricted Git access. When -'-c' is given, the program executes non-interactively; - can be one of 'git receive-pack', 'git upload-pack', 'git -upload-archive', 'cvs server', or a command in COMMAND_DIR. The shell -is started in interactive mode when no arguments are given; in this -case, COMMAND_DIR must exist, and any of the executables in it can be -invoked. - -'cvs server' is a special command which executes git-cvsserver. - -COMMAND_DIR is the path "$HOME/git-shell-commands". The user must have -read and execute permissions to the directory in order to execute the -programs in it. The programs are executed with a cwd of $HOME, and - is parsed as a command-line string. +This is a login shell for SSH accounts to provide restricted Git access. +It permits execution only of server-side Git commands implementing the +pull/push functionality, plus custom commands present in a subdirectory +named `git-shell-commands` in the user's home directory. + +COMMANDS + + +'git shell' accepts the following commands after the '-c' option: + +'git receive-pack ':: +'git upload-pack ':: +'git upload-archive ':: + Call the corresponding server-side command to support + the client's 'git push', 'git fetch', or 'git archive --remote' + request. +'cvs server':: + Imitate a CVS server. See linkgit:git-cvsserver[1]. + +If a `~/git-shell-commands` directory is present, 'git shell' will +also handle other, custom commands by running +"`git-shell-commands/ `" from the user's home +directory. + +INTERACTIVE USE +--- + +By default, the commands above can be executed only with the '-c' +option; the shell is not interactive. + +If a `~/git-shell-commands` directory is present, 'git shell' +can also be run interactively (with no arguments). If a `help` +command is present in the `git-shell-commands` directory, it is +run to provide the user with an overview of allowed actions. Then a +"git> " prompt is presented at which one can enter any of the +commands from the `git-shell-commands` directory, or `exit` to close +the connection. + +Generally this mode is used as an administrative interface to allow +users to list repositories they have access to, create, delete, or +rename repositories, or change repository descriptions and +permissions. + +SEE ALSO + +ssh(1), +linkgit:git-daemon[1], +contrib/git-shell-commands/README GIT --- -- 1.8.2.rc3 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 1/2] shell doc: emphasize purpose and security model
Jonathan Nieder writes: > diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt > index 9b925060..4fe93203 100644 > --- a/Documentation/git-shell.txt > +++ b/Documentation/git-shell.txt > @@ -9,25 +9,61 @@ git-shell - Restricted login shell for Git-only SSH access > SYNOPSIS > > [verse] > -'git shell' [-c ] > +'chsh' -s $(which git-shell) git > +'git clone' `git@localhost:/path/to/repo.git` > +'ssh' `git@localhost` I am wondering if we want to do the following instead of/in addition to fixing the $(which git-shell). It is not like we only allow a single user and its name has to be 'git'. diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index 4fe9320..6829ea9 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -9,9 +9,9 @@ git-shell - Restricted login shell for Git-only SSH access SYNOPSIS [verse] -'chsh' -s $(which git-shell) git -'git clone' `git@localhost:/path/to/repo.git` -'ssh' `git@localhost` +'chsh' -s /path/to/git-shell +'git clone' `@localhost:/path/to/repo.git` +'ssh' `@localhost` DESCRIPTION --- -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 1/2] shell doc: emphasize purpose and security model
Junio C Hamano wrote: > Jonathan Nieder writes: >> --- a/Documentation/git-shell.txt >> +++ b/Documentation/git-shell.txt >> @@ -9,25 +9,61 @@ git-shell - Restricted login shell for Git-only SSH access >> SYNOPSIS >> >> [verse] >> -'git shell' [-c ] >> +'chsh' -s $(which git-shell) git [...] > "command -v" Sounds good. (chsh isn't in POSIX either, FWIW. ;-)) Jonathan -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 1/2] shell doc: emphasize purpose and security model
Jonathan Nieder writes: > diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt > index 9b925060..4fe93203 100644 > --- a/Documentation/git-shell.txt > +++ b/Documentation/git-shell.txt > @@ -9,25 +9,61 @@ git-shell - Restricted login shell for Git-only SSH access > SYNOPSIS > > [verse] > -'git shell' [-c ] > +'chsh' -s $(which git-shell) git Please don't use "which" in scripts. Perhaps "command -v" is more suitable here. Otherwise looks good to me. Thanks. > +'git clone' `git@localhost:/path/to/repo.git` > +'ssh' `git@localhost` > > DESCRIPTION > --- > > +This is a login shell for SSH accounts to provide restricted Git access. > +It permits execution only of server-side Git commands implementing the > +pull/push functionality, plus custom commands present in a subdirectory > +named `git-shell-commands` in the user's home directory. > + > +COMMANDS > + > + > +'git shell' accepts the following commands after the '-c' option: > + > +'git receive-pack ':: > +'git upload-pack ':: > +'git upload-archive ':: > + Call the corresponding server-side command to support > + the client's 'git push', 'git fetch', or 'git archive --remote' > + request. > +'cvs server':: > + Imitate a CVS server. See linkgit:git-cvsserver[1]. > + > +If a `~/git-shell-commands` directory is present, 'git shell' will > +also handle other, custom commands by running > +"`git-shell-commands/ `" from the user's home > +directory. > + > +INTERACTIVE USE > +--- > + > +By default, the commands above can be executed only with the '-c' > +option; the shell is not interactive. > + > +If a `~/git-shell-commands` directory is present, 'git shell' > +can also be run interactively (with no arguments). If a `help` > +command is present in the `git-shell-commands` directory, it is > +run to provide the user with an overview of allowed actions. Then a > +"`git> `" prompt is presented at which one can enter any of the > +commands from the `git-shell-commands` directory, or `exit` to close > +the connection. > + > +Generally this mode is used as an administrative interface to allow > +users to list repositories they have access to, create, delete, or > +rename repositories, or change repository descriptions and > +permissions. > + > +SEE ALSO > + > +ssh(1), > +linkgit:git-daemon[1], > +contrib/git-shell-commands/README > > GIT > --- -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 1/2] shell doc: emphasize purpose and security model
The original git-shell(1) manpage emphasized that the shell supports only git transport commands, and as the shell gained features that emphasis and focus in the manual has been lost. Bring it back by splitting the manpage into a few short sections and fleshing out each: - SYNOPSIS, describing how the shell gets used in practice - DESCRIPTION, which gives an overview of the purpose and guarantees provided by this restricted shell - COMMANDS, listing supported commands and restrictions on the arguments they accept - INTERACTIVE USE, describing the interactive mode Also add a "see also" section with some relevant related reading. Signed-off-by: Jonathan Nieder --- New text. Split off from patch 2 --- this is just documenting existing behavior. Documentation/git-shell.txt | 66 ++--- 1 file changed, 51 insertions(+), 15 deletions(-) diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index 9b925060..4fe93203 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -9,25 +9,61 @@ git-shell - Restricted login shell for Git-only SSH access SYNOPSIS [verse] -'git shell' [-c ] +'chsh' -s $(which git-shell) git +'git clone' `git@localhost:/path/to/repo.git` +'ssh' `git@localhost` DESCRIPTION --- -A login shell for SSH accounts to provide restricted Git access. When -'-c' is given, the program executes non-interactively; - can be one of 'git receive-pack', 'git upload-pack', 'git -upload-archive', 'cvs server', or a command in COMMAND_DIR. The shell -is started in interactive mode when no arguments are given; in this -case, COMMAND_DIR must exist, and any of the executables in it can be -invoked. - -'cvs server' is a special command which executes git-cvsserver. - -COMMAND_DIR is the path "$HOME/git-shell-commands". The user must have -read and execute permissions to the directory in order to execute the -programs in it. The programs are executed with a cwd of $HOME, and - is parsed as a command-line string. +This is a login shell for SSH accounts to provide restricted Git access. +It permits execution only of server-side Git commands implementing the +pull/push functionality, plus custom commands present in a subdirectory +named `git-shell-commands` in the user's home directory. + +COMMANDS + + +'git shell' accepts the following commands after the '-c' option: + +'git receive-pack ':: +'git upload-pack ':: +'git upload-archive ':: + Call the corresponding server-side command to support + the client's 'git push', 'git fetch', or 'git archive --remote' + request. +'cvs server':: + Imitate a CVS server. See linkgit:git-cvsserver[1]. + +If a `~/git-shell-commands` directory is present, 'git shell' will +also handle other, custom commands by running +"`git-shell-commands/ `" from the user's home +directory. + +INTERACTIVE USE +--- + +By default, the commands above can be executed only with the '-c' +option; the shell is not interactive. + +If a `~/git-shell-commands` directory is present, 'git shell' +can also be run interactively (with no arguments). If a `help` +command is present in the `git-shell-commands` directory, it is +run to provide the user with an overview of allowed actions. Then a +"`git> `" prompt is presented at which one can enter any of the +commands from the `git-shell-commands` directory, or `exit` to close +the connection. + +Generally this mode is used as an administrative interface to allow +users to list repositories they have access to, create, delete, or +rename repositories, or change repository descriptions and +permissions. + +SEE ALSO + +ssh(1), +linkgit:git-daemon[1], +contrib/git-shell-commands/README GIT --- -- 1.8.1.3 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html