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>.nntpmirror
90 This may be the full NNTP URL of an independently-run mirror.
91 For example, the https://public-inbox.org/meta/ inbox is
93 C<nntp://news.gmane.org/gmane.mail.public-inbox.general>
97 =item publicinbox.<name>.indexlevel
99 The indexing level for L<public-inbox-index(1)>
101 C<basic> only requires L<DBD::SQLite(3pm)> and provides all
102 NNTP functionality along with thread-awareness in the WWW
105 C<medium> requires L<Search::Xapian(3pm)> to provide full-text
106 term search functionality in the WWW UI.
108 C<full> also includes positional information used by Xapian to
109 allow for searching for phrases using quoted text.
110 (e.g. C<"looking for a complete sentence">)
114 =item publicinbox.<name>.httpbackendmax
116 If a digit, the maximum number of parallel
117 L<git-http-backend(1)> processes to allow for cloning this
120 If an alphanumeric value starting with a lowercase alphabetic
121 character is specified, the inbox will use a L</NAMED LIMITER>
122 which can be shared by multiple inboxes.
124 Default: 32 (using a default limiter shared by all inboxes)
126 =item publicinbox.<name>.coderepo
128 The nickname of a "coderepo" section associated with the inbox.
129 May be specified more than once for M:N mapping of code repos to
130 inboxes. If enabled, diff hunk headers in patch emails will
131 link to the line numbers of blobs.
135 =item publicinbox.<name>.replyto
137 May be used to control how reply instructions in the PSGI
138 interface are displayed.
140 ":none=dead inbox" may be specified to denote an inactive list
141 ("dead inbox" may be replaced with another phrase).
143 A list of comma-delimited email addresses may be specified.
144 This can be useful for dedicated inboxes for bot emails, but
145 discussion happens on a seperate mailing list/inbox.
147 Mirrors of existing centralized mailing lists may use ":list"
148 here to redirect mail only to the configured inbox address.
149 The use of ":list" is discouraged for new mailing lists, as it
150 leads to centralization.
154 =item publicinbox.css
156 The local path name of a CSS file for the PSGI web interface.
157 May contain the attributes "media", "title" and "href" which match
158 the associated attributes of the HTML <style> tag.
159 "href" may be specified to point to the URL of an remote CSS file
160 and the path may be "/dev/null" or any empty file.
161 Multiple files may be specified and will be included in the
164 =item publicinboxmda.spamcheck
166 This may be set to C<none> to disable the use of SpamAssassin
167 L<spamc(1)> for filtering spam before it is imported into git
168 history. Other spam filtering backends may be supported in
173 =item publicinboxwatch.spamcheck
175 This may be set to C<spamc> to enable the use of SpamAssassin
176 L<spamc(1)> for filtering spam before it is imported into git
177 history. Other spam filtering backends may be supported in
182 =item publicinboxwatch.watchspam
184 This may be set to C<spamc> to enable 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
187 the future. This requires L<public-inbox-watch(1)>, but affects
188 all configured public-inboxes in PI_CONFIG.
192 =item publicinbox.nntpserver
194 Set this to point to the address of the L<public-inbox-nntpd(1)>
195 instance. This is used to advertise the existence of the NNTP
196 presnce in the L<PublicInbox::WWW> HTML interface.
198 Multiple values are allowed for servers with multiple
199 addresses or mirrors.
203 =item publicinbox.<name>.feedmax
205 The size of an Atom feed for the inbox. If specified more than
206 once, only the last value is used. Invalid values (<= 0) will
207 be treated as the default value.
211 =item publicinbox.<name>.hide
213 A comma-delimited list of listings to hide the inbox from.
215 Valid values are currently C<www> and C<manifest>.
219 =item coderepo.<nick>.dir
221 The path to a git repository for "publicinbox.<name>.coderepo"
223 =item coderepo.<nick>.cgitUrl
225 The URL of the cgit instance associated with the coderepo.
229 =item publicinbox.cgitrc
231 A path to a L<cgitrc(5)> file. "repo.url" directives in the cgitrc
232 will be mapped to the nickname of a coderepo (without trailing slash),
233 and "repo.path" directives map to "coderepo.<nick>.dir".
234 Use of this directive allows admins of existing cgit installations
235 to skip declaring coderepo sections and map inboxes directly to
236 code repositories known to cgit.
238 Macro expansion (e.g. C<$HTTP_HOST>) is not yet supported.
240 =item publicinbox.cgitbin
242 A path to the C<cgit.cgi> executable. The L<PublicInbox::WWW>
243 interface can spawn cgit as a fallback if the publicinbox.cgitrc
244 directive is configured.
246 Default: /var/www/htdocs/cgit/cgit.cgi or /usr/lib/cgit/cgit.cgi
248 =item publicinbox.cgitdata
250 A path to the data directory used by cgit for storing static files.
251 Typically guessed based the location of C<cgit.cgi> (from
252 C<publicinbox.cgitbin>, but may be overridden.
254 Default: basename of C<publicinbox.cgitbin>, /var/www/htdocs/cgit/
257 =item publicinbox.mailEditor
259 See L<public-inbox-edit(1)>
261 =item publicinbox.wwwlisting
263 Enable a HTML listing style when the root path of the URL '/' is accessed.
272 - Return a 404 page. This is useful to allow customization with
273 L<Plack::App::Cascade(3pm)>
276 - Only show inboxes with URLs which belong to the domain of the HTTP request
280 support showing cgit listing
286 =item publicinbox.grokmanifest
288 Controls the generation of a grokmirror-compatible gzipped JSON file
289 at the top-level of the PSGI interface. You generally do not need to
290 change this from the default.
297 - Only include inboxes with URLs which belong to the domain of
298 the HTTP request. This is compatible with virtual hosting where
299 several domains come from the same host.
302 - All inboxes are present in C<manifest.js.gz>, regardless of domain.
303 Only use this if you're serving HTTP requests in a domain-agnostic manner.
306 - C<manifest.js.gz> will only contain an empty JSON array.
307 This does NOT affect C<$INBOX_URL/manifest.js.gz>, which will
308 always contain all git repos used by the inbox at C<$INBOX_URL>
312 Default: C<match=domain>
316 =head2 NAMED LIMITER (PSGI)
318 Named limiters are useful for preventing large inboxes from
319 monopolizing (or overloading) the server. Since serving git
320 clones (via L<git-http-backend(1)> can be memory-intensive for
321 large inboxes, it makes sense to put large inboxes on a named
322 limiter with a low max value; while smaller inboxes can use
325 C<RLIMIT_*> keys may be set to enforce resource limits for
326 a particular limiter.
328 Default named-limiters are prefixed with "-". Currently,
329 the "-cgit" named limiter is reserved for instances spawning
330 cgit via C<publicinbox.cgitrc>
334 =item publicinboxlimiter.<name>.max
336 The maximum number of parallel processes for the given limiter.
338 =item publicinboxlimiter.<name>.rlimitCore
340 =item publicinboxlimiter.<name>.rlimitCPU
342 =item publicinboxlimiter.<name>.rlimitData
344 The maximum core size, CPU time, or data size processes run with the
345 given limiter will use. This may be comma-separated to distinguish
346 soft and hard limits. The word "INFINITY" is accepted as the
347 RLIM_INFINITY constant (if supported by your OS).
349 See L<setrlimit(2)> for more info on the behavior of RLIMIT_CORE,
350 RLIMIT_CPU, and RLIMIT_DATA for you operating system.
354 =head3 EXAMPLE WITH NAMED LIMITERS
356 ; big inboxes which require lots of memory to clone:
358 mainrepo = /path/to/big1
359 address = big1@example.com
362 mainrepo = /path/to/big2
363 address = big2@example.com
366 ; tiny inboxes which are easily cloned:
367 [publicinbox "tiny1"]
368 mainrepo = /path/to/tiny1
369 address = tiny1@example.com
370 [publicinbox "tiny2"]
371 mainrepo = /path/to/tiny2
372 address = tiny2@example.com
374 [publicinboxlimiter "big"]
377 In the above example, the "big1" and "big2" are limited to four
378 parallel L<git-http-backend(1)> processes between them.
380 However, "tiny1" and "tiny2" will share the default limiter
381 which means there can be 32 L<git-http-backend(1)> processes
390 Used to override the default "~/.public-inbox/config" value.
396 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
398 The mail archives are hosted at L<https://public-inbox.org/meta/>
399 and L<http://hjrcffqmbrq6wope.onion/meta/>
403 Copyright 2016-2019 all contributors L<mailto:meta@public-inbox.org>
405 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
409 L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>,
410 L<public-inbox-mda(1)>, L<public-inbox-watch(1)>,
411 L<grokmirror|https://git.kernel.org/pub/scm/utils/grokmirror/grokmirror.git>