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.css
 116
 117 The local path name of a CSS file for the PSGI web interface.
 118 May contain the attributes "media", "title" and "href" which match
 119 the associated attributes of the HTML <style> tag.
 120 "href" may be specified to point to the URL of an remote CSS file
 121 and the path may be "/dev/null" or any empty file.
 122 Multiple files may be specified and will be included in the
 123 order specified.
 124
 125 =item publicinboxmda.spamcheck
 126
 127 This may be set to C<none> to disable the use of SpamAssassin
 128 L<spamc(1)> for filtering spam before it is imported into git
 129 history.  Other spam filtering backends may be supported in
 130 the future.
 131
 132 Default: spamc
 133
 134 =item publicinboxwatch.spamcheck
 135
 136 This may be set to C<spamc> to enable the use of SpamAssassin
 137 L<spamc(1)> for filtering spam before it is imported into git
 138 history.  Other spam filtering backends may be supported in
 139 the future.
 140
 141 Default: none
 142
 143 =item publicinboxwatch.watchspam
 144
 145 This may be set to C<spamc> to enable the use of SpamAssassin
 146 L<spamc(1)> for filtering spam before it is imported into git
 147 history.  Other spam filtering backends may be supported in
 148 the future.  This requires L<public-inbox-watch(1)>, but affects
 149 all configured public-inboxes in PI_CONFIG.
 150
 151 Default: none
 152
 153 =item publicinbox.nntpserver
 154
 155 Set this to point to the address of the L<public-inbox-nntpd(1)>
 156 instance.  This is used to advertise the existence of the NNTP
 157 presnce in the L<PublicInbox::WWW> HTML interface.
 158
 159 Multiple values are allowed for servers with multiple
 160 addresses or mirrors.
 161
 162 Default: none
 163
 164 =item publicinbox.<name>.feedmax
 165
 166 The size of an Atom feed for the inbox.  If specified more than
 167 once, only the last value is used.  Invalid values (<= 0) will
 168 be treated as the default value.
 169
 170 Default: 25
 171
 172 =item coderepo.<name>.dir
 173
 174 The path to a git repository for "publicinbox.<name>.coderepo"
 175
 176 =item coderepo.<name>.cgitUrl
 177
 178 The URL of the cgit instance associated with the coderepo.
 179
 180 Default: none
 181
 182 =back
 183
 184 =head2 NAMED LIMITER (PSGI)
 185
 186 Named limiters are useful for preventing large inboxes from
 187 monopolizing (or overloading) the server.  Since serving git
 188 clones (via L<git-http-backend(1)> can be memory-intensive for
 189 large inboxes, it makes sense to put large inboxes on a named
 190 limiter with a low max value; while smaller inboxes can use
 191 the default limiter.
 192
 193 =over 8
 194
 195 =item publicinboxlimiter.<name>.max
 196
 197 The maximum number of parallel processes for the given limiter.
 198
 199 =back
 200
 201 =head3 EXAMPLE WITH NAMED LIMITERS
 202
 203         ; big inboxes which require lots of memory to clone:
 204         [publicinbox "big1"]
 205                 mainrepo = /path/to/big1
 206                 address = big1@example.com
 207                 httpbackendmax = big
 208         [publicinbox "big2"]
 209                 mainrepo = /path/to/big2
 210                 address = big2@example.com
 211                 httpbackendmax = big
 212
 213         ; tiny inboxes which are easily cloned:
 214         [publicinbox "tiny1"]
 215                 mainrepo = /path/to/tiny1
 216                 address = tiny1@example.com
 217         [publicinbox "tiny2"]
 218                 mainrepo = /path/to/tiny2
 219                 address = tiny2@example.com
 220
 221         [publicinboxlimiter "big"]
 222                 max = 4
 223
 224 In the above example, the "big1" and "big2" are limited to four
 225 parallel L<git-http-backend(1)> processes between them.
 226
 227 However, "tiny1" and "tiny2" will share the default limiter
 228 which means there can be 32 L<git-http-backend(1)> processes
 229 between them.
 230
 231 =head1 ENVIRONMENT
 232
 233 =over 8
 234
 235 =item PI_CONFIG
 236
 237 Used to override the default "~/.public-inbox/config" value.
 238
 239 =back
 240
 241 =head1 CONTACT
 242
 243 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 244
 245 The mail archives are hosted at L<https://public-inbox.org/meta/>
 246 and L<http://hjrcffqmbrq6wope.onion/meta/>
 247
 248 =head1 COPYRIGHT
 249
 250 Copyright 2016-2018 all contributors L<mailto:meta@public-inbox.org>
 251
 252 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 253
 254 =head1 SEE ALSO
 255
 256 L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>,
 257 L<public-inbox-mda(1)>, L<public-inbox-watch(1)>