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