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.
177 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds -compact
178 13b2bc37 2022-10-23 stsp .It Pa /etc/gotd.conf
179 13b2bc37 2022-10-23 stsp Location of the
181 13b2bc37 2022-10-23 stsp configuration file.
183 13b2bc37 2022-10-23 stsp .Sh EXAMPLES
184 13b2bc37 2022-10-23 stsp .Bd -literal -offset indent
185 6f854dde 2023-01-04 stsp # Run as the default user:
188 83577462 2023-01-05 stsp # Listen on the default socket:
189 83577462 2023-01-05 stsp listen on "/var/run/gotd.sock"
191 13b2bc37 2022-10-23 stsp # This repository can be accessed via ssh://user@example.com/src
192 13b2bc37 2022-10-23 stsp repository "src" {
193 13b2bc37 2022-10-23 stsp path "/var/git/src.git"
194 0ccf3acb 2022-11-16 stsp permit rw flan_hacker
195 0ccf3acb 2022-11-16 stsp permit rw :developers
196 0ccf3acb 2022-11-16 stsp permit ro anonymous
199 13b2bc37 2022-10-23 stsp # This repository can be accessed via
200 13b2bc37 2022-10-23 stsp # ssh://user@example.com/openbsd/ports
201 13b2bc37 2022-10-23 stsp repository "openbsd/ports" {
202 13b2bc37 2022-10-23 stsp path "/var/git/ports.git"
203 0ccf3acb 2022-11-16 stsp permit rw :porters
204 0ccf3acb 2022-11-16 stsp permit ro anonymous
205 0ccf3acb 2022-11-16 stsp deny flan_hacker
208 40b85cca 2023-01-03 stsp # Use a larger request timeout value:
209 2be11cde 2023-01-03 op connection request timeout 2h
211 40b85cca 2023-01-03 stsp # Some users are granted a higher concurrent connection limit:
212 40b85cca 2023-01-03 stsp connection {
213 40b85cca 2023-01-03 stsp limit user flan_hacker 16
214 40b85cca 2023-01-03 stsp limit user anonymous 32
217 13b2bc37 2022-10-23 stsp .Sh SEE ALSO
218 13b2bc37 2022-10-23 stsp .Xr got 1 ,
219 13b2bc37 2022-10-23 stsp .Xr gotsh 1 ,