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 (currently only
  39 Maildir) 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 Currently, only Maildirs are supported.
  52
  53 For now, IMAP users should use tools such as L<mbsync(1)>
  54 or L<offlineimap(1)> to bidirectionally sync their IMAP
  55 folders to Maildirs for public-inbox-watch.
  56
  57 public-inbox-watch should be run inside a L<screen(1)> session
  58 or as a L<systemd(1)> service.  Errors are emitted to stderr.
  59
  60 =head1 OPTIONS
  61
  62 public-inbox-watch takes no command-line options.
  63
  64 =head1 CONFIGURATION
  65
  66 These configuration knobs should be used in the
  67 L<public-inbox-config(5)>
  68
  69 =over 8
  70
  71 =item publicinbox.<name>.watch
  72
  73 =item publicinbox.<name>.watchheader
  74
  75 =item publicinboxwatch.spamcheck
  76
  77 =item publicinboxwatch.watchspam
  78
  79 =back
  80
  81 See L<public-inbox-config(5)> for documentation on them.
  82
  83 =head1 SIGNALS
  84
  85 =over 8
  86
  87 =item SIGHUP
  88
  89 Reload the config file (default: ~/.public-inbox/config)
  90
  91 =item SIGUSR1
  92
  93 Rescan all watched mailboxes.  This is done automatically after
  94 startup.
  95
  96 =back
  97
  98 =head1 ENVIRONMENT
  99
 100 =over 8
 101
 102 =item PI_CONFIG
 103
 104 config file. default: ~/.public-inbox/config
 105 See L<public-inbox-config(5)>
 106
 107 =item PERL_INLINE_DIRECTORY
 108
 109 This may affect any public-inbox processes, but is intended
 110 for long-lived ones such as C<public-inbox-watch> or network
 111 daemons.  See L<public-inbox-daemon(8)>.
 112
 113 =back
 114
 115 =head1 CONTACT
 116
 117 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 118
 119 The mail archives are hosted at L<https://public-inbox.org/meta/>
 120 and L<http://hjrcffqmbrq6wope.onion/meta/>
 121
 122 =head1 COPYRIGHT
 123
 124 Copyright 2016-2020 all contributors L<mailto:meta@public-inbox.org>
 125
 126 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 127
 128 =head1 SEE ALSO
 129
 130 L<public-inbox-config(5)>