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                 inboxdir = /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                 ; backwards compatibility with public-inbox pre-1.2.0,
  28                 ; "inboxdir" takes precedence over "mainrepo"
  29                 mainrepo = /home/user/path/to/test.git
  30
  31 =head2 VARIABLES
  32
  33 =over 8
  34
  35 =item publicinbox.<name>.address
  36
  37 The email address of the public-inbox.  May be specified
  38 more than once for merging multiple mailing lists (or migrating
  39 to new addresses).  This must be specified at least once,
  40 the first value will be considered the primary address for
  41 informational purposes.
  42
  43 Default: none, required
  44
  45 =item publicinbox.<name>.inboxdir
  46
  47 The absolute path to the directory which hosts the
  48 public-inbox.  This must be specified once.
  49
  50 This was previously known as "mainrepo", which remains supported,
  51 but "inboxdir" takes precedence.
  52
  53 Default: none, required
  54
  55 =item publicinbox.<name>.url
  56
  57 The primary URL for hosting the HTTP/HTTPS archives.
  58 Additional HTTP/HTTPS URLs may be specified via
  59 C<$GIT_DIR/cloneurl> as documented in L<gitweb(1)>
  60
  61 Default: none, optional
  62
  63 =item publicinbox.<name>.newsgroup
  64
  65 The NNTP group name for use with L<public-inbox-nntpd(8)>.  This
  66 may be any newsgroup name with hierarchies delimited by '.'.
  67 For example, the newsgroup for L<mailto:meta@public-inbox.org>
  68 is: C<inbox.comp.mail.public-inbox.meta>
  69
  70 Omitting this for the given inbox will prevent the group from
  71 being read by L<public-inbox-nntpd(1)>
  72
  73 Default: none, optional
  74
  75 =item publicinbox.<name>.watch
  76
  77 A location for L<public-inbox-watch(1)> to watch.  Currently,
  78 only C<maildir:> paths are supported:
  79
  80         [publicinbox "test"]
  81                 watch = maildir:/path/to/maildirs/.INBOX.test/
  82
  83 Default: none; only for L<public-inbox-watch(1)> users
  84
  85 =item publicinbox.<name>.watchheader
  86
  87         [publicinbox "test"]
  88                 watchheader = List-Id:<test.example.com>
  89
  90 If specified, L<public-inbox-watch(1)> will only process mail matching
  91 the given header.  If specified multiple times, mail will be processed
  92 if it matches any of the values.
  93
  94 Default: none; only for L<public-inbox-watch(1)> users
  95
  96 =item publicinbox.<name>.listid
  97
  98 The L<rfc2919|https://tools.ietf.org/html/rfc2919> header without
  99 angle brackets for L<public-inbox-mda(1)> deliveries and
 100 L<public-inbox-watch(1)>.
 101
 102 For public-inbox-watch users, this is a shortcut for specifying
 103 C<publicinbox.$NAME.watchheader=List-Id:E<lt>foo.example.comE<gt>>
 104
 105 For public-inbox-mda users, this may be used to avoid recipient
 106 matching via C<ORIGINAL_RECIPIENT> environment variable.
 107
 108 This may be specified multiple times for merging multiple mailing
 109 lists into a single public-inbox, only one C<List-Id> header
 110 needs to match.
 111
 112 Default: none
 113
 114 =item publicinbox.<name>.nntpmirror
 115
 116 This may be the full NNTP URL of an independently-run mirror.
 117 For example, the https://public-inbox.org/meta/ inbox is
 118 mirrored by Gmane at
 119 C<nntp://news.gmane.io/gmane.mail.public-inbox.general>
 120
 121 Default: none
 122
 123 =item publicinbox.<name>.indexlevel
 124
 125 The indexing level for L<public-inbox-index(1)>
 126
 127 C<basic> only requires L<DBD::SQLite(3pm)> and provides all
 128 NNTP functionality along with thread-awareness in the WWW
 129 interface.
 130
 131 C<medium> requires L<Search::Xapian(3pm)> to provide full-text
 132 term search functionality in the WWW UI.
 133
 134 C<full> also includes positional information used by Xapian to
 135 allow for searching for phrases using quoted text.
 136 (e.g. C<"looking for a complete sentence">)
 137
 138 Default: C<full>
 139
 140 =item publicinbox.<name>.httpbackendmax
 141
 142 If a digit, the maximum number of parallel
 143 L<git-http-backend(1)> processes to allow for cloning this
 144 particular inbox.
 145
 146 If an alphanumeric value starting with a lowercase alphabetic
 147 character is specified, the inbox will use a L</NAMED LIMITER>
 148 which can be shared by multiple inboxes.
 149
 150 Default: 32 (using a default limiter shared by all inboxes)
 151
 152 =item publicinbox.<name>.coderepo
 153
 154 The nickname of a "coderepo" section associated with the inbox.
 155 May be specified more than once for M:N mapping of code repos to
 156 inboxes.  If enabled, diff hunk headers in patch emails will
 157 link to the line numbers of blobs.
 158
 159 Default: none
 160
 161 =item publicinbox.<name>.replyto
 162
 163 May be used to control how reply instructions in the PSGI
 164 interface are displayed.
 165
 166 ":none=dead inbox" may be specified to denote an inactive list
 167 ("dead inbox" may be replaced with another phrase).
 168
 169 A list of comma-delimited email addresses may be specified.
 170 This can be useful for dedicated inboxes for bot emails, but
 171 discussion happens on a separate mailing list/inbox.
 172
 173 Mirrors of existing centralized mailing lists may use ":list"
 174 here to redirect mail only to the configured inbox address.
 175 The use of ":list" is discouraged for new mailing lists, as it
 176 leads to centralization.
 177
 178 Default: :all
 179
 180 =item publicinbox.css
 181
 182 The local path name of a CSS file for the PSGI web interface.
 183 May contain the attributes "media", "title" and "href" which match
 184 the associated attributes of the HTML <style> tag.
 185 "href" may be specified to point to the URL of an remote CSS file
 186 and the path may be "/dev/null" or any empty file.
 187 Multiple files may be specified and will be included in the
 188 order specified.
 189
 190 =item publicinboxmda.spamcheck
 191
 192 This may be set to C<none> to disable the use of SpamAssassin
 193 L<spamc(1)> for filtering spam before it is imported into git
 194 history.  Other spam filtering backends may be supported in
 195 the future.
 196
 197 Default: spamc
 198
 199 =item publicinboxwatch.spamcheck
 200
 201 This may be set to C<spamc> to enable the use of SpamAssassin
 202 L<spamc(1)> for filtering spam before it is imported into git
 203 history.  Other spam filtering backends may be supported in
 204 the future.
 205
 206 This requires L<public-inbox-watch(1)>, but affects all configured
 207 public-inboxes in PI_CONFIG.
 208
 209 Default: none
 210
 211 =item publicinboxwatch.watchspam
 212
 213 A Maildir to watch for confirmed spam messages to appear in.
 214 Messages which appear in this folder with the (S)een Maildir flag
 215 will be hidden from all configured inboxes based on Message-ID
 216 and content matching.
 217
 218 Messages without the (S)een Maildir flag are not considered for hiding.
 219
 220 Default: none; only for L<public-inbox-watch(1)> users
 221
 222 =item publicinbox.nntpserver
 223
 224 Set this to point to the hostname of the L<public-inbox-nntpd(1)>
 225 instance.  This is used to advertise the existence of the NNTP
 226 endpoint in the L<PublicInbox::WWW> HTML interface.
 227
 228 Multiple values are allowed for instances with multiple hostnames
 229 or mirrors.
 230
 231 Default: none
 232
 233 =item publicinbox.<name>.feedmax
 234
 235 The size of an Atom feed for the inbox.  If specified more than
 236 once, only the last value is used.  Invalid values (<= 0) will
 237 be treated as the default value.
 238
 239 Default: 25
 240
 241 =item publicinbox.<name>.hide
 242
 243 A comma-delimited list of listings to hide the inbox from.
 244
 245 Valid values are currently C<www> and C<manifest>.
 246
 247 Default: none
 248
 249 =item coderepo.<nick>.dir
 250
 251 The path to a git repository for "publicinbox.<name>.coderepo"
 252
 253 =item coderepo.<nick>.cgitUrl
 254
 255 The URL of the cgit instance associated with the coderepo.
 256
 257 Default: none
 258
 259 =item publicinbox.cgitrc
 260
 261 A path to a L<cgitrc(5)> file.  "repo.url" directives in the cgitrc
 262 will be mapped to the nickname of a coderepo (without trailing slash),
 263 and "repo.path" directives map to "coderepo.<nick>.dir".
 264 Use of this directive allows admins of existing cgit installations
 265 to skip declaring coderepo sections and map inboxes directly to
 266 code repositories known to cgit.
 267
 268 Macro expansion (e.g. C<$HTTP_HOST>) is not yet supported.
 269
 270 =item publicinbox.cgitbin
 271
 272 A path to the C<cgit.cgi> executable.  The L<PublicInbox::WWW>
 273 interface can spawn cgit as a fallback if the publicinbox.cgitrc
 274 directive is configured.
 275
 276 Default: /var/www/htdocs/cgit/cgit.cgi or /usr/lib/cgit/cgit.cgi
 277
 278 =item publicinbox.cgitdata
 279
 280 A path to the data directory used by cgit for storing static files.
 281 Typically guessed based the location of C<cgit.cgi> (from
 282 C<publicinbox.cgitbin>, but may be overridden.
 283
 284 Default: basename of C<publicinbox.cgitbin>, /var/www/htdocs/cgit/
 285 or /usr/share/cgit/
 286
 287 =item publicinbox.mailEditor
 288
 289 See L<public-inbox-edit(1)>
 290
 291 =item publicinbox.wwwlisting
 292
 293 Enable a HTML listing style when the root path of the URL '/' is accessed.
 294 Valid values are:
 295
 296 =over 8
 297
 298 =item * all
 299 - Show all inboxes
 300
 301 =item * 404
 302 - Return a 404 page.  This is useful to allow customization with
 303 L<Plack::App::Cascade(3pm)>
 304
 305 =item * match=domain
 306 - Only show inboxes with URLs which belong to the domain of the HTTP request
 307
 308 =for TODO comment
 309
 310 support showing cgit listing
 311
 312 =back
 313
 314 Default: C<404>
 315
 316 =item publicinbox.grokmanifest
 317
 318 Controls the generation of a grokmirror-compatible gzipped JSON file
 319 at the top-level of the PSGI interface.  You generally do not need to
 320 change this from the default.
 321
 322 Valid values are:
 323
 324 =over 8
 325
 326 =item * match=domain
 327 - Only include inboxes with URLs which belong to the domain of
 328 the HTTP request.  This is compatible with virtual hosting where
 329 several domains come from the same host.
 330
 331 =item * all
 332 - All inboxes are present in C<manifest.js.gz>, regardless of domain.
 333 Only use this if you're serving HTTP requests in a domain-agnostic manner.
 334
 335 =item * 404
 336 - C<manifest.js.gz> will only contain an empty JSON array.
 337 This does NOT affect C<$INBOX_URL/manifest.js.gz>, which will
 338 always contain all git repos used by the inbox at C<$INBOX_URL>
 339
 340 =back
 341
 342 Default: C<match=domain>
 343
 344 =back
 345
 346 =head2 NAMED LIMITER (PSGI)
 347
 348 Named limiters are useful for preventing large inboxes from
 349 monopolizing (or overloading) the server.  Since serving git
 350 clones (via L<git-http-backend(1)> can be memory-intensive for
 351 large inboxes, it makes sense to put large inboxes on a named
 352 limiter with a low max value; while smaller inboxes can use
 353 the default limiter.
 354
 355 C<RLIMIT_*> keys may be set to enforce resource limits for
 356 a particular limiter.
 357
 358 Default named-limiters are prefixed with "-".  Currently,
 359 the "-cgit" named limiter is reserved for instances spawning
 360 cgit via C<publicinbox.cgitrc>
 361
 362 =over 8
 363
 364 =item publicinboxlimiter.<name>.max
 365
 366 The maximum number of parallel processes for the given limiter.
 367
 368 =item publicinboxlimiter.<name>.rlimitCore
 369
 370 =item publicinboxlimiter.<name>.rlimitCPU
 371
 372 =item publicinboxlimiter.<name>.rlimitData
 373
 374 The maximum core size, CPU time, or data size processes run with the
 375 given limiter will use.  This may be comma-separated to distinguish
 376 soft and hard limits.  The word "INFINITY" is accepted as the
 377 RLIM_INFINITY constant (if supported by your OS).
 378
 379 See L<setrlimit(2)> for more info on the behavior of RLIMIT_CORE,
 380 RLIMIT_CPU, and RLIMIT_DATA for you operating system.
 381
 382 =back
 383
 384 =head3 EXAMPLE WITH NAMED LIMITERS
 385
 386         ; big inboxes which require lots of memory to clone:
 387         [publicinbox "big1"]
 388                 inboxdir = /path/to/big1
 389                 address = big1@example.com
 390                 httpbackendmax = big
 391         [publicinbox "big2"]
 392                 inboxdir = /path/to/big2
 393                 address = big2@example.com
 394                 httpbackendmax = big
 395
 396         ; tiny inboxes which are easily cloned:
 397         [publicinbox "tiny1"]
 398                 inboxdir = /path/to/tiny1
 399                 address = tiny1@example.com
 400         [publicinbox "tiny2"]
 401                 inboxdir = /path/to/tiny2
 402                 address = tiny2@example.com
 403
 404         [publicinboxlimiter "big"]
 405                 max = 4
 406
 407 In the above example, the "big1" and "big2" are limited to four
 408 parallel L<git-http-backend(1)> processes between them.
 409
 410 However, "tiny1" and "tiny2" will share the default limiter
 411 which means there can be 32 L<git-http-backend(1)> processes
 412 between them.
 413
 414 =head1 ENVIRONMENT
 415
 416 =over 8
 417
 418 =item PI_CONFIG
 419
 420 Used to override the default "~/.public-inbox/config" value.
 421
 422 =back
 423
 424 =head1 CONTACT
 425
 426 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 427
 428 The mail archives are hosted at L<https://public-inbox.org/meta/>
 429 and L<http://hjrcffqmbrq6wope.onion/meta/>
 430
 431 =head1 COPYRIGHT
 432
 433 Copyright 2016-2020 all contributors L<mailto:meta@public-inbox.org>
 434
 435 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 436
 437 =head1 SEE ALSO
 438
 439 L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>,
 440 L<public-inbox-mda(1)>, L<public-inbox-watch(1)>,
 441 L<grokmirror|https://git.kernel.org/pub/scm/utils/grokmirror/grokmirror.git>