]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-watch.pod
searchidx: avoid modification of read-only `$_'
[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         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://user@mail.example.com/INBOX.test
82
83 This may be specified multiple times to combine several mailboxes
84 into a single public-inbox.  URLs requiring authentication
85 will require L<netrc(5)> and/or L<git-credential(1)> (preferred) to fill
86 in the username and password.
87
88 Default: none
89
90 =item publicinbox.<name>.watchheader
91
92         [publicinbox "test"]
93                 watchheader = List-Id:<test.example.com>
94
95 If specified, L<public-inbox-watch(1)> will only process mail
96 matching the given header.  If specified multiple times in
97 public-inbox 1.5 or later, mail will be processed if it matches
98 any of the values.  Only the last value was used in public-inbox
99 1.4 and earlier.
100
101 Default: none
102
103 =item publicinboxwatch.spamcheck
104
105 This may be set to C<spamc> to enable the use of SpamAssassin
106 L<spamc(1)> for filtering spam before it is imported into git
107 history.  Other spam filtering backends may be supported in
108 the future.
109
110 Default: none
111
112 =item publicinboxwatch.watchspam
113
114 A Maildir to watch for confirmed spam messages to appear in.
115 Messages which appear in this folder with the (S)een flag
116 will be hidden from all configured inboxes based on Message-ID
117 and content matching.
118
119 Messages without the (S)een flag are not considered for hiding.
120 This hiding affects all configured public-inboxes in PI_CONFIG.
121
122 As with C<publicinbox.$NAME.watch>, C<imap://> and C<imaps://> URLs
123 are supported in public-inbox 1.6.0+.
124
125 Default: none; only for L<public-inbox-watch(1)> users
126
127 =item imap.Starttls / imap.$URL.Starttls
128
129 Whether or not to use C<STARTTLS> on plain C<imap://> connections.
130
131 May be specified for certain URLs via L<git-config(1)/--get-urlmatch>
132 in C<git(1)> 1.8.5+.
133
134 Default: C<true>
135
136 =item imap.Compress / imap.$URL.Compress
137
138 Whether or not to use the IMAP COMPRESS (RFC4978) extension to
139 save bandwidth.  This is not supported by all IMAP servers and
140 some advertising this feature may not implement it correctly.
141
142 May be specified only for certain URLs if L<git(1)> 1.8.5+ is
143 installed to use L<git-config(1)/--get-urlmatch>
144
145 Default: C<false>
146
147 =item nntp.Starttls / nntp.$URL.Starttls
148
149 Whether or not to use C<STARTTLS> on plain C<nntp://> connections.
150
151 May be specified for certain URLs via L<git-config(1)/--get-urlmatch>
152 in C<git(1)> 1.8.5+.
153
154 Default: C<false> if the hostname is a Tor C<.onion>, C<true> otherwise
155
156 =back
157
158 =head1 SIGNALS
159
160 =over 8
161
162 =item SIGHUP
163
164 Reload the config file (default: ~/.public-inbox/config)
165
166 =item SIGUSR1
167
168 Rescan all watched mailboxes.  This is done automatically after
169 startup.
170
171 =item SIGQUIT / SIGTERM / SIGINT
172
173 Gracefully shut down.  In-flight messages will be stored
174 and indexed.
175
176 =back
177
178 =head1 ENVIRONMENT
179
180 =over 8
181
182 =item PI_CONFIG
183
184 config file. default: ~/.public-inbox/config
185 See L<public-inbox-config(5)>
186
187 =item PERL_INLINE_DIRECTORY
188
189 This may affect any public-inbox processes, but is intended
190 for long-lived ones such as C<public-inbox-watch> or network
191 daemons.  See L<public-inbox-daemon(8)>.
192
193 =back
194
195 =head1 CONTACT
196
197 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
198
199 The mail archives are hosted at L<https://public-inbox.org/meta/> and
200 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
201
202 =head1 COPYRIGHT
203
204 Copyright 2016-2021 all contributors L<mailto:meta@public-inbox.org>
205
206 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
207
208 =head1 SEE ALSO
209
210 L<public-inbox-config(5)>