Game of Trees Repos

Blame

Date:: Sun Oct 23 14:38:32 2022 UTC
Message:: introduce gotd(8), a Git repository server reachable via ssh(1) This is an initial barebones implementation which provides the absolute minimum of functionality required to serve got(1) and git(1) clients. Basic fetch/send functionality has been tested and seems to work here, but this server is not yet expected to be stable. More testing is welcome. See the man pages for setup instructions. The current design uses one reader and one writer process per repository, which will have to be extended to N readers and N writers in the future. At startup, each process will chroot(2) into its assigned repository. This works because gotd(8) can only be started as root, and will then fork+exec, chroot, and privdrop. At present the parent process runs with the following pledge(2) promises: "stdio rpath wpath cpath proc getpw sendfd recvfd fattr flock unix unveil" The parent is the only process able to modify the repository in a way that becomes visible to Git clients. The parent uses unveil(2) to restrict its view of the filesystem to /tmp and the repositories listed in the configuration file gotd.conf(5). Per-repository chroot(2) processes use "stdio rpath sendfd recvfd". The writer defers to the parent for modifying references in the repository to point at newly uploaded commits. The reader is fine without such help, because Git repositories can be read without having to create any lock-files. gotd(8) requires a dedicated user ID, which should own repositories on the filesystem, and a separate secondary group, which should not have filesystem-level repository access, and must be allowed access to the gotd(8) socket. To obtain Git repository access, users must be members of this secondary group, and must have their login shell set to gotsh(1). gotsh(1) connects to the gotd(8) socket and speaks Git-protocol towards the client on the other end of the SSH connection. gotsh(1) is not an interactive command shell. At present, authenticated clients are granted read/write access to all repositories and all references (except for the "refs/got/" and the "refs/remotes/" namespaces, which are already being protected from modification). While complicated access control mechanism are not a design goal, making it possible to safely offer anonymous Git repository access over ssh(1) is on the road map.
Actions:: History | Blob | Raw File

  1 3efd8e31 2022-10-23 thomas .\"
  2 3efd8e31 2022-10-23 thomas .\" Copyright (c) 2022 Stefan Sperling <stsp@openbsd.org>
  3 3efd8e31 2022-10-23 thomas .\"
  4 3efd8e31 2022-10-23 thomas .\" Permission to use, copy, modify, and distribute this software for any
  5 3efd8e31 2022-10-23 thomas .\" purpose with or without fee is hereby granted, provided that the above
  6 3efd8e31 2022-10-23 thomas .\" copyright notice and this permission notice appear in all copies.
  7 3efd8e31 2022-10-23 thomas .\"
  8 3efd8e31 2022-10-23 thomas .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  9 3efd8e31 2022-10-23 thomas .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 10 3efd8e31 2022-10-23 thomas .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 11 3efd8e31 2022-10-23 thomas .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 12 3efd8e31 2022-10-23 thomas .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 13 3efd8e31 2022-10-23 thomas .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 14 3efd8e31 2022-10-23 thomas .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 15 3efd8e31 2022-10-23 thomas .\"
 16 3efd8e31 2022-10-23 thomas .Dd $Mdocdate$
 17 3efd8e31 2022-10-23 thomas .Dt GOTD.CONF 5
 18 3efd8e31 2022-10-23 thomas .Os
 19 3efd8e31 2022-10-23 thomas .Sh NAME
 20 3efd8e31 2022-10-23 thomas .Nm gotd.conf
 21 3efd8e31 2022-10-23 thomas .Nd gotd configuration file
 22 3efd8e31 2022-10-23 thomas .Sh DESCRIPTION
 23 3efd8e31 2022-10-23 thomas .Nm
 24 3efd8e31 2022-10-23 thomas is the run-time configuration file for
 25 3efd8e31 2022-10-23 thomas .Xr gotd 8 .
 26 3efd8e31 2022-10-23 thomas .Pp
 27 3efd8e31 2022-10-23 thomas The file format is line-based, with one configuration directive per line.
 28 3efd8e31 2022-10-23 thomas Any lines beginning with a
 29 3efd8e31 2022-10-23 thomas .Sq #
 30 3efd8e31 2022-10-23 thomas are treated as comments and ignored.
 31 3efd8e31 2022-10-23 thomas .Sh GLOBAL CONFIGURATION
 32 3efd8e31 2022-10-23 thomas The available global configuration directives are as follows:
 33 3efd8e31 2022-10-23 thomas .Bl -tag -width Ds
 34 3efd8e31 2022-10-23 thomas .It Ic unix_socket Ar path
 35 3efd8e31 2022-10-23 thomas Set the path to the unix socket which
 36 3efd8e31 2022-10-23 thomas .Xr gotd 8
 37 3efd8e31 2022-10-23 thomas should listen on.
 38 3efd8e31 2022-10-23 thomas If not specified, the path
 39 3efd8e31 2022-10-23 thomas .Pa /var/run/gotd.sock
 40 3efd8e31 2022-10-23 thomas will be used.
 41 3efd8e31 2022-10-23 thomas .It Ic unix_group Ar group
 42 3efd8e31 2022-10-23 thomas Set the
 43 3efd8e31 2022-10-23 thomas .Ar group ,
 44 3efd8e31 2022-10-23 thomas defined in the
 45 3efd8e31 2022-10-23 thomas .Xr group 5
 46 3efd8e31 2022-10-23 thomas file, which is allowed to access
 47 3efd8e31 2022-10-23 thomas .Xr gotd 8
 48 3efd8e31 2022-10-23 thomas via
 49 3efd8e31 2022-10-23 thomas .Xr gotsh 1 .
 50 3efd8e31 2022-10-23 thomas The
 51 3efd8e31 2022-10-23 thomas .Xr gotd 8
 52 3efd8e31 2022-10-23 thomas user must be a secondary member of this group.
 53 3efd8e31 2022-10-23 thomas If not specified, the group _gotsh will be used.
 54 3efd8e31 2022-10-23 thomas .It Ic user Ar user
 55 3efd8e31 2022-10-23 thomas Set the
 56 3efd8e31 2022-10-23 thomas .Ar user
 57 3efd8e31 2022-10-23 thomas which will run
 58 3efd8e31 2022-10-23 thomas .Xr gotd 8 .
 59 3efd8e31 2022-10-23 thomas Initially,
 60 3efd8e31 2022-10-23 thomas .Xr gotd 8
 61 3efd8e31 2022-10-23 thomas requires root privileges in order to create its unix socket and start
 62 3efd8e31 2022-10-23 thomas child processes in a
 63 3efd8e31 2022-10-23 thomas .Xr chroot 2
 64 3efd8e31 2022-10-23 thomas environment.
 65 3efd8e31 2022-10-23 thomas Afterwards,
 66 3efd8e31 2022-10-23 thomas .Xr gotd 8
 67 3efd8e31 2022-10-23 thomas drops privileges to the specified
 68 3efd8e31 2022-10-23 thomas .Ar user .
 69 3efd8e31 2022-10-23 thomas If not specified, the user _gotd will be used.
 70 3efd8e31 2022-10-23 thomas .El
 71 3efd8e31 2022-10-23 thomas .Sh REPOSITORY CONFIGURATION
 72 3efd8e31 2022-10-23 thomas At least one repository context must exist for
 73 3efd8e31 2022-10-23 thomas .Xr gotd 8
 74 3efd8e31 2022-10-23 thomas to function.
 75 3efd8e31 2022-10-23 thomas .Pp
 76 3efd8e31 2022-10-23 thomas A repository context is declared with a unique
 77 3efd8e31 2022-10-23 thomas .Ar name ,
 78 3efd8e31 2022-10-23 thomas followed by repository-specific configuration directives inside curly braces:
 79 3efd8e31 2022-10-23 thomas .Pp
 80 3efd8e31 2022-10-23 thomas .Ic repository Ar name Brq ...
 81 3efd8e31 2022-10-23 thomas .Pp
 82 3efd8e31 2022-10-23 thomas .Xr got 1
 83 3efd8e31 2022-10-23 thomas and
 84 3efd8e31 2022-10-23 thomas .Xr git 1
 85 3efd8e31 2022-10-23 thomas clients can connect to a repository by including the repository's unique
 86 3efd8e31 2022-10-23 thomas .Ar name
 87 3efd8e31 2022-10-23 thomas in the request URL.
 88 3efd8e31 2022-10-23 thomas Clients appending the string
 89 3efd8e31 2022-10-23 thomas .Dq .git
 90 3efd8e31 2022-10-23 thomas to the
 91 3efd8e31 2022-10-23 thomas .Ar name
 92 3efd8e31 2022-10-23 thomas will also be accepted.
 93 3efd8e31 2022-10-23 thomas .Pp
 94 3efd8e31 2022-10-23 thomas If desired, the
 95 3efd8e31 2022-10-23 thomas .Ar name
 96 3efd8e31 2022-10-23 thomas may contain path-separators,
 97 3efd8e31 2022-10-23 thomas .Dq / ,
 98 3efd8e31 2022-10-23 thomas to expose repositories as part of a virtual client-visible directory hierarchy.
 99 3efd8e31 2022-10-23 thomas .Pp
100 3efd8e31 2022-10-23 thomas The available repository configuration directives are as follows:
101 3efd8e31 2022-10-23 thomas .Bl -tag -width Ds
102 3efd8e31 2022-10-23 thomas .It Ic path Ar path
103 3efd8e31 2022-10-23 thomas Set the path to the Git repository.
104 3efd8e31 2022-10-23 thomas .EL
105 3efd8e31 2022-10-23 thomas .Sh FILES
106 3efd8e31 2022-10-23 thomas .Bl -tag -width Ds -compact
107 3efd8e31 2022-10-23 thomas .It Pa /etc/gotd.conf
108 3efd8e31 2022-10-23 thomas Location of the
109 3efd8e31 2022-10-23 thomas .Nm
110 3efd8e31 2022-10-23 thomas configuration file.
111 3efd8e31 2022-10-23 thomas .El
112 3efd8e31 2022-10-23 thomas .Sh EXAMPLES
113 3efd8e31 2022-10-23 thomas .Bd -literal -offset indent
114 3efd8e31 2022-10-23 thomas # Default unix_group and user values:
115 3efd8e31 2022-10-23 thomas unix_group _gotsh
116 3efd8e31 2022-10-23 thomas user _gotd
117 3efd8e31 2022-10-23 thomas 
118 3efd8e31 2022-10-23 thomas # This repository can be accessed via ssh://user@example.com/src
119 3efd8e31 2022-10-23 thomas repository "src" {
120 3efd8e31 2022-10-23 thomas 	path "/var/git/src.git"
121 3efd8e31 2022-10-23 thomas }
122 3efd8e31 2022-10-23 thomas 
123 3efd8e31 2022-10-23 thomas # This repository can be accessed via
124 3efd8e31 2022-10-23 thomas # ssh://user@example.com/openbsd/ports
125 3efd8e31 2022-10-23 thomas repository "openbsd/ports" {
126 3efd8e31 2022-10-23 thomas 	path "/var/git/ports.git"
127 3efd8e31 2022-10-23 thomas }
128 3efd8e31 2022-10-23 thomas .Ed
129 3efd8e31 2022-10-23 thomas .Sh SEE ALSO
130 3efd8e31 2022-10-23 thomas .Xr got 1 ,
131 3efd8e31 2022-10-23 thomas .Xr gotsh 1 ,
132 3efd8e31 2022-10-23 thomas .Xr group 5 ,
133 3efd8e31 2022-10-23 thomas .Xr gotd 8