Documentation/public-inbox-watch.pod

   1 =head1 NAME
   2
   3 public-inbox-watch - mailbox watcher for public-inbox
   4
   5 =head1 SYNOPSIS
   6
   7         public-inbox-watch
   8
   9 In ~/.public-inbox/config:
  10
  11         [publicinbox "test"]
  12                 ; generic public-inbox-config keys:
  13                 address = test@example.com
  14                 url = http://example.com/test
  15                 inboxdir = /path/to/test.example.com.git
  16
  17                 ; config keys specific to public-inbox-watch:
  18
  19                 watch = maildir:/path/to/maildirs/.INBOX.test/
  20
  21                 ; optional, emails that don't have a header matching
  22                 ; value will be skipped
  23                 watchheader = List-Id:<test.example.com>
  24
  25         [publicinboxwatch]
  26                 ; optional, enable use of spamc(1) for checking:
  27                 spamcheck = spamc
  28
  29                 ; optional, emails marked as read which appear
  30                 ; here will be trained as spam and deleted from
  31                 ; the inboxdirs of any public-inboxes which are
  32                 ; configured for watch.
  33                 ; This is global for all publicinbox.* sections
  34                 watchspam = maildir:/path/to/maildirs/.INBOX.spam
  35
  36 =head1 DESCRIPTION
  37
  38 public-inbox-watch allows watching a mailbox or newsgroup
  39 for the arrival of new messages and automatically
  40 importing them into public-inbox git repositories and indices.
  41 public-inbox-watch is useful in situations when a user wishes to
  42 mirror an existing mailing list, but has no access to run
  43 L<public-inbox-mda(1)> on a server.  Unlike public-inbox-mda
  44 which is invoked once per-message, public-inbox-watch is a
  45 persistent process, making it faster for after-the-fact imports
  46 of large Maildirs.
  47
  48 Upon startup, it scans the mailbox for new messages to be
  49 imported while it was not running.
  50
  51 As of public-inbox 1.6.0, Maildirs, IMAP folders, and NNTP
  52 newsgroups are supported.  Previous versions of public-inbox
  53 only supported Maildirs.
  54
  55 public-inbox-watch should be run inside a L<screen(1)> session
  56 or as a L<systemd(1)> service.  Errors are emitted to stderr.
  57
  58 =head1 OPTIONS
  59
  60 public-inbox-watch takes no command-line options.
  61
  62 =head1 CONFIGURATION
  63
  64 These configuration knobs should be used in the
  65 L<public-inbox-config(5)> file
  66
  67 =over 8
  68
  69 =item publicinbox.<name>.watch
  70
  71 A location to watch.  public-inbox 1.5.0 and earlier only supported
  72 C<maildir:> paths:
  73
  74         [publicinbox "test"]
  75                 watch = maildir:/path/to/maildirs/.INBOX.test/
  76
  77 public-inbox 1.6.0 supports C<nntp://>, C<nntps://>,
  78 C<imap://> and C<imaps://> URLs:
  79
  80                 watch = nntp://news.example.com/inbox.test.group
  81                 watch = imaps://user@mail.example.com/INBOX.test
  82
  83 This may be specified multiple times to combine several mailboxes
  84 into a single public-inbox.  URLs requiring authentication
  85 will require L<netrc(5)> and/or L<git-credential(1)> (preferred) to fill
  86 in the username and password.
  87
  88 Default: none
  89
  90 =item publicinbox.<name>.watchheader
  91
  92         [publicinbox "test"]
  93                 watchheader = List-Id:<test.example.com>
  94
  95 If specified, L<public-inbox-watch(1)> will only process mail
  96 matching the given header.  If specified multiple times in
  97 public-inbox 1.5 or later, mail will be processed if it matches
  98 any of the values.  Only the last value was used in public-inbox
  99 1.4 and earlier.
 100
 101 Default: none
 102
 103 =item publicinboxwatch.spamcheck
 104
 105 This may be set to C<spamc> to enable the use of SpamAssassin
 106 L<spamc(1)> for filtering spam before it is imported into git
 107 history.  Other spam filtering backends may be supported in
 108 the future.
 109
 110 Default: none
 111
 112 =item publicinboxwatch.watchspam
 113
 114 A Maildir to watch for confirmed spam messages to appear in.
 115 Messages which appear in this folder with the (S)een flag
 116 will be hidden from all configured inboxes based on Message-ID
 117 and content matching.
 118
 119 Messages without the (S)een flag are not considered for hiding.
 120 This hiding affects all configured public-inboxes in PI_CONFIG.
 121
 122 As with C<publicinbox.$NAME.watch>, C<imap://> and C<imaps://> URLs
 123 are supported in public-inbox 1.6.0+.
 124
 125 Default: none; only for L<public-inbox-watch(1)> users
 126
 127 =item imap.Starttls / imap.$URL.Starttls
 128
 129 Whether or not to use C<STARTTLS> on plain C<imap://> connections.
 130
 131 May be specified for certain URLs via L<git-config(1)/--get-urlmatch>
 132 in C<git(1)> 1.8.5+.
 133
 134 Default: C<true>
 135
 136 =item imap.Compress / imap.$URL.Compress
 137
 138 Whether or not to use the IMAP COMPRESS (RFC4978) extension to
 139 save bandwidth.  This is not supported by all IMAP servers and
 140 some advertising this feature may not implement it correctly.
 141
 142 May be specified only for certain URLs if L<git(1)> 1.8.5+ is
 143 installed to use L<git-config(1)/--get-urlmatch>
 144
 145 Default: C<false>
 146
 147 =item nntp.Starttls / nntp.$URL.Starttls
 148
 149 Whether or not to use C<STARTTLS> on plain C<nntp://> connections.
 150
 151 May be specified for certain URLs via L<git-config(1)/--get-urlmatch>
 152 in C<git(1)> 1.8.5+.
 153
 154 Default: C<false> if the hostname is a Tor C<.onion>, C<true> otherwise
 155
 156 =back
 157
 158 =head1 SIGNALS
 159
 160 =over 8
 161
 162 =item SIGHUP
 163
 164 Reload the config file (default: ~/.public-inbox/config)
 165
 166 =item SIGUSR1
 167
 168 Rescan all watched mailboxes.  This is done automatically after
 169 startup.
 170
 171 =item SIGQUIT / SIGTERM / SIGINT
 172
 173 Gracefully shut down.  In-flight messages will be stored
 174 and indexed.
 175
 176 =back
 177
 178 =head1 ENVIRONMENT
 179
 180 =over 8
 181
 182 =item PI_CONFIG
 183
 184 config file. default: ~/.public-inbox/config
 185 See L<public-inbox-config(5)>
 186
 187 =item PERL_INLINE_DIRECTORY
 188
 189 This may affect any public-inbox processes, but is intended
 190 for long-lived ones such as C<public-inbox-watch> or network
 191 daemons.  See L<public-inbox-daemon(8)>.
 192
 193 =back
 194
 195 =head1 CONTACT
 196
 197 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 198
 199 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 200 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 201
 202 =head1 COPYRIGHT
 203
 204 Copyright 2016-2021 all contributors L<mailto:meta@public-inbox.org>
 205
 206 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 207
 208 =head1 SEE ALSO
 209
 210 L<public-inbox-config(5)>