]> Sergey Matveev's repositories - public-inbox.git/blobdiff - Documentation/public-inbox-config.pod
watchmaildir: support multiple watchheader values
[public-inbox.git] / Documentation / public-inbox-config.pod
index b0c80e550fe68d67735f03ef14903bfca5309210..708a785f76b046f78972f3f77a6cb4190b59b666 100644 (file)
@@ -17,13 +17,17 @@ all public-inboxes used by a particular user.
 =head2 EXAMPLE
 
        [publicinbox "test"]
 =head2 EXAMPLE
 
        [publicinbox "test"]
-               mainrepo = /home/user/path/to/test.git
+               inboxdir = /home/user/path/to/test.git
                ; multiple addresses are supported
                address = test@example.com
                ; address = alternate@example.com
                url = http://example.com/test
                newsgroup = inbox.test
 
                ; multiple addresses are supported
                address = test@example.com
                ; address = alternate@example.com
                url = http://example.com/test
                newsgroup = inbox.test
 
+               ; backwards compatibility with public-inbox pre-1.2.0,
+               ; "inboxdir" takes precedence over "mainrepo"
+               mainrepo = /home/user/path/to/test.git
+
 =head2 VARIABLES
 
 =over 8
 =head2 VARIABLES
 
 =over 8
@@ -38,11 +42,14 @@ informational purposes.
 
 Default: none, required
 
 
 Default: none, required
 
-=item publicinbox.<name>.mainrepo
+=item publicinbox.<name>.inboxdir
 
 The absolute path to the directory which hosts the
 public-inbox.  This must be specified once.
 
 
 The absolute path to the directory which hosts the
 public-inbox.  This must be specified once.
 
+This was previously known as "mainrepo", which remains supported,
+but "inboxdir" takes precedence.
+
 Default: none, required
 
 =item publicinbox.<name>.url
 Default: none, required
 
 =item publicinbox.<name>.url
@@ -80,14 +87,36 @@ Default: none; only for L<public-inbox-watch(1)> users
        [publicinbox "test"]
                watchheader = List-Id:<test.example.com>
 
        [publicinbox "test"]
                watchheader = List-Id:<test.example.com>
 
+If specified, L<public-inbox-watch(1)> will only process mail matching
+the given header.  If specified multiple times, mail will be processed
+if it matches any of the values.
+
 Default: none; only for L<public-inbox-watch(1)> users
 
 Default: none; only for L<public-inbox-watch(1)> users
 
+=item publicinbox.<name>.listid
+
+The L<rfc2919|https://tools.ietf.org/html/rfc2919> header without
+angle brackets for L<public-inbox-mda(1)> deliveries and
+L<public-inbox-watch(1)>.
+
+For public-inbox-watch users, this is a shortcut for specifying
+C<publicinbox.$NAME.watchheader=List-Id:E<lt>foo.example.comE<gt>>
+
+For public-inbox-mda users, this may be used to avoid recipient
+matching via C<ORIGINAL_RECIPIENT> environment variable.
+
+This may be specified multiple times for merging multiple mailing
+lists into a single public-inbox, only one C<List-Id> header
+needs to match.
+
+Default: none
+
 =item publicinbox.<name>.nntpmirror
 
 This may be the full NNTP URL of an independently-run mirror.
 For example, the https://public-inbox.org/meta/ inbox is
 mirrored by Gmane at
 =item publicinbox.<name>.nntpmirror
 
 This may be the full NNTP URL of an independently-run mirror.
 For example, the https://public-inbox.org/meta/ inbox is
 mirrored by Gmane at
-C<nntp://news.gmane.org/gmane.mail.public-inbox.general>
+C<nntp://news.gmane.io/gmane.mail.public-inbox.general>
 
 Default: none
 
 
 Default: none
 
@@ -139,7 +168,7 @@ interface are displayed.
 
 A list of comma-delimited email addresses may be specified.
 This can be useful for dedicated inboxes for bot emails, but
 
 A list of comma-delimited email addresses may be specified.
 This can be useful for dedicated inboxes for bot emails, but
-discussion happens on a seperate mailing list/inbox.
+discussion happens on a separate mailing list/inbox.
 
 Mirrors of existing centralized mailing lists may use ":list"
 here to redirect mail only to the configured inbox address.
 
 Mirrors of existing centralized mailing lists may use ":list"
 here to redirect mail only to the configured inbox address.
@@ -174,26 +203,30 @@ L<spamc(1)> for filtering spam before it is imported into git
 history.  Other spam filtering backends may be supported in
 the future.
 
 history.  Other spam filtering backends may be supported in
 the future.
 
+This requires L<public-inbox-watch(1)>, but affects all configured
+public-inboxes in PI_CONFIG.
+
 Default: none
 
 =item publicinboxwatch.watchspam
 
 Default: none
 
 =item publicinboxwatch.watchspam
 
-This may be set to C<spamc> to enable the use of SpamAssassin
-L<spamc(1)> for filtering spam before it is imported into git
-history.  Other spam filtering backends may be supported in
-the future.  This requires L<public-inbox-watch(1)>, but affects
-all configured public-inboxes in PI_CONFIG.
+A Maildir to watch for confirmed spam messages to appear in.
+Messages which appear in this folder with the (S)een Maildir flag
+will be hidden from all configured inboxes based on Message-ID
+and content matching.
 
 
-Default: none
+Messages without the (S)een Maildir flag are not considered for hiding.
+
+Default: none; only for L<public-inbox-watch(1)> users
 
 =item publicinbox.nntpserver
 
 
 =item publicinbox.nntpserver
 
-Set this to point to the address of the L<public-inbox-nntpd(1)>
+Set this to point to the hostname of the L<public-inbox-nntpd(1)>
 instance.  This is used to advertise the existence of the NNTP
 instance.  This is used to advertise the existence of the NNTP
-presnce in the L<PublicInbox::WWW> HTML interface.
+endpoint in the L<PublicInbox::WWW> HTML interface.
 
 
-Multiple values are allowed for servers with multiple
-addresses or mirrors.
+Multiple values are allowed for instances with multiple hostnames
+or mirrors.
 
 Default: none
 
 
 Default: none
 
@@ -209,7 +242,7 @@ Default: 25
 
 A comma-delimited list of listings to hide the inbox from.
 
 
 A comma-delimited list of listings to hide the inbox from.
 
-Valid values are currently "www".
+Valid values are currently C<www> and C<manifest>.
 
 Default: none
 
 
 Default: none
 
@@ -278,7 +311,35 @@ support showing cgit listing
 
 =back
 
 
 =back
 
-Default: 404
+Default: C<404>
+
+=item publicinbox.grokmanifest
+
+Controls the generation of a grokmirror-compatible gzipped JSON file
+at the top-level of the PSGI interface.  You generally do not need to
+change this from the default.
+
+Valid values are:
+
+=over 8
+
+=item * match=domain
+- Only include inboxes with URLs which belong to the domain of
+the HTTP request.  This is compatible with virtual hosting where
+several domains come from the same host.
+
+=item * all
+- All inboxes are present in C<manifest.js.gz>, regardless of domain.
+Only use this if you're serving HTTP requests in a domain-agnostic manner.
+
+=item * 404
+- C<manifest.js.gz> will only contain an empty JSON array.
+This does NOT affect C<$INBOX_URL/manifest.js.gz>, which will
+always contain all git repos used by the inbox at C<$INBOX_URL>
+
+=back
+
+Default: C<match=domain>
 
 =back
 
 
 =back
 
@@ -324,20 +385,20 @@ RLIMIT_CPU, and RLIMIT_DATA for you operating system.
 
        ; big inboxes which require lots of memory to clone:
        [publicinbox "big1"]
 
        ; big inboxes which require lots of memory to clone:
        [publicinbox "big1"]
-               mainrepo = /path/to/big1
+               inboxdir = /path/to/big1
                address = big1@example.com
                httpbackendmax = big
        [publicinbox "big2"]
                address = big1@example.com
                httpbackendmax = big
        [publicinbox "big2"]
-               mainrepo = /path/to/big2
+               inboxdir = /path/to/big2
                address = big2@example.com
                httpbackendmax = big
 
        ; tiny inboxes which are easily cloned:
        [publicinbox "tiny1"]
                address = big2@example.com
                httpbackendmax = big
 
        ; tiny inboxes which are easily cloned:
        [publicinbox "tiny1"]
-               mainrepo = /path/to/tiny1
+               inboxdir = /path/to/tiny1
                address = tiny1@example.com
        [publicinbox "tiny2"]
                address = tiny1@example.com
        [publicinbox "tiny2"]
-               mainrepo = /path/to/tiny2
+               inboxdir = /path/to/tiny2
                address = tiny2@example.com
 
        [publicinboxlimiter "big"]
                address = tiny2@example.com
 
        [publicinboxlimiter "big"]
@@ -369,11 +430,12 @@ and L<http://hjrcffqmbrq6wope.onion/meta/>
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 
-Copyright 2016-2018 all contributors L<mailto:meta@public-inbox.org>
+Copyright 2016-2020 all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 =head1 SEE ALSO
 
 L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>,
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 =head1 SEE ALSO
 
 L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>,
-L<public-inbox-mda(1)>, L<public-inbox-watch(1)>
+L<public-inbox-mda(1)>, L<public-inbox-watch(1)>,
+L<grokmirror|https://git.kernel.org/pub/scm/utils/grokmirror/grokmirror.git>