.\"
.\" Copyright (c) 2022 Stefan Sperling
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt GOTSH 1
.Os
.Sh NAME
.Nm gotsh
.Nd Game of Trees Shell
.Sh SYNOPSIS
.Nm Fl c Sq Cm git-receive-pack Ar repository-path
.Nm Fl c Sq Cm git-upload-pack Ar repository-path
.Sh DESCRIPTION
.Nm
is the network-facing interface to
.Xr gotd 8 .
It implements the server-side part of the Git network protocol used by
.Xr git 1
and
.Xr got 1 .
.Pp
.Nm
is not an interactive shell.
.Nm
is intended to be configured as the login shell of Git repository
user accounts on servers running
.Xr gotd 8 .
If users require a different login shell,
.Nm
can be installed in the command search path under the names
.Cm git-receive-pack
and
.Cm git-upload-pack ,
or
.Xr gitwrapper 1
can be used to select the appropriate command to run automatically.
.Pp
The users can then interact with
.Xr gotd 8
over the network.
When users invoke commands such as
.Cm got send
and
.Cm got fetch
on client machines,
.Xr got 1
will connect to the server with
.Xr ssh 1 .
.Nm
will facilitate communication between
.Xr gotd 8
running on the server machine and the
.Xr got 1
or
.Xr git 1
program running on the client machine.
.Pp
Users running
.Nm
should not have access to Git repositories by means other than
accessing the unix socket of
.Xr gotd 8
via
.Nm .
.Pp
It is recommended to restrict
.Xr ssh 1
features available to users of
.Nm .
See the
.Sx EXAMPLES
section for details.
.Sh ENVIRONMENT
.Bl -tag -width GOTD_UNIX_SOCKET
.It Ev GOTD_UNIX_SOCKET
Set the path to the unix socket which
.Xr gotd 8
is listening on.
If not specified, the default path
.Pa /var/run/gotd.sock
will be used.
.El
.Sh EXAMPLES
.Xr sshd_config 5
directives such as the following are recommended to protect the server
machine and any systems reachable from it, especially if anonymous users
are allowed to connect:
.Bd -literal -offset indent
Match User developer
    DisableForwarding yes
    PermitTTY no
.Ed
.Pp
It can be convenient to add all relevant users to a common group, such as
.Dq developers ,
and then use this group as the Match criteria:
.Bd -literal -offset indent
Match Group developers
    DisableForwarding yes
    PermitTTY no
.Ed
.Pp
Anonymous users can be given public read-only access by using a
.Xr gotd.conf 5
access rule such as the following:
.Bd -literal -offset indent
repository "public" {
	path "/var/git/public.git"
	permit ro anonymous
}
.Ed
.Pp
The anonymous user account should have a publicly known password, or can be
set up with an empty password in which case the user's
.Xr vipw 8
entry would look similar to this example:
.Bd -literal
anonymous::1002:1002::0:0:Anonymous:/home/anonymous:/usr/local/bin/gotsh
.Ed
.Pp
Use of an empty password must be explicitly allowed in
.Xr sshd_config 5 :
.Bd -literal -offset indent
Match User anonymous
    PasswordAuthentication yes
    PermitEmptyPasswords yes
    DisableForwarding yes
    PermitTTY no
.Ed
.Sh SEE ALSO
.Xr gitwrapper 1 ,
.Xr got 1 ,
.Xr ssh 1 ,
.Xr gotd.conf 5 ,
.Xr sshd_config 5 ,
.Xr gotd 8
.Sh AUTHORS
.An Stefan Sperling Aq Mt stsp@openbsd.org