1PUBLIC-INBOX-CONFIG(5)     public-inbox user manual     PUBLIC-INBOX-CONFIG(5)
2
3
4

NAME

6       public-inbox-config - public-inbox config file description
7

SYNOPSIS

9       ~/.public-inbox/config
10

DESCRIPTION

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

CONFIGURATION FILE

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

ENVIRONMENT

393       PI_CONFIG
394               Used to override the default "~/.public-inbox/config" value.
395

CONTACT

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

SEE ALSO

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)
Impressum