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