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