]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-config.pod
examples: cgit filter for use with WwwHighlight
[public-inbox.git] / Documentation / public-inbox-config.pod
1 =head1 NAME
2
3 public-inbox-config - public-inbox config file description
4
5 =head1 SYNOPSIS
6
7 ~/.public-inbox/config
8
9 =head1 DESCRIPTION
10
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.
14
15 =head1 CONFIGURATION FILE
16
17 =head2 EXAMPLE
18
19         [publicinbox "test"]
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
26
27 =head2 VARIABLES
28
29 =over 8
30
31 =item publicinbox.<name>.address
32
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.
38
39 Default: none, required
40
41 =item publicinbox.<name>.mainrepo
42
43 The absolute path to the directory which hosts the
44 public-inbox.  This must be specified once.
45
46 Default: none, required
47
48 =item publicinbox.<name>.url
49
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)>
53
54 Default: none, optional
55
56 =item publicinbox.<name>.newsgroup
57
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>
62
63 Omitting this for the given inbox will prevent the group from
64 being read by L<public-inbox-nntpd(1)>
65
66 Default: none, optional
67
68 =item publicinbox.<name>.watch
69
70 A location for L<public-inbox-watch(1)> to watch.  Currently,
71 only C<maildir:> paths are supported:
72
73         [publicinbox "test"]
74                 watch = maildir:/path/to/maildirs/.INBOX.test/
75
76 Default: none; only for L<public-inbox-watch(1)> users
77
78 =item publicinbox.<name>.watchheader
79
80         [publicinbox "test"]
81                 watchheader = List-Id:<test.example.com>
82
83 Default: none; only for L<public-inbox-watch(1)> users
84
85 =item publicinbox.<name>.nntpmirror
86
87 This may be the full NNTP URL of an independently-run mirror.
88 For example, the https://public-inbox.org/meta/ inbox is
89 mirrored by Gmane at
90 C<nntp://news.gmane.org/gmane.mail.public-inbox.general>
91
92 Default: none
93
94 =item publicinbox.<name>.httpbackendmax
95
96 If a digit, the maximum number of parallel
97 L<git-http-backend(1)> processes to allow for cloning this
98 particular inbox.
99
100 If an alphanumeric value starting with a lowercase alphabetic
101 character is specified, the inbox will use a L</NAMED LIMITER>
102 which can be shared by multiple inboxes.
103
104 Default: 32 (using a default limiter shared by all inboxes)
105
106 =item publicinbox.<name>.coderepo
107
108 The nickname of a "coderepo" section associated with the inbox.
109 May be specified more than once for M:N mapping of code repos to
110 inboxes.  If enabled, diff hunk headers in patch emails will
111 link to the line numbers of blobs.
112
113 Default: none
114
115 =item publicinbox.<name>.replyto
116
117 May be used to control how reply instructions in the PSGI
118 interface are displayed.
119
120 ":none=dead inbox" may be specified to denote an inactive list
121 ("dead inbox" may be replaced with another phrase).
122
123 A list of comma-delimited email addresses may be specified.
124 This can be useful for dedicated inboxes for bot emails, but
125 discussion happens on a seperate mailing list/inbox.
126
127 Mirrors of existing centralized mailing lists may use ":list"
128 here to redirect mail only to the configured inbox address.
129 The use of ":list" is discouraged for new mailing lists, as it
130 leads to centralization.
131
132 Default: :all
133
134 =item publicinbox.css
135
136 The local path name of a CSS file for the PSGI web interface.
137 May contain the attributes "media", "title" and "href" which match
138 the associated attributes of the HTML <style> tag.
139 "href" may be specified to point to the URL of an remote CSS file
140 and the path may be "/dev/null" or any empty file.
141 Multiple files may be specified and will be included in the
142 order specified.
143
144 =item publicinboxmda.spamcheck
145
146 This may be set to C<none> to disable the use of SpamAssassin
147 L<spamc(1)> for filtering spam before it is imported into git
148 history.  Other spam filtering backends may be supported in
149 the future.
150
151 Default: spamc
152
153 =item publicinboxwatch.spamcheck
154
155 This may be set to C<spamc> to enable the use of SpamAssassin
156 L<spamc(1)> for filtering spam before it is imported into git
157 history.  Other spam filtering backends may be supported in
158 the future.
159
160 Default: none
161
162 =item publicinboxwatch.watchspam
163
164 This may be set to C<spamc> to enable the use of SpamAssassin
165 L<spamc(1)> for filtering spam before it is imported into git
166 history.  Other spam filtering backends may be supported in
167 the future.  This requires L<public-inbox-watch(1)>, but affects
168 all configured public-inboxes in PI_CONFIG.
169
170 Default: none
171
172 =item publicinbox.nntpserver
173
174 Set this to point to the address of the L<public-inbox-nntpd(1)>
175 instance.  This is used to advertise the existence of the NNTP
176 presnce in the L<PublicInbox::WWW> HTML interface.
177
178 Multiple values are allowed for servers with multiple
179 addresses or mirrors.
180
181 Default: none
182
183 =item publicinbox.<name>.feedmax
184
185 The size of an Atom feed for the inbox.  If specified more than
186 once, only the last value is used.  Invalid values (<= 0) will
187 be treated as the default value.
188
189 Default: 25
190
191 =item coderepo.<nick>.dir
192
193 The path to a git repository for "publicinbox.<name>.coderepo"
194
195 =item coderepo.<nick>.cgitUrl
196
197 The URL of the cgit instance associated with the coderepo.
198
199 Default: none
200
201 =item publicinbox.cgitrc
202
203 A path to a L<cgitrc(5)> file.  "repo.url" directives in the cgitrc
204 will be mapped to the nickname of a coderepo (without trailing slash),
205 and "repo.path" directives map to "coderepo.<nick>.dir".
206 Use of this directive allows admins of existing cgit installations
207 to skip declaring coderepo sections and map inboxes directly to
208 code repositories known to cgit.
209
210 Macro expansion (e.g. C<$HTTP_HOST>) is not yet supported.
211
212 =item publicinbox.cgitbin
213
214 A path to the C<cgit.cgi> executable.  The L<PublicInbox::WWW>
215 interface can spawn cgit as a fallback if the publicinbox.cgitrc
216 directive is configured.
217
218 Default: /var/www/htdocs/cgit/cgit.cgi or /usr/lib/cgit/cgit.cgi
219
220 =back
221
222 =head2 NAMED LIMITER (PSGI)
223
224 Named limiters are useful for preventing large inboxes from
225 monopolizing (or overloading) the server.  Since serving git
226 clones (via L<git-http-backend(1)> can be memory-intensive for
227 large inboxes, it makes sense to put large inboxes on a named
228 limiter with a low max value; while smaller inboxes can use
229 the default limiter.
230
231 C<RLIMIT_*> keys may be set to enforce resource limits for
232 a particular limiter.
233
234 Default named-limiters are prefixed with "-".  Currently,
235 the "-cgit" named limiter is reserved for instances spawning
236 cgit via C<publicinbox.cgitrc>
237
238 =over 8
239
240 =item publicinboxlimiter.<name>.max
241
242 The maximum number of parallel processes for the given limiter.
243
244 =item publicinboxlimiter.<name>.rlimitCore
245
246 =item publicinboxlimiter.<name>.rlimitCPU
247
248 =item publicinboxlimiter.<name>.rlimitData
249
250 The maximum core size, CPU time, or data size processes run with the
251 given limiter will use.  This may be comma-separated to distinguish
252 soft and hard limits.  The word "INFINITY" is accepted as the
253 RLIM_INFINITY constant (if supported by your OS).
254
255 See L<setrlimit(2)> for more info on the behavior of RLIMIT_CORE,
256 RLIMIT_CPU, and RLIMIT_DATA for you operating system.
257
258 =back
259
260 =head3 EXAMPLE WITH NAMED LIMITERS
261
262         ; big inboxes which require lots of memory to clone:
263         [publicinbox "big1"]
264                 mainrepo = /path/to/big1
265                 address = big1@example.com
266                 httpbackendmax = big
267         [publicinbox "big2"]
268                 mainrepo = /path/to/big2
269                 address = big2@example.com
270                 httpbackendmax = big
271
272         ; tiny inboxes which are easily cloned:
273         [publicinbox "tiny1"]
274                 mainrepo = /path/to/tiny1
275                 address = tiny1@example.com
276         [publicinbox "tiny2"]
277                 mainrepo = /path/to/tiny2
278                 address = tiny2@example.com
279
280         [publicinboxlimiter "big"]
281                 max = 4
282
283 In the above example, the "big1" and "big2" are limited to four
284 parallel L<git-http-backend(1)> processes between them.
285
286 However, "tiny1" and "tiny2" will share the default limiter
287 which means there can be 32 L<git-http-backend(1)> processes
288 between them.
289
290 =head1 ENVIRONMENT
291
292 =over 8
293
294 =item PI_CONFIG
295
296 Used to override the default "~/.public-inbox/config" value.
297
298 =back
299
300 =head1 CONTACT
301
302 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
303
304 The mail archives are hosted at L<https://public-inbox.org/meta/>
305 and L<http://hjrcffqmbrq6wope.onion/meta/>
306
307 =head1 COPYRIGHT
308
309 Copyright 2016-2018 all contributors L<mailto:meta@public-inbox.org>
310
311 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
312
313 =head1 SEE ALSO
314
315 L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>,
316 L<public-inbox-mda(1)>, L<public-inbox-watch(1)>