Documentation/public-inbox-watch.pod

   1 =head1 NAME
   2
   3 public-inbox-watch - mailbox watcher for public-inbox
   4
   5 =head1 SYNOPSIS
   6
   7 B<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://mail.example.com/INBOX.test.foo
  82
  83 Default: none
  84
  85 =item publicinbox.<name>.watchheader
  86
  87         [publicinbox "test"]
  88                 watchheader = List-Id:<test.example.com>
  89
  90 If specified, L<public-inbox-watch(1)> will only process mail
  91 matching the given header.  If specified multiple times in
  92 public-inbox 1.5 or later, mail will be processed if it matches
  93 any of the values.  Only the last value was used in public-inbox
  94 1.4 and earlier.
  95
  96 Default: none
  97
  98 =item publicinboxwatch.spamcheck
  99
 100 This may be set to C<spamc> to enable the use of SpamAssassin
 101 L<spamc(1)> for filtering spam before it is imported into git
 102 history.  Other spam filtering backends may be supported in
 103 the future.
 104
 105 Default: none
 106
 107 =item publicinboxwatch.watchspam
 108
 109 A Maildir to watch for confirmed spam messages to appear in.
 110 Messages which appear in this folder with the (S)een flag
 111 will be hidden from all configured inboxes based on Message-ID
 112 and content matching.
 113
 114 Messages without the (S)een flag are not considered for hiding.
 115 This hiding affects all configured public-inboxes in PI_CONFIG.
 116
 117 As with C<publicinbox.$NAME.watch>, C<imap://> and C<imaps://> URLs
 118 are supported in public-inbox 1.6.0.
 119
 120 Default: none; only for L<public-inbox-watch(1)> users
 121
 122 =back
 123
 124 =head1 SIGNALS
 125
 126 =over 8
 127
 128 =item SIGHUP
 129
 130 Reload the config file (default: ~/.public-inbox/config)
 131
 132 =item SIGUSR1
 133
 134 Rescan all watched mailboxes.  This is done automatically after
 135 startup.
 136
 137 =item SIGQUIT / SIGTERM / SIGINT
 138
 139 Gracefully shut down.  In-flight messages will be stored
 140 and indexed.
 141
 142 =back
 143
 144 =head1 ENVIRONMENT
 145
 146 =over 8
 147
 148 =item PI_CONFIG
 149
 150 config file. default: ~/.public-inbox/config
 151 See L<public-inbox-config(5)>
 152
 153 =item PERL_INLINE_DIRECTORY
 154
 155 This may affect any public-inbox processes, but is intended
 156 for long-lived ones such as C<public-inbox-watch> or network
 157 daemons.  See L<public-inbox-daemon(8)>.
 158
 159 =back
 160
 161 =head1 CONTACT
 162
 163 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 164
 165 The mail archives are hosted at L<https://public-inbox.org/meta/>
 166 and L<http://hjrcffqmbrq6wope.onion/meta/>
 167
 168 =head1 COPYRIGHT
 169
 170 Copyright 2016-2020 all contributors L<mailto:meta@public-inbox.org>
 171
 172 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 173
 174 =head1 SEE ALSO
 175
 176 L<public-inbox-config(5)>