]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-config.pod
mda+learn: add --help / -h support
[public-inbox.git] / Documentation / public-inbox-config.pod
1 =head1 NAME
2
3 public-inbox-config - public-inbox config file description
4
5 =head1 SYNOPSIS
6
7 ~/.public-inbox/config
8
9 =head1 DESCRIPTION
10
11 The public-inbox config file is parseable by L<git-config(1)>.
12 This is a global configuration file for mapping/discovering
13 all public-inboxes used by a particular user.
14
15 =head1 CONFIGURATION FILE
16
17 =head2 EXAMPLE
18
19         [publicinbox "test"]
20                 inboxdir = /home/user/path/to/test.git
21                 ; multiple addresses are supported
22                 address = test@example.com
23                 ; address = alternate@example.com
24                 url = http://example.com/test
25                 newsgroup = inbox.test
26
27                 ; backwards compatibility with public-inbox pre-1.2.0,
28                 ; "inboxdir" takes precedence over "mainrepo"
29                 mainrepo = /home/user/path/to/test.git
30
31 =head2 VARIABLES
32
33 =over 8
34
35 =item publicinbox.<name>.address
36
37 The email address of the public-inbox.  May be specified
38 more than once for merging multiple mailing lists (or migrating
39 to new addresses).  This must be specified at least once,
40 the first value will be considered the primary address for
41 informational purposes.
42
43 Default: none, required
44
45 =item publicinbox.<name>.inboxdir
46
47 The absolute path to the directory which hosts the
48 public-inbox.  This must be specified once.
49
50 This was previously known as "mainrepo", which remains supported,
51 but "inboxdir" takes precedence.
52
53 Default: none, required
54
55 =item publicinbox.<name>.url
56
57 The primary URL for hosting the HTTP/HTTPS archives.
58 Additional HTTP/HTTPS URLs may be specified via
59 C<$GIT_DIR/cloneurl> as documented in L<gitweb(1)>
60
61 Default: none, optional
62
63 =item publicinbox.<name>.newsgroup
64
65 The NNTP group name for use with L<public-inbox-nntpd(8)>.  This
66 may be any newsgroup name with hierarchies delimited by C<.>.
67 For example, the newsgroup for L<mailto:meta@public-inbox.org>
68 is: C<inbox.comp.mail.public-inbox.meta>
69
70 Omitting this for the given inbox will prevent the group from
71 being read by L<public-inbox-nntpd(1)>
72
73 Default: none, optional
74
75 =item publicinbox.<name>.watch
76
77 See L<public-inbox-watch(1)>
78
79 =item publicinbox.<name>.watchheader
80
81 See L<public-inbox-watch(1)>
82
83 =item publicinbox.<name>.listid
84
85 The L<rfc2919|https://tools.ietf.org/html/rfc2919> header without
86 angle brackets for L<public-inbox-mda(1)> deliveries and
87 L<public-inbox-watch(1)>.
88
89 For public-inbox-watch users, this is a shortcut for specifying
90 C<publicinbox.$NAME.watchheader=List-Id:E<lt>foo.example.comE<gt>>
91
92 For public-inbox-mda users, this may be used to avoid recipient
93 matching via C<ORIGINAL_RECIPIENT> environment variable.
94
95 This may be specified multiple times for merging multiple mailing
96 lists into a single public-inbox, only one C<List-Id> header
97 needs to match.
98
99 Default: none
100
101 =item publicinbox.<name>.nntpmirror
102
103 This may be the full NNTP URL of an independently-run mirror.
104 For example, the https://public-inbox.org/meta/ inbox is
105 mirrored by Gmane at
106 C<nntp://news.gmane.io/gmane.mail.public-inbox.general>
107
108 Default: none
109
110 =item publicinbox.<name>.indexlevel
111
112 The indexing level for L<public-inbox-index(1)>
113
114 C<basic> only requires L<DBD::SQLite(3pm)> and provides all
115 NNTP functionality along with thread-awareness in the WWW
116 interface.
117
118 C<medium> requires L<Search::Xapian(3pm)> to provide full-text
119 term search functionality in the WWW UI.
120
121 C<full> also includes positional information used by Xapian to
122 allow for searching for phrases using quoted text.
123 (e.g. C<"looking for a complete sentence">)
124
125 Default: C<full>
126
127 =item publicinbox.<name>.indexSequentialShard
128
129 See L<public-inbox-index(1)/publicInbox.indexSequentialShard>
130
131 =item publicinbox.<name>.httpbackendmax
132
133 If a digit, the maximum number of parallel
134 L<git-http-backend(1)> processes to allow for cloning this
135 particular inbox.
136
137 If an alphanumeric value starting with a lowercase alphabetic
138 character is specified, the inbox will use a L</NAMED LIMITER>
139 which can be shared by multiple inboxes.
140
141 Default: 32 (using a default limiter shared by all inboxes)
142
143 =item publicinbox.<name>.coderepo
144
145 The nickname of a "coderepo" section associated with the inbox.
146 May be specified more than once for M:N mapping of code repos to
147 inboxes.  If enabled, diff hunk headers in patch emails will
148 link to the line numbers of blobs.
149
150 Default: none
151
152 =item publicinbox.<name>.replyto
153
154 May be used to control how reply instructions in the PSGI
155 interface are displayed.
156
157 ":none=dead inbox" may be specified to denote an inactive list
158 ("dead inbox" may be replaced with another phrase).
159
160 A list of comma-delimited email addresses may be specified.
161 This can be useful for dedicated inboxes for bot emails, but
162 discussion happens on a separate mailing list/inbox.
163
164 Mirrors of existing centralized mailing lists may use ":list"
165 here to redirect mail only to the configured inbox address.
166 The use of ":list" is discouraged for new mailing lists, as it
167 leads to centralization.
168
169 Default: :all
170
171 =item publicinbox.css
172
173 The local path name of a CSS file for the PSGI web interface.
174 May contain the attributes "media", "title" and "href" which match
175 the associated attributes of the HTML <style> tag.
176 "href" may be specified to point to the URL of an remote CSS file
177 and the path may be "/dev/null" or any empty file.
178 Multiple files may be specified and will be included in the
179 order specified.
180
181 =item publicinboxmda.spamcheck
182
183 This may be set to C<none> to disable the use of SpamAssassin
184 L<spamc(1)> for filtering spam before it is imported into git
185 history.  Other spam filtering backends may be supported in
186 the future.
187
188 Default: spamc
189
190 =item publicinboxwatch.spamcheck
191
192 See L<public-inbox-watch(1)>
193
194 =item publicinboxwatch.watchspam
195
196 See L<public-inbox-watch(1)>
197
198 =item publicinbox.nntpserver
199
200 Set this to point to the hostname of the L<public-inbox-nntpd(1)>
201 instance.  This is used to advertise the existence of the NNTP
202 endpoint in the L<PublicInbox::WWW> HTML interface.
203
204 Multiple values are allowed for instances with multiple hostnames
205 or mirrors.
206
207 Default: none
208
209 =item publicinbox.<name>.feedmax
210
211 The size of an Atom feed for the inbox.  If specified more than
212 once, only the last value is used.  Invalid values (<= 0) will
213 be treated as the default value.
214
215 Default: 25
216
217 =item publicinbox.<name>.hide
218
219 A comma-delimited list of listings to hide the inbox from.
220
221 Valid values are currently C<www> and C<manifest>.
222
223 Default: none
224
225 =item coderepo.<nick>.dir
226
227 The path to a git repository for "publicinbox.<name>.coderepo"
228
229 =item coderepo.<nick>.cgitUrl
230
231 The URL of the cgit instance associated with the coderepo.
232
233 Default: none
234
235 =item publicinbox.cgitrc
236
237 A path to a L<cgitrc(5)> file.  "repo.url" directives in the cgitrc
238 will be mapped to the nickname of a coderepo (without trailing slash),
239 and "repo.path" directives map to "coderepo.<nick>.dir".
240 Use of this directive allows admins of existing cgit installations
241 to skip declaring coderepo sections and map inboxes directly to
242 code repositories known to cgit.
243
244 Macro expansion (e.g. C<$HTTP_HOST>) is not yet supported.
245
246 =item publicinbox.cgitbin
247
248 A path to the C<cgit.cgi> executable.  The L<PublicInbox::WWW>
249 interface can spawn cgit as a fallback if the publicinbox.cgitrc
250 directive is configured.
251
252 Default: /var/www/htdocs/cgit/cgit.cgi or /usr/lib/cgit/cgit.cgi
253
254 =item publicinbox.cgitdata
255
256 A path to the data directory used by cgit for storing static files.
257 Typically guessed based the location of C<cgit.cgi> (from
258 C<publicinbox.cgitbin>, but may be overridden.
259
260 Default: basename of C<publicinbox.cgitbin>, /var/www/htdocs/cgit/
261 or /usr/share/cgit/
262
263 =item publicinbox.mailEditor
264
265 See L<public-inbox-edit(1)>
266
267 =item publicinbox.indexMaxSize
268 =item publicinbox.indexBatchSize
269 =item publicinbox.indexSequentialShard
270
271 See L<public-inbox-index(1)>
272
273 =item publicinbox.wwwlisting
274
275 Enable a HTML listing style when the root path of the URL '/' is accessed.
276 Valid values are:
277
278 =over 8
279
280 =item * all
281 - Show all inboxes
282
283 =item * 404
284 - Return a 404 page.  This is useful to allow customization with
285 L<Plack::App::Cascade(3pm)>
286
287 =item * match=domain
288 - Only show inboxes with URLs which belong to the domain of the HTTP request
289
290 =for TODO comment
291
292 support showing cgit listing
293
294 =back
295
296 Default: C<404>
297
298 =item publicinbox.grokmanifest
299
300 Controls the generation of a grokmirror-compatible gzipped JSON file
301 at the top-level of the PSGI interface.  You generally do not need to
302 change this from the default.
303
304 Valid values are:
305
306 =over 8
307
308 =item * match=domain
309 - Only include inboxes with URLs which belong to the domain of
310 the HTTP request.  This is compatible with virtual hosting where
311 several domains come from the same host.
312
313 =item * all
314 - All inboxes are present in C<manifest.js.gz>, regardless of domain.
315 Only use this if you're serving HTTP requests in a domain-agnostic manner.
316
317 =item * 404
318 - C<manifest.js.gz> will only contain an empty JSON array.
319 This does NOT affect C<$INBOX_URL/manifest.js.gz>, which will
320 always contain all git repos used by the inbox at C<$INBOX_URL>
321
322 =back
323
324 Default: C<match=domain>
325
326 =back
327
328 =head2 NAMED LIMITER (PSGI)
329
330 Named limiters are useful for preventing large inboxes from
331 monopolizing (or overloading) the server.  Since serving git
332 clones (via L<git-http-backend(1)> can be memory-intensive for
333 large inboxes, it makes sense to put large inboxes on a named
334 limiter with a low max value; while smaller inboxes can use
335 the default limiter.
336
337 C<RLIMIT_*> keys may be set to enforce resource limits for
338 a particular limiter.
339
340 Default named-limiters are prefixed with "-".  Currently,
341 the "-cgit" named limiter is reserved for instances spawning
342 cgit via C<publicinbox.cgitrc>
343
344 =over 8
345
346 =item publicinboxlimiter.<name>.max
347
348 The maximum number of parallel processes for the given limiter.
349
350 =item publicinboxlimiter.<name>.rlimitCore
351
352 =item publicinboxlimiter.<name>.rlimitCPU
353
354 =item publicinboxlimiter.<name>.rlimitData
355
356 The maximum core size, CPU time, or data size processes run with the
357 given limiter will use.  This may be comma-separated to distinguish
358 soft and hard limits.  The word "INFINITY" is accepted as the
359 RLIM_INFINITY constant (if supported by your OS).
360
361 See L<setrlimit(2)> for more info on the behavior of RLIMIT_CORE,
362 RLIMIT_CPU, and RLIMIT_DATA for you operating system.
363
364 =back
365
366 =head3 EXAMPLE WITH NAMED LIMITERS
367
368         ; big inboxes which require lots of memory to clone:
369         [publicinbox "big1"]
370                 inboxdir = /path/to/big1
371                 address = big1@example.com
372                 httpbackendmax = big
373         [publicinbox "big2"]
374                 inboxdir = /path/to/big2
375                 address = big2@example.com
376                 httpbackendmax = big
377
378         ; tiny inboxes which are easily cloned:
379         [publicinbox "tiny1"]
380                 inboxdir = /path/to/tiny1
381                 address = tiny1@example.com
382         [publicinbox "tiny2"]
383                 inboxdir = /path/to/tiny2
384                 address = tiny2@example.com
385
386         [publicinboxlimiter "big"]
387                 max = 4
388
389 In the above example, the "big1" and "big2" are limited to four
390 parallel L<git-http-backend(1)> processes between them.
391
392 However, "tiny1" and "tiny2" will share the default limiter
393 which means there can be 32 L<git-http-backend(1)> processes
394 between them.
395
396 =head1 ENVIRONMENT
397
398 =over 8
399
400 =item PI_CONFIG
401
402 Used to override the default "~/.public-inbox/config" value.
403
404 =back
405
406 =head1 CONTACT
407
408 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
409
410 The mail archives are hosted at L<https://public-inbox.org/meta/>
411 and L<http://hjrcffqmbrq6wope.onion/meta/>
412
413 =head1 COPYRIGHT
414
415 Copyright 2016-2020 all contributors L<mailto:meta@public-inbox.org>
416
417 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
418
419 =head1 SEE ALSO
420
421 L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>,
422 L<public-inbox-mda(1)>, L<public-inbox-watch(1)>,
423 L<grokmirror|https://git.kernel.org/pub/scm/utils/grokmirror/grokmirror.git>