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