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 40b85cca 2023-01-03 stsp The default timeout is 3600 seconds (1 hour).
59 40b85cca 2023-01-03 stsp This should only be changed if legitimate requests are exceeding the default
60 40b85cca 2023-01-03 stsp timeout for some reason, such as the server spending an extraordinary
61 40b85cca 2023-01-03 stsp amount of time generating a pack file.
62 40b85cca 2023-01-03 stsp .It Ic limit Ic user Ar identity Ar number
63 40b85cca 2023-01-03 stsp Limit the maximum amount of concurrent connections by the user with
64 40b85cca 2023-01-03 stsp the username
65 40b85cca 2023-01-03 stsp .Ar identity
67 40b85cca 2023-01-03 stsp .Ar number .
68 40b85cca 2023-01-03 stsp Numeric user IDs are also accepted.
70 40b85cca 2023-01-03 stsp The default per-user limit is 4.
71 40b85cca 2023-01-03 stsp This should only be changed if concurrent connections from a given user are
72 40b85cca 2023-01-03 stsp expected to exceed the default limit, for example if an anonymous user
73 40b85cca 2023-01-03 stsp is granted read access and many concurrent connections will share this
74 40b85cca 2023-01-03 stsp anonymous user identity.
76 13b2bc37 2022-10-23 stsp .It Ic unix_socket Ar path
77 13b2bc37 2022-10-23 stsp Set the path to the unix socket which
79 13b2bc37 2022-10-23 stsp should listen on.
80 13b2bc37 2022-10-23 stsp If not specified, the path
81 13b2bc37 2022-10-23 stsp .Pa /var/run/gotd.sock
82 13b2bc37 2022-10-23 stsp will be used.
83 13b2bc37 2022-10-23 stsp .It Ic unix_group Ar group
86 13b2bc37 2022-10-23 stsp defined in the
88 13b2bc37 2022-10-23 stsp file, which is allowed to access
91 13b2bc37 2022-10-23 stsp .Xr gotsh 1 .
94 13b2bc37 2022-10-23 stsp user must be a secondary member of this group.
95 13b2bc37 2022-10-23 stsp If not specified, the group _gotsh will be used.
96 13b2bc37 2022-10-23 stsp .It Ic user Ar user
99 13b2bc37 2022-10-23 stsp which will run
100 13b2bc37 2022-10-23 stsp .Xr gotd 8 .
103 eec68231 2022-12-14 stsp requires root privileges in order to create its unix socket.
104 13b2bc37 2022-10-23 stsp Afterwards,
106 13b2bc37 2022-10-23 stsp drops privileges to the specified
108 13b2bc37 2022-10-23 stsp If not specified, the user _gotd will be used.
110 13b2bc37 2022-10-23 stsp .Sh REPOSITORY CONFIGURATION
111 13b2bc37 2022-10-23 stsp At least one repository context must exist for
113 13b2bc37 2022-10-23 stsp to function.
114 0ccf3acb 2022-11-16 stsp For each repository, access rules must be configured using the
118 0ccf3acb 2022-11-16 stsp configuration directives.
119 0ccf3acb 2022-11-16 stsp Multiple access rules can be specified, and the last matching rule
120 0ccf3acb 2022-11-16 stsp determines the action taken.
121 0ccf3acb 2022-11-16 stsp If no rule matches, access to the repository is denied.
123 13b2bc37 2022-10-23 stsp A repository context is declared with a unique
125 13b2bc37 2022-10-23 stsp followed by repository-specific configuration directives inside curly braces:
127 13b2bc37 2022-10-23 stsp .Ic repository Ar name Brq ...
132 13b2bc37 2022-10-23 stsp clients can connect to a repository by including the repository's unique
134 13b2bc37 2022-10-23 stsp in the request URL.
135 13b2bc37 2022-10-23 stsp Clients appending the string
139 13b2bc37 2022-10-23 stsp will also be accepted.
141 13b2bc37 2022-10-23 stsp If desired, the
143 13b2bc37 2022-10-23 stsp may contain path-separators,
145 13b2bc37 2022-10-23 stsp to expose repositories as part of a virtual client-visible directory hierarchy.
147 13b2bc37 2022-10-23 stsp The available repository configuration directives are as follows:
148 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds
149 0ccf3acb 2022-11-16 stsp .It Ic deny Ar identity
150 0ccf3acb 2022-11-16 stsp Deny repository access to users with the username
151 0ccf3acb 2022-11-16 stsp .Ar identity .
152 0ccf3acb 2022-11-16 stsp Group names may be matched by prepending a colon
155 0ccf3acb 2022-11-16 stsp .Ar identity .
156 0ccf3acb 2022-11-16 stsp Numeric IDs are also accepted.
157 13b2bc37 2022-10-23 stsp .It Ic path Ar path
158 13b2bc37 2022-10-23 stsp Set the path to the Git repository.
159 3b706203 2023-01-02 stsp Must be specified.
160 0ccf3acb 2022-11-16 stsp .It Ic permit Ar mode Ar identity
161 0ccf3acb 2022-11-16 stsp Permit repository access to users with the username
162 0ccf3acb 2022-11-16 stsp .Ar identity .
165 0ccf3acb 2022-11-16 stsp argument must be set to either
167 0ccf3acb 2022-11-16 stsp for read-only access,
170 0ccf3acb 2022-11-16 stsp for read-write access.
171 0ccf3acb 2022-11-16 stsp Group names may be matched by prepending a colon
174 0ccf3acb 2022-11-16 stsp .Ar identity .
175 0ccf3acb 2022-11-16 stsp Numeric IDs are also accepted.
178 13b2bc37 2022-10-23 stsp .Bl -tag -width Ds -compact
179 13b2bc37 2022-10-23 stsp .It Pa /etc/gotd.conf
180 13b2bc37 2022-10-23 stsp Location of the
182 13b2bc37 2022-10-23 stsp configuration file.
184 13b2bc37 2022-10-23 stsp .Sh EXAMPLES
185 13b2bc37 2022-10-23 stsp .Bd -literal -offset indent
186 13b2bc37 2022-10-23 stsp # Default unix_group and user values:
187 13b2bc37 2022-10-23 stsp unix_group _gotsh
190 13b2bc37 2022-10-23 stsp # This repository can be accessed via ssh://user@example.com/src
191 13b2bc37 2022-10-23 stsp repository "src" {
192 13b2bc37 2022-10-23 stsp path "/var/git/src.git"
193 0ccf3acb 2022-11-16 stsp permit rw flan_hacker
194 0ccf3acb 2022-11-16 stsp permit rw :developers
195 0ccf3acb 2022-11-16 stsp permit ro anonymous
198 13b2bc37 2022-10-23 stsp # This repository can be accessed via
199 13b2bc37 2022-10-23 stsp # ssh://user@example.com/openbsd/ports
200 13b2bc37 2022-10-23 stsp repository "openbsd/ports" {
201 13b2bc37 2022-10-23 stsp path "/var/git/ports.git"
202 0ccf3acb 2022-11-16 stsp permit rw :porters
203 0ccf3acb 2022-11-16 stsp permit ro anonymous
204 0ccf3acb 2022-11-16 stsp deny flan_hacker
207 40b85cca 2023-01-03 stsp # Use a larger request timeout value:
208 40b85cca 2023-01-03 stsp connection request timeout 7200 # 2 hours
210 40b85cca 2023-01-03 stsp # Some users are granted a higher concurrent connection limit:
211 40b85cca 2023-01-03 stsp connection {
212 40b85cca 2023-01-03 stsp limit user flan_hacker 16
213 40b85cca 2023-01-03 stsp limit user anonymous 32
216 13b2bc37 2022-10-23 stsp .Sh SEE ALSO
217 13b2bc37 2022-10-23 stsp .Xr got 1 ,
218 13b2bc37 2022-10-23 stsp .Xr gotsh 1 ,
219 13b2bc37 2022-10-23 stsp .Xr group 5 ,
