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 13b2bc37 2022-10-23 stsp .It Ic unix_socket 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 unix_group Ar group
98 13b2bc37 2022-10-23 stsp defined in the
100 13b2bc37 2022-10-23 stsp file, which is allowed to access
103 13b2bc37 2022-10-23 stsp .Xr gotsh 1 .
106 13b2bc37 2022-10-23 stsp user must be a secondary member of this group.
107 13b2bc37 2022-10-23 stsp If not specified, the group _gotsh will be used.
108 13b2bc37 2022-10-23 stsp .It Ic user Ar user
111 13b2bc37 2022-10-23 stsp which will run
112 13b2bc37 2022-10-23 stsp .Xr gotd 8 .
115 eec68231 2022-12-14 stsp requires root privileges in order to create its unix socket.
116 13b2bc37 2022-10-23 stsp Afterwards,
118 13b2bc37 2022-10-23 stsp drops privileges to the specified
120 13b2bc37 2022-10-23 stsp If not specified, the user _gotd will be used.
122 13b2bc37 2022-10-23 stsp .Sh REPOSITORY CONFIGURATION
123 13b2bc37 2022-10-23 stsp At least one repository context must exist for
125 13b2bc37 2022-10-23 stsp to function.
126 0ccf3acb 2022-11-16 stsp For each repository, access rules must be configured using the
130 0ccf3acb 2022-11-16 stsp configuration directives.
131 0ccf3acb 2022-11-16 stsp Multiple access rules can be specified, and the last matching rule
132 0ccf3acb 2022-11-16 stsp determines the action taken.
133 0ccf3acb 2022-11-16 stsp If no rule matches, access to the repository is denied.
135 13b2bc37 2022-10-23 stsp A repository context is declared with a unique
137 13b2bc37 2022-10-23 stsp followed by repository-specific configuration directives inside curly braces:
139 13b2bc37 2022-10-23 stsp .Ic repository Ar name Brq ...
144 13b2bc37 2022-10-23 stsp clients can connect to a repository by including the repository's unique
146 13b2bc37 2022-10-23 stsp in the request URL.
147 13b2bc37 2022-10-23 stsp Clients appending the string
151 13b2bc37 2022-10-23 stsp will also be accepted.
153 13b2bc37 2022-10-23 stsp If desired, the
155 13b2bc37 2022-10-23 stsp may contain path-separators,
157 13b2bc37 2022-10-23 stsp to expose repositories as part of a virtual client-visible directory hierarchy.
159 13b2bc37 2022-10-23 stsp The available repository configuration directives are as follows:
160 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds
161 0ccf3acb 2022-11-16 stsp .It Ic deny Ar identity
162 0ccf3acb 2022-11-16 stsp Deny repository access to users with the username
163 0ccf3acb 2022-11-16 stsp .Ar identity .
164 0ccf3acb 2022-11-16 stsp Group names may be matched by prepending a colon
167 0ccf3acb 2022-11-16 stsp .Ar identity .
168 0ccf3acb 2022-11-16 stsp Numeric IDs are also accepted.
169 13b2bc37 2022-10-23 stsp .It Ic path Ar path
170 13b2bc37 2022-10-23 stsp Set the path to the Git repository.
171 3b706203 2023-01-02 stsp Must be specified.
172 0ccf3acb 2022-11-16 stsp .It Ic permit Ar mode Ar identity
173 0ccf3acb 2022-11-16 stsp Permit repository access to users with the username
174 0ccf3acb 2022-11-16 stsp .Ar identity .
177 0ccf3acb 2022-11-16 stsp argument must be set to either
179 0ccf3acb 2022-11-16 stsp for read-only access,
182 0ccf3acb 2022-11-16 stsp for read-write access.
183 0ccf3acb 2022-11-16 stsp Group names may be matched by prepending a colon
186 0ccf3acb 2022-11-16 stsp .Ar identity .
187 0ccf3acb 2022-11-16 stsp Numeric IDs are also accepted.
190 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds -compact
191 13b2bc37 2022-10-23 stsp .It Pa /etc/gotd.conf
192 13b2bc37 2022-10-23 stsp Location of the
194 13b2bc37 2022-10-23 stsp configuration file.
196 13b2bc37 2022-10-23 stsp .Sh EXAMPLES
197 13b2bc37 2022-10-23 stsp .Bd -literal -offset indent
198 13b2bc37 2022-10-23 stsp # Default unix_group and user values:
199 13b2bc37 2022-10-23 stsp unix_group _gotsh
202 13b2bc37 2022-10-23 stsp # This repository can be accessed via ssh://user@example.com/src
203 13b2bc37 2022-10-23 stsp repository "src" {
204 13b2bc37 2022-10-23 stsp path "/var/git/src.git"
205 0ccf3acb 2022-11-16 stsp permit rw flan_hacker
206 0ccf3acb 2022-11-16 stsp permit rw :developers
207 0ccf3acb 2022-11-16 stsp permit ro anonymous
210 13b2bc37 2022-10-23 stsp # This repository can be accessed via
211 13b2bc37 2022-10-23 stsp # ssh://user@example.com/openbsd/ports
212 13b2bc37 2022-10-23 stsp repository "openbsd/ports" {
213 13b2bc37 2022-10-23 stsp path "/var/git/ports.git"
214 0ccf3acb 2022-11-16 stsp permit rw :porters
215 0ccf3acb 2022-11-16 stsp permit ro anonymous
216 0ccf3acb 2022-11-16 stsp deny flan_hacker
219 40b85cca 2023-01-03 stsp # Use a larger request timeout value:
220 2be11cde 2023-01-03 op connection request timeout 2h
222 40b85cca 2023-01-03 stsp # Some users are granted a higher concurrent connection limit:
223 40b85cca 2023-01-03 stsp connection {
224 40b85cca 2023-01-03 stsp limit user flan_hacker 16
225 40b85cca 2023-01-03 stsp limit user anonymous 32
228 13b2bc37 2022-10-23 stsp .Sh SEE ALSO
229 13b2bc37 2022-10-23 stsp .Xr got 1 ,
230 13b2bc37 2022-10-23 stsp .Xr gotsh 1 ,
231 13b2bc37 2022-10-23 stsp .Xr group 5 ,
