]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-watch.pod
imap: support IDLE
[public-inbox.git] / 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 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)>