Blob


1 <!DOCTYPE html>
2 <html>
3 <head>
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>
8 </head>
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.
23 -->
24 <body>
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">
30 <section class="Sh">
31 <h2 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h2>
32 <p class="Pp"><code class="Nm">gotd.conf</code> &#x2014;
33 <span class="Nd" role="doc-subtitle">gotd configuration file</span></p>
34 </section>
35 <section class="Sh">
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 &#x2018;#&#x2019; are treated as
41 comments and ignored.</p>
42 </section>
43 <section class="Sh">
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>
47 <dl class="Bl-tag">
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>
60 <dl class="Bl-tag">
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
66 be terminated.
67 <p class="Pp">The timeout value may also have a suffix indicating its
68 unit of measure. Supported suffixes are:</p>
69 <p class="Pp"></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>
73 <dd>seconds</dd>
74 <dt><var class="Ar">m</var> <span class="No">or</span>
75 <var class="Ar">M</var></dt>
76 <dd>minutes</dd>
77 <dt><var class="Ar">h</var> <span class="No">or</span>
78 <var class="Ar">H</var></dt>
79 <dd>hours</dd>
80 </dl>
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>
85 </dd>
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>
97 </dd>
98 </dl>
99 </dd>
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
113 will be used.</dd>
114 </dl>
115 </section>
116 <section class="Sh">
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>
130 {...}</p>
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 &#x201C;.git&#x201D; 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, &#x201C;/&#x201D;, 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
140 follows:</p>
141 <dl class="Bl-tag">
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 (&#x2018;:&#x2019;) 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 (&#x2018;:&#x2019;) to
158 <var class="Ar">identity</var>. Numeric IDs are also accepted.</dd>
159 </dl>
160 </section>
161 <section class="Sh">
162 <h2 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h2>
163 <dl class="Bl-tag Bl-compact">
164 <dt><span class="Pa">/etc/gotd.conf</span></dt>
165 <dd>Location of the <code class="Nm">gotd.conf</code> configuration file.</dd>
166 </dl>
167 </section>
168 <section class="Sh">
169 <h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
170 <div class="Bd Bd-indent Li">
171 <pre># Run as the default user:
172 user _gotd
174 # Listen on the default socket:
175 listen on &quot;/var/run/gotd.sock&quot;
177 # This repository can be accessed via ssh://user@example.com/src
178 repository &quot;src&quot; {
179 path &quot;/var/git/src.git&quot;
180 permit rw flan_hacker
181 permit rw :developers
182 permit ro anonymous
185 # This repository can be accessed via
186 # ssh://user@example.com/openbsd/ports
187 repository &quot;openbsd/ports&quot; {
188 path &quot;/var/git/ports.git&quot;
189 permit rw :porters
190 permit ro anonymous
191 deny flan_hacker
194 # Use a larger request timeout value:
195 connection request timeout 2h
197 # Some users are granted a higher concurrent connection limit:
198 connection {
199 limit user flan_hacker 16
200 limit user anonymous 32
201 }</pre>
202 </div>
203 </section>
204 <section class="Sh">
205 <h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
206 ALSO</a></h2>
207 <p class="Pp"><a class="Xr" aria-label="got, section 1">got(1)</a>,
208 <a class="Xr" aria-label="gotsh, section 1">gotsh(1)</a>,
209 <a class="Xr" aria-label="gotd, section 8">gotd(8)</a></p>
210 </section>
211 </main>
212 <div class="foot" role="doc-pagefooter" aria-label="Manual footer
213 line"><span class="foot-left"></span><span class="foot-date">February 22,
214 2023</span> <span class="foot-os">OpenBSD 7.2</span></div>
215 </body>
216 </html>