2 13b2bc37 2022-10-23 stsp .\" Copyright (c) 2022 Stefan Sperling <stsp@openbsd.org>
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.
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.
16 13b2bc37 2022-10-23 stsp .Dd $Mdocdate$
17 13b2bc37 2022-10-23 stsp .Dt GOTD.CONF 5
20 13b2bc37 2022-10-23 stsp .Nm gotd.conf
21 13b2bc37 2022-10-23 stsp .Nd gotd configuration file
22 13b2bc37 2022-10-23 stsp .Sh DESCRIPTION
24 13b2bc37 2022-10-23 stsp is the run-time configuration file for
25 13b2bc37 2022-10-23 stsp .Xr gotd 8 .
27 13b2bc37 2022-10-23 stsp The file format is line-based, with one configuration directive per line.
28 13b2bc37 2022-10-23 stsp Any lines beginning with a
30 13b2bc37 2022-10-23 stsp are treated as comments and ignored.
31 13b2bc37 2022-10-23 stsp .Sh GLOBAL CONFIGURATION
32 13b2bc37 2022-10-23 stsp The available global configuration directives are as follows:
33 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds
34 40b85cca 2023-01-03 stsp .It Ic connection Ar option
35 40b85cca 2023-01-03 stsp Set the specified options and limits for connections to the
37 40b85cca 2023-01-03 stsp unix socket.
40 40b85cca 2023-01-03 stsp .Ic connection
41 40b85cca 2023-01-03 stsp directive may be specified multiple times, and multiple
43 40b85cca 2023-01-03 stsp arguments may be specified within curly braces:
45 40b85cca 2023-01-03 stsp .Ic connection Brq Ar ...
47 40b85cca 2023-01-03 stsp Each option should only be specified once.
48 40b85cca 2023-01-03 stsp If a given option is listed multiple times, the last line which sets this
49 40b85cca 2023-01-03 stsp option wins.
51 40b85cca 2023-01-03 stsp Valid connection options are:
52 40b85cca 2023-01-03 stsp .Bl -tag -width Ds
53 40b85cca 2023-01-03 stsp .It Ic request timeout Ar seconds
54 40b85cca 2023-01-03 stsp Specify the inactivity timeout for operations between client and server.
55 40b85cca 2023-01-03 stsp If this timeout is exceeded while a Git protocol request is being processed,
56 40b85cca 2023-01-03 stsp the request will be aborted and the connection will be terminated.
58 2be11cde 2023-01-03 op The timeout value may also have a suffix indicating its unit of measure.
59 2be11cde 2023-01-03 op Supported suffixes are:
61 2be11cde 2023-01-03 op .Bl -tag -compact -width tenletters
62 2be11cde 2023-01-03 op .It Ar s No or Ar S
64 2be11cde 2023-01-03 op .It Ar m No or Ar M
66 2be11cde 2023-01-03 op .It Ar h No or Ar H
70 2be11cde 2023-01-03 op The default timeout is 1h (3600 seconds, one hour).
71 40b85cca 2023-01-03 stsp This should only be changed if legitimate requests are exceeding the default
72 40b85cca 2023-01-03 stsp timeout for some reason, such as the server spending an extraordinary
73 40b85cca 2023-01-03 stsp amount of time generating a pack file.
74 40b85cca 2023-01-03 stsp .It Ic limit Ic user Ar identity Ar number
75 40b85cca 2023-01-03 stsp Limit the maximum amount of concurrent connections by the user with
76 40b85cca 2023-01-03 stsp the username
77 40b85cca 2023-01-03 stsp .Ar identity
79 40b85cca 2023-01-03 stsp .Ar number .
80 40b85cca 2023-01-03 stsp Numeric user IDs are also accepted.
82 40b85cca 2023-01-03 stsp The default per-user limit is 4.
83 40b85cca 2023-01-03 stsp This should only be changed if concurrent connections from a given user are
84 40b85cca 2023-01-03 stsp expected to exceed the default limit, for example if an anonymous user
85 40b85cca 2023-01-03 stsp is granted read access and many concurrent connections will share this
86 40b85cca 2023-01-03 stsp anonymous user identity.
88 83577462 2023-01-05 stsp .It Ic listen on Ar path
89 13b2bc37 2022-10-23 stsp Set the path to the unix socket which
91 13b2bc37 2022-10-23 stsp should listen on.
92 13b2bc37 2022-10-23 stsp If not specified, the path
93 13b2bc37 2022-10-23 stsp .Pa /var/run/gotd.sock
94 13b2bc37 2022-10-23 stsp will be used.
95 13b2bc37 2022-10-23 stsp .It Ic user Ar user
98 13b2bc37 2022-10-23 stsp which will run
99 13b2bc37 2022-10-23 stsp .Xr gotd 8 .
102 eec68231 2022-12-14 stsp requires root privileges in order to create its unix socket.
103 13b2bc37 2022-10-23 stsp Afterwards,
105 13b2bc37 2022-10-23 stsp drops privileges to the specified
107 13b2bc37 2022-10-23 stsp If not specified, the user _gotd will be used.
109 13b2bc37 2022-10-23 stsp .Sh REPOSITORY CONFIGURATION
110 13b2bc37 2022-10-23 stsp At least one repository context must exist for
112 13b2bc37 2022-10-23 stsp to function.
113 0ccf3acb 2022-11-16 stsp For each repository, access rules must be configured using the
117 0ccf3acb 2022-11-16 stsp configuration directives.
118 0ccf3acb 2022-11-16 stsp Multiple access rules can be specified, and the last matching rule
119 0ccf3acb 2022-11-16 stsp determines the action taken.
120 0ccf3acb 2022-11-16 stsp If no rule matches, access to the repository is denied.
122 13b2bc37 2022-10-23 stsp A repository context is declared with a unique
124 13b2bc37 2022-10-23 stsp followed by repository-specific configuration directives inside curly braces:
126 13b2bc37 2022-10-23 stsp .Ic repository Ar name Brq ...
131 13b2bc37 2022-10-23 stsp clients can connect to a repository by including the repository's unique
133 13b2bc37 2022-10-23 stsp in the request URL.
134 13b2bc37 2022-10-23 stsp Clients appending the string
138 13b2bc37 2022-10-23 stsp will also be accepted.
140 13b2bc37 2022-10-23 stsp If desired, the
142 13b2bc37 2022-10-23 stsp may contain path-separators,
144 13b2bc37 2022-10-23 stsp to expose repositories as part of a virtual client-visible directory hierarchy.
146 13b2bc37 2022-10-23 stsp The available repository configuration directives are as follows:
147 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds
148 0ccf3acb 2022-11-16 stsp .It Ic deny Ar identity
149 0ccf3acb 2022-11-16 stsp Deny repository access to users with the username
150 0ccf3acb 2022-11-16 stsp .Ar identity .
151 0ccf3acb 2022-11-16 stsp Group names may be matched by prepending a colon
154 0ccf3acb 2022-11-16 stsp .Ar identity .
155 0ccf3acb 2022-11-16 stsp Numeric IDs are also accepted.
156 13b2bc37 2022-10-23 stsp .It Ic path Ar path
157 13b2bc37 2022-10-23 stsp Set the path to the Git repository.
158 3b706203 2023-01-02 stsp Must be specified.
159 0ccf3acb 2022-11-16 stsp .It Ic permit Ar mode Ar identity
160 0ccf3acb 2022-11-16 stsp Permit repository access to users with the username
161 0ccf3acb 2022-11-16 stsp .Ar identity .
164 0ccf3acb 2022-11-16 stsp argument must be set to either
166 0ccf3acb 2022-11-16 stsp for read-only access,
169 0ccf3acb 2022-11-16 stsp for read-write access.
170 0ccf3acb 2022-11-16 stsp Group names may be matched by prepending a colon
173 0ccf3acb 2022-11-16 stsp .Ar identity .
174 0ccf3acb 2022-11-16 stsp Numeric IDs are also accepted.
175 9afa3de2 2023-04-04 stsp .It Ic protect Brq Ar ...
177 9afa3de2 2023-04-04 stsp .Cm protect
178 9afa3de2 2023-04-04 stsp directive may be used to protect branches and tags in a repository
179 9afa3de2 2023-04-04 stsp from being overwritten by potentially destructive client-side commands,
180 9afa3de2 2023-04-04 stsp such as when
181 9afa3de2 2023-04-04 stsp .Cm got send -f
183 9afa3de2 2023-04-04 stsp .Cm git push -f
184 9afa3de2 2023-04-04 stsp are used to change the history of a branch.
186 9afa3de2 2023-04-04 stsp To build a set of protected branches and tags, multiple
187 9afa3de2 2023-04-04 stsp .Ic protect
188 9afa3de2 2023-04-04 stsp directives may be specified per repository and
190 9afa3de2 2023-04-04 stsp .Ic protect
191 9afa3de2 2023-04-04 stsp directive parameters may be specified within curly braces.
193 9afa3de2 2023-04-04 stsp The available
194 9afa3de2 2023-04-04 stsp .Cm protect
195 9afa3de2 2023-04-04 stsp parameters are as follows:
197 9afa3de2 2023-04-04 stsp .Bl -tag -width Ds
198 9afa3de2 2023-04-04 stsp .It Ic branch Ar name
199 9afa3de2 2023-04-04 stsp Protect the named branch.
200 9afa3de2 2023-04-04 stsp The branch may be created if it does not exist yet.
201 9afa3de2 2023-04-04 stsp Attempts to delete the branch or change its history will be denied.
205 9afa3de2 2023-04-04 stsp does not already begin with
206 9afa3de2 2023-04-04 stsp .Dq refs/heads/
207 9afa3de2 2023-04-04 stsp it will be looked up in the
208 9afa3de2 2023-04-04 stsp .Dq refs/heads/
209 9afa3de2 2023-04-04 stsp reference namespace.
210 9afa3de2 2023-04-04 stsp .It Ic branch Ic namespace Ar namespace
211 9afa3de2 2023-04-04 stsp Protect the given reference namespace, assuming that references in
212 9afa3de2 2023-04-04 stsp this namespace represent branches.
213 9afa3de2 2023-04-04 stsp New branches may be created in the namespace.
214 9afa3de2 2023-04-04 stsp Attempts to change the history of branches or delete them will be denied.
217 9afa3de2 2023-04-04 stsp .Ar namespace
218 9afa3de2 2023-04-04 stsp argument must be absolute, starting with
219 9afa3de2 2023-04-04 stsp .Dq refs/ .
220 9afa3de2 2023-04-04 stsp .It Ic tag Ic namespace Ar namespace
221 9afa3de2 2023-04-04 stsp Protect the given reference namespace, assuming that references in
222 9afa3de2 2023-04-04 stsp this namespace represent tags.
223 9afa3de2 2023-04-04 stsp New tags may be created in the namespace.
224 9afa3de2 2023-04-04 stsp Attempts to change or delete existing tags will be denied.
227 9afa3de2 2023-04-04 stsp .Ar namespace
228 9afa3de2 2023-04-04 stsp argument must be absolute, starting with
229 9afa3de2 2023-04-04 stsp .Dq refs/ .
232 9afa3de2 2023-04-04 stsp The special reference namespaces
233 9afa3de2 2023-04-04 stsp .Dq refs/got/
235 9afa3de2 2023-04-04 stsp .Dq refs/remotes/
236 9afa3de2 2023-04-04 stsp do not need to be listed in
238 9afa3de2 2023-04-04 stsp These namespaces are always protected and even attempts to create new
239 9afa3de2 2023-04-04 stsp references in these namespaces will always be denied.
242 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds -compact
243 13b2bc37 2022-10-23 stsp .It Pa /etc/gotd.conf
244 13b2bc37 2022-10-23 stsp Location of the
246 13b2bc37 2022-10-23 stsp configuration file.
248 13b2bc37 2022-10-23 stsp .Sh EXAMPLES
249 13b2bc37 2022-10-23 stsp .Bd -literal -offset indent
250 6f854dde 2023-01-04 stsp # Run as the default user:
253 83577462 2023-01-05 stsp # Listen on the default socket:
254 83577462 2023-01-05 stsp listen on "/var/run/gotd.sock"
256 13b2bc37 2022-10-23 stsp # This repository can be accessed via ssh://user@example.com/src
257 13b2bc37 2022-10-23 stsp repository "src" {
258 13b2bc37 2022-10-23 stsp path "/var/git/src.git"
259 0ccf3acb 2022-11-16 stsp permit rw flan_hacker
260 0ccf3acb 2022-11-16 stsp permit rw :developers
261 0ccf3acb 2022-11-16 stsp permit ro anonymous
263 9afa3de2 2023-04-04 stsp protect branch "main"
264 9afa3de2 2023-04-04 stsp protect tag namespace "refs/tags/"
267 13b2bc37 2022-10-23 stsp # This repository can be accessed via
268 13b2bc37 2022-10-23 stsp # ssh://user@example.com/openbsd/ports
269 13b2bc37 2022-10-23 stsp repository "openbsd/ports" {
270 13b2bc37 2022-10-23 stsp path "/var/git/ports.git"
271 0ccf3acb 2022-11-16 stsp permit rw :porters
272 0ccf3acb 2022-11-16 stsp permit ro anonymous
273 0ccf3acb 2022-11-16 stsp deny flan_hacker
276 9afa3de2 2023-04-04 stsp branch "main"
277 9afa3de2 2023-04-04 stsp tag namespace "refs/tags/"
281 40b85cca 2023-01-03 stsp # Use a larger request timeout value:
282 2be11cde 2023-01-03 op connection request timeout 2h
284 40b85cca 2023-01-03 stsp # Some users are granted a higher concurrent connection limit:
285 40b85cca 2023-01-03 stsp connection {
286 40b85cca 2023-01-03 stsp limit user flan_hacker 16
287 40b85cca 2023-01-03 stsp limit user anonymous 32
290 13b2bc37 2022-10-23 stsp .Sh SEE ALSO
291 13b2bc37 2022-10-23 stsp .Xr got 1 ,
292 13b2bc37 2022-10-23 stsp .Xr gotsh 1 ,
