X-Git-Url: http://www.git.stargrave.org/?p=public-inbox.git;a=blobdiff_plain;f=Documentation%2Fpublic-inbox-watch.pod;h=73340ec486f4accb2ac79457ea2b2fd9efa4e4c2;hp=404303e89c060be1f3bcb6f6132f072b55fb7c48;hb=805d781654e2c2b530de57de2d5241909d187058;hpb=66c6699142d95cce9e5c9d49e0498161a776cc22 diff --git a/Documentation/public-inbox-watch.pod b/Documentation/public-inbox-watch.pod index 404303e8..73340ec4 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 In ~/.public-inbox/config: @@ -12,10 +12,14 @@ In ~/.public-inbox/config: ; generic public-inbox-config keys: address = test@example.com url = http://example.com/test - mainrepo = /path/to/test.example.com.git + inboxdir = /path/to/test.example.com.git ; config keys specific to public-inbox-watch: + watch = maildir:/path/to/maildirs/.INBOX.test/ + + ; optional, emails that don't have a header matching + ; value will be skipped watchheader = List-Id: [publicinboxwatch] @@ -24,16 +28,16 @@ In ~/.public-inbox/config: ; optional, emails marked as read which appear ; here will be trained as spam and deleted from - ; the mainrepos of any public-inboxes which are + ; the inboxdirs of any public-inboxes which are ; configured for watch. ; This is global for all publicinbox.* sections watchspam = maildir:/path/to/maildirs/.INBOX.spam =head1 DESCRIPTION -public-inbox-watch allows watching a mailbox (currently only -Maildir) for the arrival of new messages and automatically -importing them into a public-inbox (git) repository. +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 on a server. Unlike public-inbox-mda @@ -44,12 +48,9 @@ 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 Perl module is required. - -For now, IMAP users should use tools such as L -or L to bidirectionally sync their IMAP -folders to Maildirs for public-inbox-watch. +As of public-inbox 1.6.0, Maildirs, IMAP folders, and NNTP +newsgroups are supported. Previous versions of public-inbox +only supported Maildirs. public-inbox-watch should be run inside a L session or as a L service. Errors are emitted to stderr. @@ -61,21 +62,98 @@ public-inbox-watch takes no command-line options. =head1 CONFIGURATION These configuration knobs should be used in the -L +L file =over 8 =item publicinbox..watch +A location to watch. public-inbox 1.5.0 and earlier only supported +C paths: + + [publicinbox "test"] + watch = maildir:/path/to/maildirs/.INBOX.test/ + +public-inbox 1.6.0 supports C, C, +C and C URLs: + + watch = nntp://news.example.com/inbox.test.group + watch = imaps://user@mail.example.com/INBOX.test + +This may be specified multiple times to combine several mailboxes +into a single public-inbox. URLs requiring authentication +will require L and/or L to fill +in the username and password. + +Default: none + =item publicinbox..watchheader + [publicinbox "test"] + watchheader = List-Id: + +If specified, L 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 to enable the use of SpamAssassin +L 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. -See L for documentation on them. +Messages without the (S)een flag are not considered for hiding. +This hiding affects all configured public-inboxes in PI_CONFIG. + +As with C, C and C URLs +are supported in public-inbox 1.6.0. + +Default: none; only for L users + +=item imap.Starttls / imap.$URL.Starttls + +Whether or not to use C on plain C connections. + +May be specified for certain URLs via L +in C 1.8.5+. + +Default: C + +=item imap.Compress / imap.$URL.Compress + +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 1.8.5+ is +installed to use L + +Default: C + +=item nntp.Starttls / nntp.$URL.Starttls + +Whether or not to use C on plain C connections. + +May be specified for certain URLs via L +in C 1.8.5+. + +Default: C if the hostname is a Tor C<.onion>, C otherwise + +=back =head1 SIGNALS @@ -90,6 +168,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 @@ -101,6 +184,12 @@ startup. config file. default: ~/.public-inbox/config See L +=item PERL_INLINE_DIRECTORY + +This may affect any public-inbox processes, but is intended +for long-lived ones such as C or network +daemons. See L. + =back =head1 CONTACT @@ -112,7 +201,7 @@ and L =head1 COPYRIGHT -Copyright 2016 all contributors L +Copyright 2016-2020 all contributors L License: AGPL-3.0+ L