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