gotsh/gotsh.1

   1 .\"
   2 .\" Copyright (c) 2022 Stefan Sperling
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .Dd $Mdocdate$
  17 .Dt GOTSH 1
  18 .Os
  19 .Sh NAME
  20 .Nm gotsh
  21 .Nd Game of Trees Shell
  22 .Sh SYNOPSIS
  23 .Nm Fl c Sq Cm git-receive-pack Ar repository-path
  24 .Nm Fl c Sq Cm git-upload-pack Ar repository-path
  25 .Sh DESCRIPTION
  26 .Nm
  27 is the network-facing interface to
  28 .Xr gotd 8 .
  29 It implements the server-side part of the Git network protocol used by
  30 .Xr git 1
  31 and
  32 .Xr got 1 .
  33 .Pp
  34 .Nm
  35 is not an interactive shell.
  36 .Nm
  37 is intended to be configured as the login shell of Git repository
  38 user accounts on servers running
  39 .Xr gotd 8 .
  40 If users require a different login shell,
  41 .Nm
  42 can be installed in the command search path under the names
  43 .Cm git-receive-pack
  44 and
  45 .Cm git-upload-pack ,
  46 or
  47 .Xr gitwrapper 1
  48 can be used to select the appropriate command to run automatically.
  49 .Pp
  50 The users can then interact with
  51 .Xr gotd 8
  52 over the network.
  53 When users invoke commands such as
  54 .Cm got send
  55 and
  56 .Cm got fetch
  57 on client machines,
  58 .Xr got 1
  59 will connect to the server with
  60 .Xr ssh 1 .
  61 .Nm
  62 will facilitate communication between
  63 .Xr gotd 8
  64 running on the server machine and the
  65 .Xr got 1
  66 or
  67 .Xr git 1
  68 program running on the client machine.
  69 .Pp
  70 Users running
  71 .Nm
  72 should not have access to Git repositories by means other than
  73 accessing the unix socket of
  74 .Xr gotd 8
  75 via
  76 .Nm .
  77 .Pp
  78 It is recommended to restrict
  79 .Xr ssh 1
  80 features available to users of
  81 .Nm .
  82 See the
  83 .Sx EXAMPLES
  84 section for details.
  85 .Sh ENVIRONMENT
  86 .Bl -tag -width GOTD_UNIX_SOCKET
  87 .It Ev GOTD_UNIX_SOCKET
  88 Set the path to the unix socket which
  89 .Xr gotd 8
  90 is listening on.
  91 If not specified, the default path
  92 .Pa /var/run/gotd.sock
  93 will be used.
  94 .El
  95 .Sh EXAMPLES
  96 .Xr sshd_config 5
  97 directives such as the following are recommended to protect the server
  98 machine and any systems reachable from it, especially if anonymous users
  99 are allowed to connect:
 100 .Bd -literal -offset indent
 101 Match User developer
 102     DisableForwarding yes
 103     PermitTTY no
 104 .Ed
 105 .Pp
 106 It can be convenient to add all relevant users to a common group, such as
 107 .Dq developers ,
 108 and then use this group as the Match criteria:
 109 .Bd -literal -offset indent
 110 Match Group developers
 111     DisableForwarding yes
 112     PermitTTY no
 113 .Ed
 114 .Pp
 115 Anonymous users can be given public read-only access by using a
 116 .Xr gotd.conf 5
 117 access rule such as the following:
 118 .Bd -literal -offset indent
 119 repository "public" {
 120         path "/var/git/public.git"
 121         permit ro anonymous
 122 }
 123 .Ed
 124 .Pp
 125 The anonymous user account should have a publicly known password, or can be
 126 set up with an empty password in which case the user's
 127 .Xr vipw 8
 128 entry would look similar to this example:
 129 .Bd -literal
 130 anonymous::1002:1002::0:0:Anonymous:/home/anonymous:/usr/local/bin/gotsh
 131 .Ed
 132 .Pp
 133 Use of an empty password must be explicitly allowed in
 134 .Xr sshd_config 5 :
 135 .Bd -literal -offset indent
 136 Match User anonymous
 137     PasswordAuthentication yes
 138     PermitEmptyPasswords yes
 139     DisableForwarding yes
 140     PermitTTY no
 141 .Ed
 142 .Sh SEE ALSO
 143 .Xr gitwrapper 1 ,
 144 .Xr got 1 ,
 145 .Xr ssh 1 ,
 146 .Xr gotd.conf 5 ,
 147 .Xr sshd_config 5 ,
 148 .Xr gotd 8
 149 .Sh AUTHORS
 150 .An Stefan Sperling Aq Mt stsp@openbsd.org