Blob

Date:
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 | Blame | Raw File
1 Game of Trees (Got) is a version control system which prioritizes ease

2 of use and simplicity over flexibility (https://gameoftrees.org)

4 Got is still under development; it is being developed exclusively

5 on OpenBSD and its target audience are OpenBSD developers. Got is

6 ISC-licensed and was designed with pledge(2) and unveil(2) in mind.

8 Got uses Git repositories to store versioned data. At present, Got

9 supports local version control operations only. Git can be used

10 for any functionality which has not yet been implemented in Got.

11 It will always remain possible to work with both Got and Git on

12 the same repository.

14 To compile the Got client tool suite on OpenBSD, run:

16  $ make obj

17  $ make

18  $ make install

20 This will install the following commands:

22  got, the command line interface

23  tog, an ncurses-based interactive Git repository browser

24  several helper programs from the libexec directory

25  man pages (only installed if building sources from a Got release tarball)

27 A Got release tarball will install files under /usr/local by default.

28 A build started in Got's Git repository will install files under ~/bin.

30 Tests will pass only after 'make install' because they rely on installed

31 binaries in $PATH. Tests in the cmdline directory currently depend on git(1).

32 Tests which use the got clone, fetch, and send commands will fail if

33 'ssh 127.0.0.1' does not succeed non-interactively.

35  $ doas pkg_add git

36  $ make regress

38 To test with packed repositories, run:

40  $ make regress GOT_TEST_PACK=1

42 Because got unveils the /tmp directory by default using the /tmp directory

43 for test data can hide bugs. However, /tmp remains the default because

44 there is no better alternative that works out of the box. In order to

45 store test data in a directory other than /tmp, such as ~/got-test, run:

47  $ mkdir ~/got-test

48  $ make regress GOT_TEST_ROOT=~/got-test

50 Man page files in the Got source tree can be viewed with 'man -l':

52  $ man -l got/got.1

53  $ man -l got/git-repository.5

54  $ man -l got/got-worktree.5

55  $ man -l tog/tog.1

57 EXAMPLES in got.1 contains a quick-start guide for OpenBSD developers.

60 To compile the Got server tool suite on OpenBSD, run:

62  $ make obj

63  $ make server

64  $ make server-install

66 This will install the following commands:

68  gotd, the repository server program

69  gotsh, the login shell for users accessing the server via the network

71 See the following manual page files for information about server setup:

73  $ man -l gotd/gotd.8

74  $ man -l gotd/gotd.conf.5

75  $ man -l gotsh/gotsh.1

78 Game of Trees Web (Gotweb) is a CGI program which displays repository data

79 and is designed to work with httpd(8) and slowcgi(8). It requires the Kristaps

80 Dzonsons kcgi library, version 0.12.0 or greater.

82 To compile gotweb on OpenBSD, run:

84  # pkg_add kcgi

85  $ make web

86  # make web-install

88 This will create the following files:

89   the CGI program /var/www/cgi-bin/gotweb/gotweb

90   helper programs from the libexec directory in /var/www/cgi-bin/gotweb/libexec

91   several template files in /var/www/cgi-bin/gw_tmpl/

92   html, css, and image files in /var/www/htdocs/gotweb/

93   the directory /var/www/got/tmp/

94   man pages (only installed if building sources from a Got release tarball)

96 Documentation is available in manual pages:

98  $ man -l gotweb/gotweb.8

99  $ man -l gotweb/gotweb.conf.5

102 Got can be built with profiling enabled to debug performance issues.

103 Note that profiled builds cannot make use of pledge(2).

104 Profiling should only be enabled for one program at a time. Otherwise,

105 multiple programs will attempt to write to the 'gmon.out' file in the

106 current working directory.

108 For example, to compile got-read-pack with profiling enabled:

110   $ cd libexec/got-read-pack

111   $ make clean

112   $ make PROFILE=1

113   $ make install

115 Running any Got command which ends up using got-read-pack should now

116 produce the file 'gmon.out' in the current working directory.

117 The gprof2dot program can be used to generate a profile graph:

119   $ doas pkg_add gprof2dot graphviz

120   $ gprof ~/bin/got-read-pack gmon.out | gprof2dot | dot -T png > profile.png

122 As another example, to compile gotweb with profiling enabled:

124   $ cd gotweb

125   $ make clean

126   $ make PROFILE=1 gotweb

127   $ make # compile remaining gotweb binaries as usual

128   $ doas make install

129   $ doas chown www /var/www/cgi-bin/gotweb/

131 After loading a gotweb page in the browser, there should now

132 be a gmon.out file next to the gotweb binary:

134 $ ls -l /var/www/cgi-bin/gotweb/

135 total 6088

136 -rw-r--r--  1 www   daemon   427642 Jun 17 22:04 gmon.out

137 -rwxr-xr-x  1 www   www     2630488 Jun 17 22:03 gotweb

138 drwxr-xr-x  2 root  daemon      512 Jun 17 22:03 gw_tmpl

139 drwxr-xr-x  2 root  daemon      512 Jun 17 22:03 libexec

142 Guidelines for reporting problems:

144 All problem/bug reports should include a reproduction recipe in form of a

145 shell script which starts out with an empty repository and runs a series of

146 Got and/or Git commands to trigger the problem, be it a crash or some other

147 undesirable behaviour.

149 The regress/cmdline directory contains plenty of example scripts.

150 An ideal reproduction recipe is written as an xfail ("expected failure")

151 regression test. For a real-world example of an xfail test, see commits

152 4866d0842a2b34812818685aaa31d3e0a966412d and

153 2b496619daecc1f25b1bc0c53e01685030dc2c74 in Got's history.

155 Please take this request very seriously; Ask for help with writing your

156 regression test before asking for your problem to be fixed. Time invested

157 in writing a regression test saves time wasted on back-and-forth discussion

158 about how the problem can be reproduced. A regression test will need to be

159 written in any case to verify a fix and prevent the problem from resurfacing.

161 It is also possible to write test cases in C. Various examples of this

162 exist in the regress/ directory. Most such tests are unit tests; it is

163 unlikely that a problem found during regular usage will require a test

164 to be written in C.

166 Some areas of code, such as the tog UI, are not covered by automated tests.

167 Please always try to find a way to trigger your problem via the command line

168 interface before reporting a problem without a written test case included.

169 If writing an automated test really turns out to be impossible, please

170 explain in very clear terms how the problem can be reproduced.

172 Mail problem reports to: gameoftrees@openbsd.org

175 Guidelines for submitting patches:

177 Mail patches to: gameoftrees@openbsd.org

178 Pull requests via any Git hosting sites will likely be overlooked.

179 Please keep the intended target audience in mind when contributing to Got.

182 Subscribing to the gameoftrees@openbsd.org mailing list:

184 The mailing list is used for patch reviews, bug reports, and user questions.

185 To subscribe, send mail to majordomo@openbsd.org with a message body of:

186 subscribe gameoftrees

188 See https://www.openbsd.org/mail.html for more information.