4 <meta charset="utf-8"/>
5 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
6 <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
7 <title>GOTD.CONF(5)</title>
9 <!-- This is an automatically generated file. Do not edit.
10 Copyright (c) 2022 Stefan Sperling <stsp@openbsd.org>
12 Permission to use, copy, modify, and distribute this software for any
13 purpose with or without fee is hereby granted, provided that the above
14 copyright notice and this permission notice appear in all copies.
16 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
17 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
18 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
19 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
20 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
21 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
22 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25 <div class="head" role="doc-pageheader" aria-label="Manual header
26 line"><span class="head-ltitle">GOTD.CONF(5)</span>
27 <span class="head-vol">File Formats Manual</span>
28 <span class="head-rtitle">GOTD.CONF(5)</span></div>
29 <main class="manual-text">
31 <h2 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h2>
32 <p class="Pp"><code class="Nm">gotd.conf</code> —
33 <span class="Nd" role="doc-subtitle">gotd configuration file</span></p>
36 <h2 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h2>
37 <p class="Pp"><code class="Nm">gotd.conf</code> is the run-time configuration
38 file for <a class="Xr" aria-label="gotd, section 8">gotd(8)</a>.</p>
39 <p class="Pp">The file format is line-based, with one configuration directive
40 per line. Any lines beginning with a ‘#’ are treated as
41 comments and ignored.</p>
44 <h2 class="Sh" id="GLOBAL_CONFIGURATION"><a class="permalink" href="#GLOBAL_CONFIGURATION">GLOBAL
45 CONFIGURATION</a></h2>
46 <p class="Pp">The available global configuration directives are as follows:</p>
48 <dt id="connection"><a class="permalink" href="#connection"><code class="Ic">connection</code></a>
49 <var class="Ar">option</var></dt>
50 <dd>Set the specified options and limits for connections to the
51 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> unix socket.
52 <p class="Pp">The <code class="Ic">connection</code> directive may be
53 specified multiple times, and multiple <var class="Ar">option</var>
54 arguments may be specified within curly braces:</p>
55 <p class="Pp"><code class="Ic">connection</code>
56 {<var class="Ar">...</var>}</p>
57 <p class="Pp">Each option should only be specified once. If a given option
58 is listed multiple times, the last line which sets this option wins.</p>
59 <p class="Pp">Valid connection options are:</p>
61 <dt id="request"><a class="permalink" href="#request"><code class="Ic">request
62 timeout</code></a> <var class="Ar">seconds</var></dt>
63 <dd>Specify the inactivity timeout for operations between client and
64 server. If this timeout is exceeded while a Git protocol request is
65 being processed, the request will be aborted and the connection will
67 <p class="Pp">The timeout value may also have a suffix indicating its
68 unit of measure. Supported suffixes are:</p>
70 <dl class="Bl-tag Bl-compact">
71 <dt><var class="Ar">s</var> <span class="No">or</span>
72 <var class="Ar">S</var></dt>
74 <dt><var class="Ar">m</var> <span class="No">or</span>
75 <var class="Ar">M</var></dt>
77 <dt><var class="Ar">h</var> <span class="No">or</span>
78 <var class="Ar">H</var></dt>
81 <p class="Pp">The default timeout is 1h (3600 seconds, one hour). This
82 should only be changed if legitimate requests are exceeding the
83 default timeout for some reason, such as the server spending an
84 extraordinary amount of time generating a pack file.</p>
86 <dt id="limit"><a class="permalink" href="#limit"><code class="Ic">limit</code></a>
87 <code class="Ic">user</code> <var class="Ar">identity</var>
88 <var class="Ar">number</var></dt>
89 <dd>Limit the maximum amount of concurrent connections by the user with
90 the username <var class="Ar">identity</var> to
91 <var class="Ar">number</var>. Numeric user IDs are also accepted.
92 <p class="Pp">The default per-user limit is 4. This should only be
93 changed if concurrent connections from a given user are expected to
94 exceed the default limit, for example if an anonymous user is
95 granted read access and many concurrent connections will share this
96 anonymous user identity.</p>
100 <dt id="listen"><a class="permalink" href="#listen"><code class="Ic">listen
101 on</code></a> <var class="Ar">path</var></dt>
102 <dd>Set the path to the unix socket which <a class="Xr" aria-label="gotd,
103 section 8">gotd(8)</a> should listen on. If not specified, the path
104 <span class="Pa">/var/run/gotd.sock</span> will be used.</dd>
105 <dt id="user"><a class="permalink" href="#user"><code class="Ic">user</code></a>
106 <var class="Ar">user</var></dt>
107 <dd>Set the <var class="Ar">user</var> which will run
108 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a>. Initially,
109 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> requires root
110 privileges in order to create its unix socket. Afterwards,
111 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> drops privileges to
112 the specified <var class="Ar">user</var>. If not specified, the user _gotd
117 <h2 class="Sh" id="REPOSITORY_CONFIGURATION"><a class="permalink" href="#REPOSITORY_CONFIGURATION">REPOSITORY
118 CONFIGURATION</a></h2>
119 <p class="Pp">At least one repository context must exist for
120 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a> to function. For each
121 repository, access rules must be configured using the
122 <code class="Ic">permit</code> and <code class="Ic">deny</code>
123 configuration directives. Multiple access rules can be specified, and the
124 last matching rule determines the action taken. If no rule matches, access
125 to the repository is denied.</p>
126 <p class="Pp">A repository context is declared with a unique
127 <var class="Ar">name</var>, followed by repository-specific configuration
128 directives inside curly braces:</p>
129 <p class="Pp"><code class="Ic">repository</code> <var class="Ar">name</var>
131 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a> and
132 <a class="Xr" aria-label="git, section 1">git(1)</a> clients can connect to
133 a repository by including the repository's unique <var class="Ar">name</var>
134 in the request URL. Clients appending the string “.git” to the
135 <var class="Ar">name</var> will also be accepted.</p>
136 <p class="Pp">If desired, the <var class="Ar">name</var> may contain
137 path-separators, “/”, to expose repositories as part of a
138 virtual client-visible directory hierarchy.</p>
139 <p class="Pp">The available repository configuration directives are as
142 <dt id="deny"><a class="permalink" href="#deny"><code class="Ic">deny</code></a>
143 <var class="Ar">identity</var></dt>
144 <dd>Deny repository access to users with the username
145 <var class="Ar">identity</var>. Group names may be matched by prepending a
146 colon (‘:’) to <var class="Ar">identity</var>. Numeric IDs
147 are also accepted.</dd>
148 <dt id="path"><a class="permalink" href="#path"><code class="Ic">path</code></a>
149 <var class="Ar">path</var></dt>
150 <dd>Set the path to the Git repository. Must be specified.</dd>
151 <dt id="permit"><a class="permalink" href="#permit"><code class="Ic">permit</code></a>
152 <var class="Ar">mode</var> <var class="Ar">identity</var></dt>
153 <dd>Permit repository access to users with the username
154 <var class="Ar">identity</var>. The <var class="Ar">mode</var> argument
155 must be set to either <code class="Ic">ro</code> for read-only access, or
156 <code class="Ic">rw</code> for read-write access. Group names may be
157 matched by prepending a colon (‘:’) to
158 <var class="Ar">identity</var>. Numeric IDs are also accepted.</dd>
159 <dt id="protect"><a class="permalink" href="#protect"><code class="Ic">protect</code></a>
160 {<var class="Ar">...</var>}</dt>
161 <dd>The <code class="Cm">protect</code> directive may be used to protect
162 branches and tags in a repository from being overwritten by potentially
163 destructive client-side commands, such as when <code class="Cm">got send
164 -f</code> and <code class="Cm">git push -f</code> are used to change the
166 <p class="Pp">To build a set of protected branches and tags, multiple
167 <code class="Ic">protect</code> directives may be specified per
168 repository and multiple <code class="Ic">protect</code> directive
169 parameters may be specified within curly braces.</p>
170 <p class="Pp">The available <code class="Cm">protect</code> parameters are
173 <dt id="branch"><a class="permalink" href="#branch"><code class="Ic">branch</code></a>
174 <var class="Ar">name</var></dt>
175 <dd>Protect the named branch. The branch may be created if it does not
176 exist yet. Attempts to delete the branch or change its history will be
178 <p class="Pp">If the <var class="Ar">name</var> does not already begin
179 with “refs/heads/” it will be looked up in the
180 “refs/heads/” reference namespace.</p>
182 <dt id="branch~2"><a class="permalink" href="#branch~2"><code class="Ic">branch</code></a>
183 <code class="Ic">namespace</code> <var class="Ar">namespace</var></dt>
184 <dd>Protect the given reference namespace, assuming that references in
185 this namespace represent branches. New branches may be created in the
186 namespace. Attempts to change the history of branches or delete them
188 <p class="Pp">The <var class="Ar">namespace</var> argument must be
189 absolute, starting with “refs/”.</p>
191 <dt id="tag"><a class="permalink" href="#tag"><code class="Ic">tag</code></a>
192 <code class="Ic">namespace</code> <var class="Ar">namespace</var></dt>
193 <dd>Protect the given reference namespace, assuming that references in
194 this namespace represent tags. New tags may be created in the
195 namespace. Attempts to change or delete existing tags will be denied.
196 <p class="Pp">The <var class="Ar">namespace</var> argument must be
197 absolute, starting with “refs/”.</p>
200 <p class="Pp">The special reference namespaces “refs/got/” and
201 “refs/remotes/” do not need to be listed in
202 <code class="Nm">gotd.conf</code>. These namespaces are always protected
203 and even attempts to create new references in these namespaces will
204 always be denied.</p>
209 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
210 <dl class="Bl-tag Bl-compact">
211 <dt><span class="Pa">/etc/gotd.conf</span></dt>
212 <dd>Location of the <code class="Nm">gotd.conf</code> configuration file.</dd>
216 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
217 <div class="Bd Bd-indent Li">
218 <pre># Run as the default user:
221 # Listen on the default socket:
222 listen on "/var/run/gotd.sock"
224 # This repository can be accessed via ssh://user@example.com/src
225 repository "src" {
226 path "/var/git/src.git"
227 permit rw flan_hacker
228 permit rw :developers
231 protect branch "main"
232 protect tag namespace "refs/tags/"
235 # This repository can be accessed via
236 # ssh://user@example.com/openbsd/ports
237 repository "openbsd/ports" {
238 path "/var/git/ports.git"
244 branch "main"
245 tag namespace "refs/tags/"
249 # Use a larger request timeout value:
250 connection request timeout 2h
252 # Some users are granted a higher concurrent connection limit:
254 limit user flan_hacker 16
255 limit user anonymous 32
260 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
262 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
263 <a class="Xr" aria-label="gotsh, section 1">gotsh(1)</a>,
264 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a></p>
267 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
268 line"><span class="foot-left"></span><span class="foot-date">March 11,
269 2024</span> <span class="foot-os">OpenBSD 7.5</span></div>
