man1/git-shell.1

   1 '\" t
   2 .\"     Title: git-shell
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2023-08-14
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.42.0.rc1.11.gfc6bba66bc
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-SHELL" "1" "2023\-08\-14" "Git 2\&.42\&.0\&.rc1\&.11\&.gf" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-shell \- Restricted login shell for Git\-only SSH access
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIchsh\fR \-s $(command \-v git\-shell) <user>
  36 \fIgit clone\fR <user>\fB@localhost:/path/to/repo\&.git\fR
  37 \fIssh\fR <user>\fB@localhost\fR
  38 .fi
  39 .sp
  40 .SH "DESCRIPTION"
  41 .sp
  42 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 \fBgit\-shell\-commands\fR in the user\(cqs home directory\&.
  43 .SH "COMMANDS"
  44 .sp
  45 \fIgit shell\fR accepts the following commands after the \fB\-c\fR option:
  46 .PP
  47 \fIgit receive\-pack <argument>\fR, \fIgit upload\-pack <argument>\fR, \fIgit upload\-archive <argument>\fR
  48 .RS 4
  49 Call the corresponding server\-side command to support the client\(cqs
  50 \fIgit push\fR,
  51 \fIgit fetch\fR, or
  52 \fIgit archive \-\-remote\fR
  53 request\&.
  54 .RE
  55 .PP
  56 \fIcvs server\fR
  57 .RS 4
  58 Imitate a CVS server\&. See
  59 \fBgit-cvsserver\fR(1)\&.
  60 .RE
  61 .sp
  62 If a \fB~/git\-shell\-commands\fR directory is present, \fIgit shell\fR will also handle other, custom commands by running "\fBgit\-shell\-commands/<command> <arguments>\fR" from the user\(cqs home directory\&.
  63 .SH "INTERACTIVE USE"
  64 .sp
  65 By default, the commands above can be executed only with the \fB\-c\fR option; the shell is not interactive\&.
  66 .sp
  67 If a \fB~/git\-shell\-commands\fR directory is present, \fIgit shell\fR can also be run interactively (with no arguments)\&. If a \fBhelp\fR command is present in the \fBgit\-shell\-commands\fR 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 \fBgit\-shell\-commands\fR directory, or \fBexit\fR to close the connection\&.
  68 .sp
  69 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\&.
  70 .sp
  71 If a \fBno\-interactive\-login\fR command exists, then it is run and the interactive shell is aborted\&.
  72 .SH "EXAMPLES"
  73 .sp
  74 To disable interactive logins, displaying a greeting instead:
  75 .sp
  76 .if n \{\
  77 .RS 4
  78 .\}
  79 .nf
  80 $ chsh \-s /usr/bin/git\-shell
  81 $ mkdir $HOME/git\-shell\-commands
  82 $ cat >$HOME/git\-shell\-commands/no\-interactive\-login <<\eEOF
  83 #!/bin/sh
  84 printf \*(Aq%s\en\*(Aq "Hi $USER! You\*(Aqve successfully authenticated, but I do not"
  85 printf \*(Aq%s\en\*(Aq "provide interactive shell access\&."
  86 exit 128
  87 EOF
  88 $ chmod +x $HOME/git\-shell\-commands/no\-interactive\-login
  89 .fi
  90 .if n \{\
  91 .RE
  92 .\}
  93 .sp
  94 .sp
  95 To enable git\-cvsserver access (which should generally have the \fBno\-interactive\-login\fR example above as a prerequisite, as creating the git\-shell\-commands directory allows interactive logins):
  96 .sp
  97 .if n \{\
  98 .RS 4
  99 .\}
 100 .nf
 101 $ cat >$HOME/git\-shell\-commands/cvs <<\eEOF
 102 if ! test $# = 1 && test "$1" = "server"
 103 then
 104         echo >&2 "git\-cvsserver only handles \e"server\e""
 105         exit 1
 106 fi
 107 exec git cvsserver server
 108 EOF
 109 $ chmod +x $HOME/git\-shell\-commands/cvs
 110 .fi
 111 .if n \{\
 112 .RE
 113 .\}
 114 .sp
 115 .SH "SEE ALSO"
 116 .sp
 117 ssh(1), \fBgit-daemon\fR(1), contrib/git\-shell\-commands/README
 118 .SH "GIT"
 119 .sp
 120 Part of the \fBgit\fR(1) suite