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 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 Macro expansion (e.g. $HTTP_HOST) is not yet supported.
246 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 Default: /var/www/htdocs/cgit/cgit.cgi or
253 /usr/lib/cgit/cgit.cgi
254 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 Default: basename of "publicinbox.cgitbin",
261 /var/www/htdocs/cgit/ or /usr/share/cgit/
262 publicinbox.mailEditor
264 See public-inbox-edit(1)
265 publicinbox.indexMaxSize =item publicinbox.indexBatchSize =item
267 publicinbox.indexSequentialShard
268 See public-inbox-index(1)
269 publicinbox.wwwlisting
271 Enable a HTML listing style when the root path of the URL '/'
272 is accessed. Valid values are:
273 • all - Show all inboxes
275 • 404 - Return a 404 page. This is useful to allow
277 customization with Plack::App::Cascade(3pm)
278 • match=domain - Only show inboxes with URLs which belong
280 to the domain of the HTTP request
281 Default: 404
283 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 Valid values are:
290 • 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 • 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 • 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 Default: "match=domain"
306 publicinbox.<name>.obfuscate
308 Whether to obfuscate email addresses in the PublicInbox::WWW
309 HTML interface.
310 Default: false
312 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 Default: none
321 extindex.<name>.topdir
323 The directory of an external index. See
324 public-inbox-extindex(1) for more details.
325 extindex.<name>.url
327 Identical to "publicinbox.<name>.url", but for external indices
328 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 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 "RLIMIT_*" keys may be set to enforce resource limits for a particular
342 limiter (BSD::Resource(3pm) is required).
343 Default named-limiters are prefixed with "-". Currently, the "-cgit"
345 named limiter is reserved for instances spawning cgit via
346 "publicinbox.cgitrc"
347 publicinboxlimiter.<name>.max
349 The maximum number of parallel processes for the given limiter.
350 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 See setrlimit(2) for more info on the behavior of RLIMIT_CORE,
361 RLIMIT_CPU, and RLIMIT_DATA for you operating system.
362 EXAMPLE WITH NAMED LIMITERS
364 ; 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 ; 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 [publicinboxlimiter "big"]
384 max = 4
385 In the above example, the "big1" and "big2" are limited to four
387 parallel git-http-backend(1) processes between them.
388 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 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 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>
411public-inbox.git 1993-10-02 PUBLIC-INBOX-CONFIG(5)