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 Default: none; only for L<public-inbox-watch(1)> users
85 =item publicinbox.<name>.nntpmirror
87 This may be the full NNTP URL of an independently-run mirror.
88 For example, the https://public-inbox.org/meta/ inbox is
90 C<nntp://news.gmane.org/gmane.mail.public-inbox.general>
94 =item publicinbox.<name>.indexlevel
96 The indexing level for L<public-inbox-index(1)>
98 C<basic> only requires L<DBD::SQLite(3pm)> and provides all
99 NNTP functionality along with thread-awareness in the WWW
102 C<medium> requires L<Search::Xapian(3pm)> to provide full-text
103 term search functionality in the WWW UI.
105 C<full> also includes positional information used by Xapian to
106 allow for searching for phrases using quoted text.
107 (e.g. C<"looking for a complete sentence">)
111 =item publicinbox.<name>.httpbackendmax
113 If a digit, the maximum number of parallel
114 L<git-http-backend(1)> processes to allow for cloning this
117 If an alphanumeric value starting with a lowercase alphabetic
118 character is specified, the inbox will use a L</NAMED LIMITER>
119 which can be shared by multiple inboxes.
121 Default: 32 (using a default limiter shared by all inboxes)
123 =item publicinbox.<name>.coderepo
125 The nickname of a "coderepo" section associated with the inbox.
126 May be specified more than once for M:N mapping of code repos to
127 inboxes. If enabled, diff hunk headers in patch emails will
128 link to the line numbers of blobs.
132 =item publicinbox.<name>.replyto
134 May be used to control how reply instructions in the PSGI
135 interface are displayed.
137 ":none=dead inbox" may be specified to denote an inactive list
138 ("dead inbox" may be replaced with another phrase).
140 A list of comma-delimited email addresses may be specified.
141 This can be useful for dedicated inboxes for bot emails, but
142 discussion happens on a seperate mailing list/inbox.
144 Mirrors of existing centralized mailing lists may use ":list"
145 here to redirect mail only to the configured inbox address.
146 The use of ":list" is discouraged for new mailing lists, as it
147 leads to centralization.
151 =item publicinbox.css
153 The local path name of a CSS file for the PSGI web interface.
154 May contain the attributes "media", "title" and "href" which match
155 the associated attributes of the HTML <style> tag.
156 "href" may be specified to point to the URL of an remote CSS file
157 and the path may be "/dev/null" or any empty file.
158 Multiple files may be specified and will be included in the
161 =item publicinboxmda.spamcheck
163 This may be set to C<none> to disable the use of SpamAssassin
164 L<spamc(1)> for filtering spam before it is imported into git
165 history. Other spam filtering backends may be supported in
170 =item publicinboxwatch.spamcheck
172 This may be set to C<spamc> to enable the use of SpamAssassin
173 L<spamc(1)> for filtering spam before it is imported into git
174 history. Other spam filtering backends may be supported in
179 =item publicinboxwatch.watchspam
181 This may be set to C<spamc> to enable the use of SpamAssassin
182 L<spamc(1)> for filtering spam before it is imported into git
183 history. Other spam filtering backends may be supported in
184 the future. This requires L<public-inbox-watch(1)>, but affects
185 all configured public-inboxes in PI_CONFIG.
189 =item publicinbox.nntpserver
191 Set this to point to the address of the L<public-inbox-nntpd(1)>
192 instance. This is used to advertise the existence of the NNTP
193 presnce in the L<PublicInbox::WWW> HTML interface.
195 Multiple values are allowed for servers with multiple
196 addresses or mirrors.
200 =item publicinbox.<name>.feedmax
202 The size of an Atom feed for the inbox. If specified more than
203 once, only the last value is used. Invalid values (<= 0) will
204 be treated as the default value.
208 =item publicinbox.<name>.hide
210 A comma-delimited list of listings to hide the inbox from.
212 Valid values are currently C<www> and C<manifest>.
216 =item coderepo.<nick>.dir
218 The path to a git repository for "publicinbox.<name>.coderepo"
220 =item coderepo.<nick>.cgitUrl
222 The URL of the cgit instance associated with the coderepo.
226 =item publicinbox.cgitrc
228 A path to a L<cgitrc(5)> file. "repo.url" directives in the cgitrc
229 will be mapped to the nickname of a coderepo (without trailing slash),
230 and "repo.path" directives map to "coderepo.<nick>.dir".
231 Use of this directive allows admins of existing cgit installations
232 to skip declaring coderepo sections and map inboxes directly to
233 code repositories known to cgit.
235 Macro expansion (e.g. C<$HTTP_HOST>) is not yet supported.
237 =item publicinbox.cgitbin
239 A path to the C<cgit.cgi> executable. The L<PublicInbox::WWW>
240 interface can spawn cgit as a fallback if the publicinbox.cgitrc
241 directive is configured.
243 Default: /var/www/htdocs/cgit/cgit.cgi or /usr/lib/cgit/cgit.cgi
245 =item publicinbox.cgitdata
247 A path to the data directory used by cgit for storing static files.
248 Typically guessed based the location of C<cgit.cgi> (from
249 C<publicinbox.cgitbin>, but may be overridden.
251 Default: basename of C<publicinbox.cgitbin>, /var/www/htdocs/cgit/
254 =item publicinbox.mailEditor
256 See L<public-inbox-edit(1)>
258 =item publicinbox.wwwlisting
260 Enable a HTML listing style when the root path of the URL '/' is accessed.
269 - Return a 404 page. This is useful to allow customization with
270 L<Plack::App::Cascade(3pm)>
273 - Only show inboxes with URLs which belong to the domain of the HTTP request
277 support showing cgit listing
283 =item publicinbox.grokmanifest
285 Controls the generation of a grokmirror-compatible gzipped JSON file
286 at the top-level of the PSGI interface. You generally do not need to
287 change this from the default.
294 - Only include inboxes with URLs which belong to the domain of
295 the HTTP request. This is compatible with virtual hosting where
296 several domains come from the same host.
299 - All inboxes are present in C<manifest.js.gz>, regardless of domain.
300 Only use this if you're serving HTTP requests in a domain-agnostic manner.
303 - C<manifest.js.gz> will only contain an empty JSON array.
304 This does NOT affect C<$INBOX_URL/manifest.js.gz>, which will
305 always contain all git repos used by the inbox at C<$INBOX_URL>
309 Default: C<match=domain>
313 =head2 NAMED LIMITER (PSGI)
315 Named limiters are useful for preventing large inboxes from
316 monopolizing (or overloading) the server. Since serving git
317 clones (via L<git-http-backend(1)> can be memory-intensive for
318 large inboxes, it makes sense to put large inboxes on a named
319 limiter with a low max value; while smaller inboxes can use
322 C<RLIMIT_*> keys may be set to enforce resource limits for
323 a particular limiter.
325 Default named-limiters are prefixed with "-". Currently,
326 the "-cgit" named limiter is reserved for instances spawning
327 cgit via C<publicinbox.cgitrc>
331 =item publicinboxlimiter.<name>.max
333 The maximum number of parallel processes for the given limiter.
335 =item publicinboxlimiter.<name>.rlimitCore
337 =item publicinboxlimiter.<name>.rlimitCPU
339 =item publicinboxlimiter.<name>.rlimitData
341 The maximum core size, CPU time, or data size processes run with the
342 given limiter will use. This may be comma-separated to distinguish
343 soft and hard limits. The word "INFINITY" is accepted as the
344 RLIM_INFINITY constant (if supported by your OS).
346 See L<setrlimit(2)> for more info on the behavior of RLIMIT_CORE,
347 RLIMIT_CPU, and RLIMIT_DATA for you operating system.
351 =head3 EXAMPLE WITH NAMED LIMITERS
353 ; big inboxes which require lots of memory to clone:
355 mainrepo = /path/to/big1
356 address = big1@example.com
359 mainrepo = /path/to/big2
360 address = big2@example.com
363 ; tiny inboxes which are easily cloned:
364 [publicinbox "tiny1"]
365 mainrepo = /path/to/tiny1
366 address = tiny1@example.com
367 [publicinbox "tiny2"]
368 mainrepo = /path/to/tiny2
369 address = tiny2@example.com
371 [publicinboxlimiter "big"]
374 In the above example, the "big1" and "big2" are limited to four
375 parallel L<git-http-backend(1)> processes between them.
377 However, "tiny1" and "tiny2" will share the default limiter
378 which means there can be 32 L<git-http-backend(1)> processes
387 Used to override the default "~/.public-inbox/config" value.
393 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
395 The mail archives are hosted at L<https://public-inbox.org/meta/>
396 and L<http://hjrcffqmbrq6wope.onion/meta/>
400 Copyright 2016-2019 all contributors L<mailto:meta@public-inbox.org>
402 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
406 L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>,
407 L<public-inbox-mda(1)>, L<public-inbox-watch(1)>,
408 L<grokmirror|https://git.kernel.org/pub/scm/utils/grokmirror/grokmirror.git>