1PUBLIC-INBOX-CONFIG(5) public-inbox user manual PUBLIC-INBOX-CONFIG(5)
2
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 ; backwards compatibility with public-inbox pre-1.2.0,
27 ; "inboxdir" takes precedence over "mainrepo"
28 mainrepo = /home/user/path/to/test.git
29 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 Default: none, required
39 publicinbox.<name>.inboxdir
41 The absolute path to the directory which hosts the public-
42 inbox. This must be specified once.
43 This was previously known as "mainrepo", which remains
45 supported, but "inboxdir" takes precedence.
46 Default: none, required
48 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 Default: none, optional
55 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 It also configures the folder hierarchy used by
63 public-inbox-imapd(1).
64 Omitting this for a given inbox will prevent the inbox from
66 being served by public-inbox-nntpd(1) and/or
67 public-inbox-imapd(1).
68 Default: none, optional
70 publicinbox.<name>.watch
72 See public-inbox-watch(1)
73 publicinbox.<name>.watchheader
75 See public-inbox-watch(1)
76 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 For public-inbox-watch users, this is a shortcut for specifying
83 "publicinbox.$NAME.watchheader=List-Id:<foo.example.com>"
84 For public-inbox-mda users, this may be used to avoid recipient
86 matching via "ORIGINAL_RECIPIENT" environment variable.
87 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 Default: none
93 publicinbox.<name>.imapmirror
95 This may be the full IMAP URL of an independently-run IMAP
96 mirror.
97 Default: none
99 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 Default: none
107 publicinbox.<name>.indexlevel
109 The indexing level for public-inbox-index(1)
110 "basic" only requires DBD::SQLite(3pm) and provides all NNTP
112 functionality along with thread-awareness in the WWW interface.
113 "medium" requires Search::Xapian(3pm) to provide full-text term
115 search functionality in the WWW UI.
116 "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 Default: "full"
122 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 Default: 0
129 publicinbox.<name>.indexSequentialShard
131 See "publicInbox.indexSequentialShard" in public-inbox-index(1)
132 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 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 Default: 32 (using a default limiter shared by all inboxes)
142 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 Default: none
150 publicinbox.<name>.replyto
152 May be used to control how reply instructions in the PSGI
153 interface are displayed.
154 ":none=dead inbox" may be specified to denote an inactive list
156 ("dead inbox" may be replaced with another phrase).
157 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 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 Default: :all
168 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 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 Default: spamc
185 publicinboxwatch.spamcheck
187 See public-inbox-watch(1)
188 publicinboxwatch.watchspam
190 See public-inbox-watch(1)
191 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 Default: none
199 publicinbox.nntpserver
201 Same as "publicinbox.imapserver", but for the hostname(s) of
202 the public-inbox-nntpd(1) instance.
203 Default: none
205 publicinbox.<name>.feedmax
207 The size of an Atom feed for the inbox. If specified more than
208 once, only the last value is used. Invalid values (<= 0) will
209 be treated as the default value.
210 Default: 25
212 publicinbox.<name>.hide
214 A comma-delimited list of listings to hide the inbox from.
215 Valid values are currently "www" and "manifest".
217 Default: none
219 coderepo.<nick>.dir
221 The path to a git repository for "publicinbox.<name>.coderepo"
222 coderepo.<nick>.cgitUrl
224 The URL of the cgit instance associated with the coderepo.
225 Default: none
227 publicinbox.cgitrc
229 A path to a cgitrc(5) file. "repo.url" directives in the
230 cgitrc will be mapped to the nickname of a coderepo (without
231 trailing slash), and "repo.path" directives map to
232 "coderepo.<nick>.dir". Use of this directive allows admins of
233 existing cgit installations to skip declaring coderepo sections
234 and map inboxes directly to code repositories known to cgit.
235 Macro expansion (e.g. $HTTP_HOST) is not yet supported.
237 publicinbox.cgitbin
239 A path to the "cgit.cgi" executable. The PublicInbox::WWW
240 interface can spawn cgit as a fallback if the
241 publicinbox.cgitrc directive is configured.
242 Default: /var/www/htdocs/cgit/cgit.cgi or
244 /usr/lib/cgit/cgit.cgi
245 publicinbox.cgitdata
247 A path to the data directory used by cgit for storing static
248 files. Typically guessed based the location of "cgit.cgi"
249 (from "publicinbox.cgitbin", but may be overridden.
250 Default: basename of "publicinbox.cgitbin",
252 /var/www/htdocs/cgit/ or /usr/share/cgit/
253 publicinbox.mailEditor
255 See public-inbox-edit(1)
256 publicinbox.indexMaxSize =item publicinbox.indexBatchSize =item
258 publicinbox.indexSequentialShard
259 See public-inbox-index(1)
260 publicinbox.wwwlisting
262 Enable a HTML listing style when the root path of the URL '/'
263 is accessed. Valid values are:
264 • all - Show all inboxes
266 • 404 - Return a 404 page. This is useful to allow
268 customization with Plack::App::Cascade(3pm)
269 • match=domain - Only show inboxes with URLs which belong
271 to the domain of the HTTP request
272 Default: 404
274 publicinbox.grokmanifest
276 Controls the generation of a grokmirror-compatible gzipped JSON
277 file at the top-level of the PSGI interface. You generally do
278 not need to change this from the default.
279 Valid values are:
281 • match=domain - Only include inboxes with URLs which
283 belong to the domain of the HTTP request. This is
284 compatible with virtual hosting where several domains
285 come from the same host.
286 • all - All inboxes are present in "manifest.js.gz",
288 regardless of domain. Only use this if you're serving
289 HTTP requests in a domain-agnostic manner.
290 • 404 - "manifest.js.gz" will only contain an empty JSON
292 array. This does NOT affect
293 "$INBOX_URL/manifest.js.gz", which will always contain
294 all git repos used by the inbox at $INBOX_URL
295 Default: "match=domain"
297 publicinbox.<name>.obfuscate
299 Whether to obfuscate email addresses in the PublicInbox::WWW
300 HTML interface.
301 Default: false
303 publicinbox.noObfuscate
305 A space-delimited list of well-known addresses and domains that
306 should not be obfuscated when "publicinbox.$NAME.obfuscate" is
307 true (e.g., "public@example.com" and "@example.com"). This may
308 be specified more than once, in which case the values are
309 merged.
310 Default: none
312 extindex.<name>.topdir
314 The directory of an external index. See
315 public-inbox-extindex(1) for more details.
316 extindex.<name>.url
318 Identical to "publicinbox.<name>.url", but for external indices
319 extindex.<name>.coderepo
321 Identical to "publicinbox.<name>.coderepo", but for external
322 indices. Code repos may be freely associated with any number
323 of public inboxes and external indices.
324 NAMED LIMITER (PSGI)
326 Named limiters are useful for preventing large inboxes from
327 monopolizing (or overloading) the server. Since serving git clones
328 (via git-http-backend(1) can be memory-intensive for large inboxes, it
329 makes sense to put large inboxes on a named limiter with a low max
330 value; while smaller inboxes can use the default limiter.
331 "RLIMIT_*" keys may be set to enforce resource limits for a particular
333 limiter (BSD::Resource(3pm) is required).
334 Default named-limiters are prefixed with "-". Currently, the "-cgit"
336 named limiter is reserved for instances spawning cgit via
337 "publicinbox.cgitrc"
338 publicinboxlimiter.<name>.max
340 The maximum number of parallel processes for the given limiter.
341 publicinboxlimiter.<name>.rlimitCore
343 publicinboxlimiter.<name>.rlimitCPU
344 publicinboxlimiter.<name>.rlimitData
345 The maximum core size, CPU time, or data size processes run
346 with the given limiter will use. This may be comma-separated
347 to distinguish soft and hard limits. The word "INFINITY" is
348 accepted as the RLIM_INFINITY constant (if supported by your
349 OS).
350 See setrlimit(2) for more info on the behavior of RLIMIT_CORE,
352 RLIMIT_CPU, and RLIMIT_DATA for you operating system.
353 EXAMPLE WITH NAMED LIMITERS
355 ; big inboxes which require lots of memory to clone:
357 [publicinbox "big1"]
358 inboxdir = /path/to/big1
359 address = big1@example.com
360 httpbackendmax = big
361 [publicinbox "big2"]
362 inboxdir = /path/to/big2
363 address = big2@example.com
364 httpbackendmax = big
365 ; tiny inboxes which are easily cloned:
367 [publicinbox "tiny1"]
368 inboxdir = /path/to/tiny1
369 address = tiny1@example.com
370 [publicinbox "tiny2"]
371 inboxdir = /path/to/tiny2
372 address = tiny2@example.com
373 [publicinboxlimiter "big"]
375 max = 4
376 In the above example, the "big1" and "big2" are limited to four
378 parallel git-http-backend(1) processes between them.
379 However, "tiny1" and "tiny2" will share the default limiter which means
381 there can be 32 git-http-backend(1) processes between them.
382
384 PI_CONFIG
385 Used to override the default "~/.public-inbox/config" value.
386
388 Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>
389 The mail archives are hosted at <https://public-inbox.org/meta/> and
391 <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
392
394 Copyright 2016-2021 all contributors <mailto:meta@public-inbox.org>
395 License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
397
399 git(1), git-config(1), public-inbox-daemon(8), public-inbox-mda(1),
400 public-inbox-watch(1), grokmirror
401 <https://git.kernel.org/pub/scm/utils/grokmirror/grokmirror.git>
402public-inbox.git 1993-10-02 PUBLIC-INBOX-CONFIG(5)