3 public-inbox-config - public-inbox config file description
11 The public-inbox config file is parseable by L<git-config(1)>.
12 This is a global configuration file for mapping/discovering
13 all public-inboxes used by a particular user.
15 =head1 CONFIGURATION FILE
20 mainrepo = /home/user/path/to/test.git
21 ; multiple addresses are supported
22 address = test@example.com
23 ; address = alternate@example.com
24 url = http://example.com/test
25 newsgroup = inbox.test
31 =item publicinbox.<name>.address
33 The email address of the public-inbox. May be specified
34 more than once for merging multiple mailing lists (or migrating
35 to new addresses). This must be specified at least once,
36 the first value will be considered the primary address for
37 informational purposes.
39 Default: none, required
41 =item publicinbox.<name>.mainrepo
43 The absolute path to the directory which hosts the
44 public-inbox. This must be specified once.
46 Default: none, required
48 =item publicinbox.<name>.url
50 The primary URL for hosting the HTTP/HTTPS archives.
51 Additional HTTP/HTTPS URLs may be specified via
52 C<$GIT_DIR/cloneurl> as documented in L<gitweb(1)>
54 Default: none, optional
56 =item publicinbox.<name>.newsgroup
58 The NNTP group name for use with L<public-inbox-nntpd(8)>. This
59 may be any newsgroup name with hierarchies delimited by '.'.
60 For example, the newsgroup for L<mailto:meta@public-inbox.org>
61 is: C<inbox.comp.mail.public-inbox.meta>
63 Omitting this for the given inbox will prevent the group from
64 being read by L<public-inbox-nntpd(1)>
66 Default: none, optional
68 =item publicinbox.<name>.watch
70 A location for L<public-inbox-watch(1)> to watch. Currently,
71 only C<maildir:> paths are supported:
74 watch = maildir:/path/to/maildirs/.INBOX.test/
76 Default: none; only for L<public-inbox-watch(1)> users
78 =item publicinbox.<name>.watchheader
81 watchheader = List-Id:<test.example.com>
83 If specified, L<public-inbox-watch(1)> will only process mail matching
84 the given header. Multiple values are not currently supported.
86 Default: none; only for L<public-inbox-watch(1)> users
88 =item publicinbox.<name>.listid
90 The L<rfc2919|https://tools.ietf.org/html/rfc2919> header without
91 angle brackets for L<public-inbox-mda(1)> deliveries and
92 L<public-inbox-watch(1)>.
94 For public-inbox-watch users, this is a shortcut for specifying
95 C<publicinbox.$NAME.watchheader=List-Id:<foo.example.com>>
97 For public-inbox-mda users, this may be used to avoid recipient
98 matching via C<ORIGINAL_RECIPIENT> environment variable.
100 This may be specified multiple times for merging multiple mailing
101 lists into a single public-inbox, only one C<List-Id> header
106 =item publicinbox.<name>.nntpmirror
108 This may be the full NNTP URL of an independently-run mirror.
109 For example, the https://public-inbox.org/meta/ inbox is
111 C<nntp://news.gmane.org/gmane.mail.public-inbox.general>
115 =item publicinbox.<name>.indexlevel
117 The indexing level for L<public-inbox-index(1)>
119 C<basic> only requires L<DBD::SQLite(3pm)> and provides all
120 NNTP functionality along with thread-awareness in the WWW
123 C<medium> requires L<Search::Xapian(3pm)> to provide full-text
124 term search functionality in the WWW UI.
126 C<full> also includes positional information used by Xapian to
127 allow for searching for phrases using quoted text.
128 (e.g. C<"looking for a complete sentence">)
132 =item publicinbox.<name>.httpbackendmax
134 If a digit, the maximum number of parallel
135 L<git-http-backend(1)> processes to allow for cloning this
138 If an alphanumeric value starting with a lowercase alphabetic
139 character is specified, the inbox will use a L</NAMED LIMITER>
140 which can be shared by multiple inboxes.
142 Default: 32 (using a default limiter shared by all inboxes)
144 =item publicinbox.<name>.coderepo
146 The nickname of a "coderepo" section associated with the inbox.
147 May be specified more than once for M:N mapping of code repos to
148 inboxes. If enabled, diff hunk headers in patch emails will
149 link to the line numbers of blobs.
153 =item publicinbox.<name>.replyto
155 May be used to control how reply instructions in the PSGI
156 interface are displayed.
158 ":none=dead inbox" may be specified to denote an inactive list
159 ("dead inbox" may be replaced with another phrase).
161 A list of comma-delimited email addresses may be specified.
162 This can be useful for dedicated inboxes for bot emails, but
163 discussion happens on a seperate mailing list/inbox.
165 Mirrors of existing centralized mailing lists may use ":list"
166 here to redirect mail only to the configured inbox address.
167 The use of ":list" is discouraged for new mailing lists, as it
168 leads to centralization.
172 =item publicinbox.css
174 The local path name of a CSS file for the PSGI web interface.
175 May contain the attributes "media", "title" and "href" which match
176 the associated attributes of the HTML <style> tag.
177 "href" may be specified to point to the URL of an remote CSS file
178 and the path may be "/dev/null" or any empty file.
179 Multiple files may be specified and will be included in the
182 =item publicinboxmda.spamcheck
184 This may be set to C<none> to disable the use of SpamAssassin
185 L<spamc(1)> for filtering spam before it is imported into git
186 history. Other spam filtering backends may be supported in
191 =item publicinboxwatch.spamcheck
193 This may be set to C<spamc> to enable the use of SpamAssassin
194 L<spamc(1)> for filtering spam before it is imported into git
195 history. Other spam filtering backends may be supported in
200 =item publicinboxwatch.watchspam
202 This may be set to C<spamc> to enable the use of SpamAssassin
203 L<spamc(1)> for filtering spam before it is imported into git
204 history. Other spam filtering backends may be supported in
205 the future. This requires L<public-inbox-watch(1)>, but affects
206 all configured public-inboxes in PI_CONFIG.
210 =item publicinbox.nntpserver
212 Set this to point to the address of the L<public-inbox-nntpd(1)>
213 instance. This is used to advertise the existence of the NNTP
214 presnce in the L<PublicInbox::WWW> HTML interface.
216 Multiple values are allowed for servers with multiple
217 addresses or mirrors.
221 =item publicinbox.<name>.feedmax
223 The size of an Atom feed for the inbox. If specified more than
224 once, only the last value is used. Invalid values (<= 0) will
225 be treated as the default value.
229 =item publicinbox.<name>.hide
231 A comma-delimited list of listings to hide the inbox from.
233 Valid values are currently C<www> and C<manifest>.
237 =item coderepo.<nick>.dir
239 The path to a git repository for "publicinbox.<name>.coderepo"
241 =item coderepo.<nick>.cgitUrl
243 The URL of the cgit instance associated with the coderepo.
247 =item publicinbox.cgitrc
249 A path to a L<cgitrc(5)> file. "repo.url" directives in the cgitrc
250 will be mapped to the nickname of a coderepo (without trailing slash),
251 and "repo.path" directives map to "coderepo.<nick>.dir".
252 Use of this directive allows admins of existing cgit installations
253 to skip declaring coderepo sections and map inboxes directly to
254 code repositories known to cgit.
256 Macro expansion (e.g. C<$HTTP_HOST>) is not yet supported.
258 =item publicinbox.cgitbin
260 A path to the C<cgit.cgi> executable. The L<PublicInbox::WWW>
261 interface can spawn cgit as a fallback if the publicinbox.cgitrc
262 directive is configured.
264 Default: /var/www/htdocs/cgit/cgit.cgi or /usr/lib/cgit/cgit.cgi
266 =item publicinbox.cgitdata
268 A path to the data directory used by cgit for storing static files.
269 Typically guessed based the location of C<cgit.cgi> (from
270 C<publicinbox.cgitbin>, but may be overridden.
272 Default: basename of C<publicinbox.cgitbin>, /var/www/htdocs/cgit/
275 =item publicinbox.mailEditor
277 See L<public-inbox-edit(1)>
279 =item publicinbox.wwwlisting
281 Enable a HTML listing style when the root path of the URL '/' is accessed.
290 - Return a 404 page. This is useful to allow customization with
291 L<Plack::App::Cascade(3pm)>
294 - Only show inboxes with URLs which belong to the domain of the HTTP request
298 support showing cgit listing
304 =item publicinbox.grokmanifest
306 Controls the generation of a grokmirror-compatible gzipped JSON file
307 at the top-level of the PSGI interface. You generally do not need to
308 change this from the default.
315 - Only include inboxes with URLs which belong to the domain of
316 the HTTP request. This is compatible with virtual hosting where
317 several domains come from the same host.
320 - All inboxes are present in C<manifest.js.gz>, regardless of domain.
321 Only use this if you're serving HTTP requests in a domain-agnostic manner.
324 - C<manifest.js.gz> will only contain an empty JSON array.
325 This does NOT affect C<$INBOX_URL/manifest.js.gz>, which will
326 always contain all git repos used by the inbox at C<$INBOX_URL>
330 Default: C<match=domain>
334 =head2 NAMED LIMITER (PSGI)
336 Named limiters are useful for preventing large inboxes from
337 monopolizing (or overloading) the server. Since serving git
338 clones (via L<git-http-backend(1)> can be memory-intensive for
339 large inboxes, it makes sense to put large inboxes on a named
340 limiter with a low max value; while smaller inboxes can use
343 C<RLIMIT_*> keys may be set to enforce resource limits for
344 a particular limiter.
346 Default named-limiters are prefixed with "-". Currently,
347 the "-cgit" named limiter is reserved for instances spawning
348 cgit via C<publicinbox.cgitrc>
352 =item publicinboxlimiter.<name>.max
354 The maximum number of parallel processes for the given limiter.
356 =item publicinboxlimiter.<name>.rlimitCore
358 =item publicinboxlimiter.<name>.rlimitCPU
360 =item publicinboxlimiter.<name>.rlimitData
362 The maximum core size, CPU time, or data size processes run with the
363 given limiter will use. This may be comma-separated to distinguish
364 soft and hard limits. The word "INFINITY" is accepted as the
365 RLIM_INFINITY constant (if supported by your OS).
367 See L<setrlimit(2)> for more info on the behavior of RLIMIT_CORE,
368 RLIMIT_CPU, and RLIMIT_DATA for you operating system.
372 =head3 EXAMPLE WITH NAMED LIMITERS
374 ; big inboxes which require lots of memory to clone:
376 mainrepo = /path/to/big1
377 address = big1@example.com
380 mainrepo = /path/to/big2
381 address = big2@example.com
384 ; tiny inboxes which are easily cloned:
385 [publicinbox "tiny1"]
386 mainrepo = /path/to/tiny1
387 address = tiny1@example.com
388 [publicinbox "tiny2"]
389 mainrepo = /path/to/tiny2
390 address = tiny2@example.com
392 [publicinboxlimiter "big"]
395 In the above example, the "big1" and "big2" are limited to four
396 parallel L<git-http-backend(1)> processes between them.
398 However, "tiny1" and "tiny2" will share the default limiter
399 which means there can be 32 L<git-http-backend(1)> processes
408 Used to override the default "~/.public-inbox/config" value.
414 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
416 The mail archives are hosted at L<https://public-inbox.org/meta/>
417 and L<http://hjrcffqmbrq6wope.onion/meta/>
421 Copyright 2016-2019 all contributors L<mailto:meta@public-inbox.org>
423 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
427 L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>,
428 L<public-inbox-mda(1)>, L<public-inbox-watch(1)>,
429 L<grokmirror|https://git.kernel.org/pub/scm/utils/grokmirror/grokmirror.git>