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) as well as public-inbox-pop3d(1)
64 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 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.pop3server
207 Same as "publicinbox.imapserver", but for the hostname(s) of
208 the public-inbox-pop3d(1) instance.
209 Default: none
211 publicinbox.pop3state
213 See "publicinbox.pop3state" in public-inbox-pop3d(1)
214 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 Default: 25
221 publicinbox.<name>.hide
223 A comma-delimited list of listings to hide the inbox from.
224 Valid values are currently "www" and "manifest".
226 Default: none
228 coderepo.<nick>.dir
230 The path to a git repository for "publicinbox.<name>.coderepo"
231 coderepo.<nick>.cgitUrl
233 The URL of the cgit instance associated with the coderepo.
234 Default: none
236 coderepo.snapshots
238 See "snapshots" in cgitrc(5)
239 publicinbox.cgitrc
241 A path to a cgitrc(5) file. "repo.url" directives in the
242 cgitrc will be mapped to the nickname of a coderepo (without
243 trailing slash), and "repo.path" directives map to
244 "coderepo.<nick>.dir". Use of this directive allows admins of
245 existing cgit installations to skip declaring coderepo sections
246 and map inboxes directly to code repositories known to cgit.
247 Macro expansion (e.g. $HTTP_HOST) is not yet supported.
249 publicinbox.cgitbin
251 A path to the "cgit.cgi" executable. The PublicInbox::WWW
252 interface can spawn cgit as a fallback if the
253 publicinbox.cgitrc directive is configured.
254 Default: /var/www/htdocs/cgit/cgit.cgi or
256 /usr/lib/cgit/cgit.cgi
257 publicinbox.cgitdata
259 A path to the data directory used by cgit for storing static
260 files. Typically guessed based the location of "cgit.cgi"
261 (from "publicinbox.cgitbin", but may be overridden.
262 Default: basename of "publicinbox.cgitbin",
264 /var/www/htdocs/cgit/ or /usr/share/cgit/
265 publicinbox.cgit
267 Controls whether or not and how "cgit" is used for serving
268 coderepos. New in public-inbox 2.0.0 (PENDING).
269 • first
271 Try using "cgit" as the first choice, this is the
273 default.
274 • fallback
276 Fall back to using "cgit" only if our native, inbox-
278 aware git code repository viewer doesn't recognized the
279 URL.
280 • rewrite
282 Rewrite "cgit" URLs for our native, inbox-aware code
284 repository viewer. This implies "fallback" for URLs
285 the native viewer does not recognize.
286 Default: "first" ("cgit" will be used iff "publicinbox.cgitrc"
288 is set and the "cgit" binary exists).
289 publicinbox.mailEditor
291 See public-inbox-edit(1)
292 publicinbox.indexMaxSize =item publicinbox.indexBatchSize =item
294 publicinbox.indexSequentialShard
295 See public-inbox-index(1)
296 publicinbox.wwwlisting
298 Enable a HTML listing style when the root path of the URL '/'
299 is accessed. Valid values are:
300 • all - Show all inboxes
302 • 404 - Return a 404 page. This is useful to allow
304 customization with Plack::App::Cascade(3pm)
305 • match=domain - Only show inboxes with URLs which belong
307 to the domain of the HTTP request
308 Default: 404
310 publicinbox.grokmanifest
312 Controls the generation of a grokmirror-compatible gzipped JSON
313 file at the top-level of the PSGI interface. You generally do
314 not need to change this from the default.
315 Valid values are:
317 • match=domain - Only include inboxes with URLs which
319 belong to the domain of the HTTP request. This is
320 compatible with virtual hosting where several domains
321 come from the same host.
322 • all - All inboxes are present in "manifest.js.gz",
324 regardless of domain. Only use this if you're serving
325 HTTP requests in a domain-agnostic manner.
326 • 404 - "manifest.js.gz" will only contain an empty JSON
328 array. This does NOT affect
329 "$INBOX_URL/manifest.js.gz", which will always contain
330 all git repos used by the inbox at $INBOX_URL
331 Default: "match=domain"
333 publicinbox.<name>.obfuscate
335 Whether to obfuscate email addresses in the PublicInbox::WWW
336 HTML interface.
337 Default: false
339 publicinbox.noObfuscate
341 A space-delimited list of well-known addresses and domains that
342 should not be obfuscated when "publicinbox.$NAME.obfuscate" is
343 true (e.g., "public@example.com" and "@example.com"). This may
344 be specified more than once, in which case the values are
345 merged.
346 Default: none
348 extindex.<name>.topdir
350 The directory of an external index. See
351 public-inbox-extindex(1) for more details.
352 extindex.<name>.url
354 Identical to "publicinbox.<name>.url", but for external indices
355 extindex.<name>.coderepo
357 Identical to "publicinbox.<name>.coderepo", but for external
358 indices. Code repos may be freely associated with any number
359 of public inboxes and external indices.
360 NAMED LIMITER (PSGI)
362 Named limiters are useful for preventing large inboxes from
363 monopolizing (or overloading) the server. Since serving git clones
364 (via git-http-backend(1) can be memory-intensive for large inboxes, it
365 makes sense to put large inboxes on a named limiter with a low max
366 value; while smaller inboxes can use the default limiter.
367 "RLIMIT_*" keys may be set to enforce resource limits for a particular
369 limiter (BSD::Resource(3pm) is required).
370 Default named-limiters are prefixed with "-". Currently, the "-cgit"
372 named limiter is reserved for instances spawning cgit via
373 "publicinbox.cgitrc"
374 publicinboxlimiter.<name>.max
376 The maximum number of parallel processes for the given limiter.
377 publicinboxlimiter.<name>.rlimitCore
379 publicinboxlimiter.<name>.rlimitCPU
380 publicinboxlimiter.<name>.rlimitData
381 The maximum core size, CPU time, or data size processes run
382 with the given limiter will use. This may be comma-separated
383 to distinguish soft and hard limits. The word "INFINITY" is
384 accepted as the RLIM_INFINITY constant (if supported by your
385 OS).
386 See setrlimit(2) for more info on the behavior of RLIMIT_CORE,
388 RLIMIT_CPU, and RLIMIT_DATA for you operating system.
389 EXAMPLE WITH NAMED LIMITERS
391 ; big inboxes which require lots of memory to clone:
393 [publicinbox "big1"]
394 inboxdir = /path/to/big1
395 address = big1@example.com
396 httpbackendmax = big
397 [publicinbox "big2"]
398 inboxdir = /path/to/big2
399 address = big2@example.com
400 httpbackendmax = big
401 ; tiny inboxes which are easily cloned:
403 [publicinbox "tiny1"]
404 inboxdir = /path/to/tiny1
405 address = tiny1@example.com
406 [publicinbox "tiny2"]
407 inboxdir = /path/to/tiny2
408 address = tiny2@example.com
409 [publicinboxlimiter "big"]
411 max = 4
412 In the above example, the "big1" and "big2" are limited to four
414 parallel git-http-backend(1) processes between them.
415 However, "tiny1" and "tiny2" will share the default limiter which means
417 there can be 32 git-http-backend(1) processes between them.
418
420 PI_CONFIG
421 Used to override the default "~/.public-inbox/config" value.
422
424 Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>
425 The mail archives are hosted at <https://public-inbox.org/meta/> and
427 <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
428
430 Copyright all contributors <mailto:meta@public-inbox.org>
431 License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
433
435 git(1), git-config(1), public-inbox-daemon(8), public-inbox-mda(1),
436 public-inbox-watch(1), grokmirror
437 <https://git.kernel.org/pub/scm/utils/grokmirror/grokmirror.git>
438public-inbox.git 1993-10-02 PUBLIC-INBOX-CONFIG(5)