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                 mainrepo = /path/to/test.example.com.git
  16
  17                 ; config keys specific to public-inbox-watch:
  18                 watch = maildir:/path/to/maildirs/.INBOX.test/
  19                 watchheader = List-Id:<test.example.com>
  20
  21         [publicinboxwatch]
  22                 ; optional, enable use of spamc(1) for checking:
  23                 spamcheck = spamc
  24
  25                 ; optional, emails marked as read which appear
  26                 ; here will be trained as spam and deleted from
  27                 ; the mainrepos of any public-inboxes which are
  28                 ; configured for watch.
  29                 ; This is global for all publicinbox.* sections
  30                 watchspam = maildir:/path/to/maildirs/.INBOX.spam
  31
  32 =head1 DESCRIPTION
  33
  34 public-inbox-watch allows watching a mailbox (currently only
  35 Maildir) for the arrival of new messages and automatically
  36 importing them into a public-inbox (git) repository.
  37 public-inbox-watch is useful in situations when a user wishes to
  38 mirror an existing mailing list, but has no access to run
  39 L<public-inbox-mda(1)> on a server.  Unlike public-inbox-mda
  40 which is invoked once per-message, public-inbox-watch is a
  41 persistent process, making it faster for after-the-fact imports
  42 of large Maildirs.
  43
  44 Upon startup, it scans the mailbox for new messages to be
  45 imported while it was not running.
  46
  47 Currently, only Maildirs are supported and the
  48 L<Filesys::Notify::Simple> Perl module is required.
  49
  50 For now, IMAP users should use tools such as L<mbsync(1)>
  51 or L<offlineimap(1)> to bidirectionally sync their IMAP
  52 folders to Maildirs for public-inbox-watch.
  53
  54 public-inbox-watch should be run inside a L<screen(1)> session
  55 or as a L<systemd(1)> service.  Errors are emitted to stderr.
  56
  57 =head1 OPTIONS
  58
  59 public-inbox-watch takes no command-line options.
  60
  61 =head1 CONFIGURATION
  62
  63 These configuration knobs should be used in the
  64 L<public-inbox-config(5)>
  65
  66 =over 8
  67
  68 =item publicinbox.<name>.watch
  69
  70 =item publicinbox.<name>.watchheader
  71
  72 =item publicinboxwatch.spamcheck
  73
  74 =item publicinboxwatch.watchspam
  75
  76 =back
  77
  78 See L<public-inbox-config(5)> for documentation on them.
  79
  80 =head1 SIGNALS
  81
  82 =over 8
  83
  84 =item SIGHUP
  85
  86 Reload the config file (default: ~/.public-inbox/config)
  87
  88 =item SIGUSR1
  89
  90 Rescan all watched mailboxes.  This is done automatically after
  91 startup.
  92
  93 =back
  94
  95 =head1 ENVIRONMENT
  96
  97 =over 8
  98
  99 =item PI_CONFIG
 100
 101 config file. default: ~/.public-inbox/config
 102 See L<public-inbox-config(5)>
 103
 104 =item PERL_INLINE_DIRECTORY
 105
 106 This may affect any public-inbox processes, but is intended
 107 for long-lived ones such as C<public-inbox-watch> or network
 108 daemons.  See L<public-inbox-daemon(8)>.
 109
 110 =back
 111
 112 =head1 CONTACT
 113
 114 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 115
 116 The mail archives are hosted at L<https://public-inbox.org/meta/>
 117 and L<http://hjrcffqmbrq6wope.onion/meta/>
 118
 119 =head1 COPYRIGHT
 120
 121 Copyright 2016-2018 all contributors L<mailto:meta@public-inbox.org>
 122
 123 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 124
 125 =head1 SEE ALSO
 126
 127 L<public-inbox-config(5)>