Blame


1 742bb3a1 2022-10-24 stsp <!DOCTYPE html>
2 742bb3a1 2022-10-24 stsp <html>
3 742bb3a1 2022-10-24 stsp <head>
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>
8 742bb3a1 2022-10-24 stsp </head>
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>
11 742bb3a1 2022-10-24 stsp
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.
15 742bb3a1 2022-10-24 stsp
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.
23 742bb3a1 2022-10-24 stsp -->
24 742bb3a1 2022-10-24 stsp <body>
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> &#x2014;
33 742bb3a1 2022-10-24 stsp <span class="Nd" role="doc-subtitle">gotd configuration file</span></p>
34 742bb3a1 2022-10-24 stsp </section>
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 &#x2018;#&#x2019; are treated as
41 742bb3a1 2022-10-24 stsp comments and ignored.</p>
42 742bb3a1 2022-10-24 stsp </section>
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>
80 47f19dd5 2023-01-17 stsp </dl>
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>
85 47f19dd5 2023-01-17 stsp </dd>
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>
97 47f19dd5 2023-01-17 stsp </dd>
98 47f19dd5 2023-01-17 stsp </dl>
99 47f19dd5 2023-01-17 stsp </dd>
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>
114 742bb3a1 2022-10-24 stsp </dl>
115 742bb3a1 2022-10-24 stsp </section>
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>
130 742bb3a1 2022-10-24 stsp {...}</p>
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 &#x201C;.git&#x201D; 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, &#x201C;/&#x201D;, 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 (&#x2018;:&#x2019;) 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 (&#x2018;:&#x2019;) to
158 47f19dd5 2023-01-17 stsp <var class="Ar">identity</var>. Numeric IDs are also accepted.</dd>
159 742bb3a1 2022-10-24 stsp </dl>
160 742bb3a1 2022-10-24 stsp </section>
161 742bb3a1 2022-10-24 stsp <section class="Sh">
162 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
163 742bb3a1 2022-10-24 stsp <dl class="Bl-tag Bl-compact">
164 742bb3a1 2022-10-24 stsp <dt><span class="Pa">/etc/gotd.conf</span></dt>
165 742bb3a1 2022-10-24 stsp <dd>Location of the <code class="Nm">gotd.conf</code> configuration file.</dd>
166 742bb3a1 2022-10-24 stsp </dl>
167 742bb3a1 2022-10-24 stsp </section>
168 742bb3a1 2022-10-24 stsp <section class="Sh">
169 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
170 742bb3a1 2022-10-24 stsp <div class="Bd Bd-indent Li">
171 47f19dd5 2023-01-17 stsp <pre># Run as the default user:
172 742bb3a1 2022-10-24 stsp user _gotd
173 742bb3a1 2022-10-24 stsp
174 47f19dd5 2023-01-17 stsp # Listen on the default socket:
175 47f19dd5 2023-01-17 stsp listen on &quot;/var/run/gotd.sock&quot;
176 47f19dd5 2023-01-17 stsp
177 742bb3a1 2022-10-24 stsp # This repository can be accessed via ssh://user@example.com/src
178 742bb3a1 2022-10-24 stsp repository &quot;src&quot; {
179 742bb3a1 2022-10-24 stsp path &quot;/var/git/src.git&quot;
180 47f19dd5 2023-01-17 stsp permit rw flan_hacker
181 47f19dd5 2023-01-17 stsp permit rw :developers
182 47f19dd5 2023-01-17 stsp permit ro anonymous
183 742bb3a1 2022-10-24 stsp }
184 742bb3a1 2022-10-24 stsp
185 742bb3a1 2022-10-24 stsp # This repository can be accessed via
186 742bb3a1 2022-10-24 stsp # ssh://user@example.com/openbsd/ports
187 742bb3a1 2022-10-24 stsp repository &quot;openbsd/ports&quot; {
188 742bb3a1 2022-10-24 stsp path &quot;/var/git/ports.git&quot;
189 47f19dd5 2023-01-17 stsp permit rw :porters
190 47f19dd5 2023-01-17 stsp permit ro anonymous
191 47f19dd5 2023-01-17 stsp deny flan_hacker
192 47f19dd5 2023-01-17 stsp }
193 47f19dd5 2023-01-17 stsp
194 47f19dd5 2023-01-17 stsp # Use a larger request timeout value:
195 47f19dd5 2023-01-17 stsp connection request timeout 2h
196 47f19dd5 2023-01-17 stsp
197 47f19dd5 2023-01-17 stsp # Some users are granted a higher concurrent connection limit:
198 47f19dd5 2023-01-17 stsp connection {
199 47f19dd5 2023-01-17 stsp limit user flan_hacker 16
200 47f19dd5 2023-01-17 stsp limit user anonymous 32
201 742bb3a1 2022-10-24 stsp }</pre>
202 742bb3a1 2022-10-24 stsp </div>
203 742bb3a1 2022-10-24 stsp </section>
204 742bb3a1 2022-10-24 stsp <section class="Sh">
205 742bb3a1 2022-10-24 stsp <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
206 742bb3a1 2022-10-24 stsp ALSO</a></h2>
207 742bb3a1 2022-10-24 stsp <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
208 742bb3a1 2022-10-24 stsp <a class="Xr" aria-label="gotsh, section 1">gotsh(1)</a>,
209 742bb3a1 2022-10-24 stsp <a class="Xr" aria-label="gotd, section 8">gotd(8)</a></p>
210 742bb3a1 2022-10-24 stsp </section>
211 742bb3a1 2022-10-24 stsp </main>
212 742bb3a1 2022-10-24 stsp <div class="foot" role="doc-pagefooter" aria-label="Manual footer
213 f6a6fa94 2023-02-22 stsp line"><span class="foot-left"></span><span class="foot-date">February 22,
214 47f19dd5 2023-01-17 stsp 2023</span> <span class="foot-os">OpenBSD 7.2</span></div>
215 742bb3a1 2022-10-24 stsp </body>
216 742bb3a1 2022-10-24 stsp </html>