diff options
Diffstat (limited to 'Documentation/public-inbox-watch.pod')
| -rw-r--r-- | Documentation/public-inbox-watch.pod | 124 |
1 files changed, 108 insertions, 16 deletions
diff --git a/Documentation/public-inbox-watch.pod b/Documentation/public-inbox-watch.pod index 8a3ef076..6e2142fe 100644 --- a/Documentation/public-inbox-watch.pod +++ b/Documentation/public-inbox-watch.pod @@ -4,7 +4,7 @@ public-inbox-watch - mailbox watcher for public-inbox =head1 SYNOPSIS -B<public-inbox-watch> + public-inbox-watch In ~/.public-inbox/config: @@ -35,25 +35,24 @@ In ~/.public-inbox/config: =head1 DESCRIPTION -public-inbox-watch allows watching a mailbox (currently only -Maildir) for the arrival of new messages and automatically +public-inbox-watch allows watching a mailbox or newsgroup +for the arrival of new messages and automatically importing them into public-inbox git repositories and indices. public-inbox-watch is useful in situations when a user wishes to mirror an existing mailing list, but has no access to run L<public-inbox-mda(1)> on a server. Unlike public-inbox-mda -which is invoked once per-message, public-inbox-watch is a +which is invoked once per message, public-inbox-watch is a persistent process, making it faster for after-the-fact imports of large Maildirs. Upon startup, it scans the mailbox for new messages to be imported while it was not running. -Currently, only Maildirs are supported and the -L<Filesys::Notify::Simple> Perl module is required. - -For now, IMAP users should use tools such as L<mbsync(1)> -or L<offlineimap(1)> to bidirectionally sync their IMAP -folders to Maildirs for public-inbox-watch. +All versions of public-inbox-watch support Maildirs. public-inbox +1.6.0 added support for IMAP folders and NNTP newsgroups. +public-inbox 2.0 adds support for MH directories. There are no +plans to support the mbox family since new messages are expensive +to detect in large mboxes. public-inbox-watch should be run inside a L<screen(1)> session or as a L<systemd(1)> service. Errors are emitted to stderr. @@ -65,21 +64,109 @@ public-inbox-watch takes no command-line options. =head1 CONFIGURATION These configuration knobs should be used in the -L<public-inbox-config(5)> +L<public-inbox-config(5)> file. =over 8 +=item publicinboxImport.dropUniqueUnsubscribe + +See L<public-inbox-config(5)/publicinboxImport.dropUniqueUnsubscribe> + =item publicinbox.<name>.watch +A location to watch. public-inbox 1.5.0 and earlier only supported +C<maildir:> paths: + + [publicinbox "test"] + watch = maildir:/path/to/maildirs/.INBOX.test/ + +public-inbox 1.6.0+ supports C<nntp://>, C<nntps://>, +C<imap://> and C<imaps://> URLs: + + watch = nntp://news.example.com/inbox.test.group + watch = imaps://user@mail.example.com/INBOX.test + +2.0+ supports MH: + + watch = mh:/path/to/MH/inbox.test + +This may be specified multiple times to combine several mailboxes +into a single public-inbox. URLs requiring authentication +will require L<netrc(5)> and/or L<git-credential(1)> (preferred) to fill +in the username and password. + +public-inbox 2.0+ also supports boolean C<false> to prevent the global +L</publicinboxwatch.watchspam> directive from writing to the inbox. + +Default: none + =item publicinbox.<name>.watchheader + [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 in +public-inbox 1.5 or later, mail will be processed if it matches +any of the values. Only the last value was used in public-inbox +1.4 and earlier. + +Default: none + =item publicinboxwatch.spamcheck +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. + +Default: none + =item publicinboxwatch.watchspam -=back +A Maildir to watch for confirmed spam messages to appear in. +Messages which appear in this folder with the (S)een flag +will be hidden from all configured inboxes based on Message-ID +and content matching. + +Messages without the (S)een flag are not considered for hiding. +This hiding affects all configured public-inboxes in PI_CONFIG. + +As with C<publicinbox.$NAME.watch>, C<imap://> and C<imaps://> URLs +are supported in public-inbox 1.6.0+, and C<MH> in 2.0+. + +Default: none; only for L<public-inbox-watch(1)> users + +=item imap.Starttls / imap.$URL.Starttls + +Whether or not to use C<STARTTLS> on plain C<imap://> connections. + +May be specified for certain URLs via L<git-config(1)/--get-urlmatch> +in C<git(1)> 1.8.5+. + +Default: C<true> + +=item imap.Compress / imap.$URL.Compress -See L<public-inbox-config(5)> for documentation on them. +Whether or not to use the IMAP COMPRESS (RFC4978) extension to +save bandwidth. This is not supported by all IMAP servers and +some advertising this feature may not implement it correctly. + +May be specified only for certain URLs if L<git(1)> 1.8.5+ is +installed to use L<git-config(1)/--get-urlmatch> + +Default: C<false> + +=item nntp.Starttls / nntp.$URL.Starttls + +Whether or not to use C<STARTTLS> on plain C<nntp://> connections. + +May be specified for certain URLs via L<git-config(1)/--get-urlmatch> +in C<git(1)> 1.8.5+. + +Default: C<false> if the hostname is a Tor C<.onion>, C<true> otherwise + +=back =head1 SIGNALS @@ -94,6 +181,11 @@ Reload the config file (default: ~/.public-inbox/config) Rescan all watched mailboxes. This is done automatically after startup. +=item SIGQUIT / SIGTERM / SIGINT + +Gracefully shut down. In-flight messages will be stored +and indexed. + =back =head1 ENVIRONMENT @@ -117,12 +209,12 @@ daemons. See L<public-inbox-daemon(8)>. Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org> -The mail archives are hosted at L<https://public-inbox.org/meta/> -and L<http://hjrcffqmbrq6wope.onion/meta/> +The mail archives are hosted at L<https://public-inbox.org/meta/> and +L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/> =head1 COPYRIGHT -Copyright 2016-2020 all contributors L<mailto:meta@public-inbox.org> +Copyright all contributors L<mailto:meta@public-inbox.org> License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt> |