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 If specified, L<public-inbox-watch(1)> will only process mail matching
  84 the given header.  Multiple values are not currently supported.
  85
  86 Default: none; only for L<public-inbox-watch(1)> users
  87
  88 =item publicinbox.<name>.nntpmirror
  89
  90 This may be the full NNTP URL of an independently-run mirror.
  91 For example, the https://public-inbox.org/meta/ inbox is
  92 mirrored by Gmane at
  93 C<nntp://news.gmane.org/gmane.mail.public-inbox.general>
  94
  95 Default: none
  96
  97 =item publicinbox.<name>.indexlevel
  98
  99 The indexing level for L<public-inbox-index(1)>
 100
 101 C<basic> only requires L<DBD::SQLite(3pm)> and provides all
 102 NNTP functionality along with thread-awareness in the WWW
 103 interface.
 104
 105 C<medium> requires L<Search::Xapian(3pm)> to provide full-text
 106 term search functionality in the WWW UI.
 107
 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">)
 111
 112 Default: C<full>
 113
 114 =item publicinbox.<name>.httpbackendmax
 115
 116 If a digit, the maximum number of parallel
 117 L<git-http-backend(1)> processes to allow for cloning this
 118 particular inbox.
 119
 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.
 123
 124 Default: 32 (using a default limiter shared by all inboxes)
 125
 126 =item publicinbox.<name>.coderepo
 127
 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.
 132
 133 Default: none
 134
 135 =item publicinbox.<name>.replyto
 136
 137 May be used to control how reply instructions in the PSGI
 138 interface are displayed.
 139
 140 ":none=dead inbox" may be specified to denote an inactive list
 141 ("dead inbox" may be replaced with another phrase).
 142
 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.
 146
 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.
 151
 152 Default: :all
 153
 154 =item publicinbox.css
 155
 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
 162 order specified.
 163
 164 =item publicinboxmda.spamcheck
 165
 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
 169 the future.
 170
 171 Default: spamc
 172
 173 =item publicinboxwatch.spamcheck
 174
 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
 178 the future.
 179
 180 Default: none
 181
 182 =item publicinboxwatch.watchspam
 183
 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.
 189
 190 Default: none
 191
 192 =item publicinbox.nntpserver
 193
 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.
 197
 198 Multiple values are allowed for servers with multiple
 199 addresses or mirrors.
 200
 201 Default: none
 202
 203 =item publicinbox.<name>.feedmax
 204
 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.
 208
 209 Default: 25
 210
 211 =item publicinbox.<name>.hide
 212
 213 A comma-delimited list of listings to hide the inbox from.
 214
 215 Valid values are currently C<www> and C<manifest>.
 216
 217 Default: none
 218
 219 =item coderepo.<nick>.dir
 220
 221 The path to a git repository for "publicinbox.<name>.coderepo"
 222
 223 =item coderepo.<nick>.cgitUrl
 224
 225 The URL of the cgit instance associated with the coderepo.
 226
 227 Default: none
 228
 229 =item publicinbox.cgitrc
 230
 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.
 237
 238 Macro expansion (e.g. C<$HTTP_HOST>) is not yet supported.
 239
 240 =item publicinbox.cgitbin
 241
 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.
 245
 246 Default: /var/www/htdocs/cgit/cgit.cgi or /usr/lib/cgit/cgit.cgi
 247
 248 =item publicinbox.cgitdata
 249
 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.
 253
 254 Default: basename of C<publicinbox.cgitbin>, /var/www/htdocs/cgit/
 255 or /usr/share/cgit/
 256
 257 =item publicinbox.mailEditor
 258
 259 See L<public-inbox-edit(1)>
 260
 261 =item publicinbox.wwwlisting
 262
 263 Enable a HTML listing style when the root path of the URL '/' is accessed.
 264 Valid values are:
 265
 266 =over 8
 267
 268 =item * all
 269 - Show all inboxes
 270
 271 =item * 404
 272 - Return a 404 page.  This is useful to allow customization with
 273 L<Plack::App::Cascade(3pm)>
 274
 275 =item * match=domain
 276 - Only show inboxes with URLs which belong to the domain of the HTTP request
 277
 278 =for TODO comment
 279
 280 support showing cgit listing
 281
 282 =back
 283
 284 Default: C<404>
 285
 286 =item publicinbox.grokmanifest
 287
 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.
 291
 292 Valid values are:
 293
 294 =over 8
 295
 296 =item * match=domain
 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.
 300
 301 =item * all
 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.
 304
 305 =item * 404
 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>
 309
 310 =back
 311
 312 Default: C<match=domain>
 313
 314 =back
 315
 316 =head2 NAMED LIMITER (PSGI)
 317
 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
 323 the default limiter.
 324
 325 C<RLIMIT_*> keys may be set to enforce resource limits for
 326 a particular limiter.
 327
 328 Default named-limiters are prefixed with "-".  Currently,
 329 the "-cgit" named limiter is reserved for instances spawning
 330 cgit via C<publicinbox.cgitrc>
 331
 332 =over 8
 333
 334 =item publicinboxlimiter.<name>.max
 335
 336 The maximum number of parallel processes for the given limiter.
 337
 338 =item publicinboxlimiter.<name>.rlimitCore
 339
 340 =item publicinboxlimiter.<name>.rlimitCPU
 341
 342 =item publicinboxlimiter.<name>.rlimitData
 343
 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).
 348
 349 See L<setrlimit(2)> for more info on the behavior of RLIMIT_CORE,
 350 RLIMIT_CPU, and RLIMIT_DATA for you operating system.
 351
 352 =back
 353
 354 =head3 EXAMPLE WITH NAMED LIMITERS
 355
 356         ; big inboxes which require lots of memory to clone:
 357         [publicinbox "big1"]
 358                 mainrepo = /path/to/big1
 359                 address = big1@example.com
 360                 httpbackendmax = big
 361         [publicinbox "big2"]
 362                 mainrepo = /path/to/big2
 363                 address = big2@example.com
 364                 httpbackendmax = big
 365
 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
 373
 374         [publicinboxlimiter "big"]
 375                 max = 4
 376
 377 In the above example, the "big1" and "big2" are limited to four
 378 parallel L<git-http-backend(1)> processes between them.
 379
 380 However, "tiny1" and "tiny2" will share the default limiter
 381 which means there can be 32 L<git-http-backend(1)> processes
 382 between them.
 383
 384 =head1 ENVIRONMENT
 385
 386 =over 8
 387
 388 =item PI_CONFIG
 389
 390 Used to override the default "~/.public-inbox/config" value.
 391
 392 =back
 393
 394 =head1 CONTACT
 395
 396 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 397
 398 The mail archives are hosted at L<https://public-inbox.org/meta/>
 399 and L<http://hjrcffqmbrq6wope.onion/meta/>
 400
 401 =head1 COPYRIGHT
 402
 403 Copyright 2016-2019 all contributors L<mailto:meta@public-inbox.org>
 404
 405 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 406
 407 =head1 SEE ALSO
 408
 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>