public-inbox.git  about / heads / tags
an "archives first" approach to mailing lists
blob 6e2142fe1df20d1cc16feb6d42b7c910629bb65d 6125 bytes (raw)
$ git show HEAD:Documentation/public-inbox-watch.pod	# shows this blob on the CLI

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
=head1 NAME

public-inbox-watch - mailbox watcher for public-inbox

=head1 SYNOPSIS

	public-inbox-watch

In ~/.public-inbox/config:

	[publicinbox "test"]
		; generic public-inbox-config keys:
		address = test@example.com
		url = http://example.com/test
		inboxdir = /path/to/test.example.com.git

		; config keys specific to public-inbox-watch:

		watch = maildir:/path/to/maildirs/.INBOX.test/

		; optional, emails that don't have a header matching
		; value will be skipped
		watchheader = List-Id:<test.example.com>

	[publicinboxwatch]
		; optional, enable use of spamc(1) for checking:
		spamcheck = spamc

		; optional, emails marked as read which appear
		; here will be trained as spam and deleted from
		; the inboxdirs of any public-inboxes which are
		; configured for watch.
		; This is global for all publicinbox.* sections
		watchspam = maildir:/path/to/maildirs/.INBOX.spam

=head1 DESCRIPTION

public-inbox-watch allows watching a mailbox or newsgroup
for the arrival of new messages and automatically
importing them into public-inbox git repositories and indices.
public-inbox-watch is useful in situations when a user wishes to
mirror an existing mailing list, but has no access to run
L<public-inbox-mda(1)> on a server.  Unlike public-inbox-mda
which is invoked once per message, public-inbox-watch is a
persistent process, making it faster for after-the-fact imports
of large Maildirs.

Upon startup, it scans the mailbox for new messages to be
imported while it was not running.

All versions of public-inbox-watch support Maildirs.  public-inbox
1.6.0 added support for IMAP folders and NNTP newsgroups.
public-inbox 2.0 adds support for MH directories.  There are no
plans to support the mbox family since new messages are expensive
to detect in large mboxes.

public-inbox-watch should be run inside a L<screen(1)> session
or as a L<systemd(1)> service.  Errors are emitted to stderr.

=head1 OPTIONS

public-inbox-watch takes no command-line options.

=head1 CONFIGURATION

These configuration knobs should be used in the
L<public-inbox-config(5)> file.

=over 8

=item publicinboxImport.dropUniqueUnsubscribe

See L<public-inbox-config(5)/publicinboxImport.dropUniqueUnsubscribe>

=item publicinbox.<name>.watch

A location to watch.  public-inbox 1.5.0 and earlier only supported
C<maildir:> paths:

	[publicinbox "test"]
		watch = maildir:/path/to/maildirs/.INBOX.test/

public-inbox 1.6.0+ supports C<nntp://>, C<nntps://>,
C<imap://> and C<imaps://> URLs:

		watch = nntp://news.example.com/inbox.test.group
		watch = imaps://user@mail.example.com/INBOX.test

2.0+ supports MH:

		watch = mh:/path/to/MH/inbox.test

This may be specified multiple times to combine several mailboxes
into a single public-inbox.  URLs requiring authentication
will require L<netrc(5)> and/or L<git-credential(1)> (preferred) to fill
in the username and password.

public-inbox 2.0+ also supports boolean C<false> to prevent the global
L</publicinboxwatch.watchspam> directive from writing to the inbox.

Default: none

=item publicinbox.<name>.watchheader

	[publicinbox "test"]
		watchheader = List-Id:<test.example.com>

If specified, L<public-inbox-watch(1)> will only process mail
matching the given header.  If specified multiple times in
public-inbox 1.5 or later, mail will be processed if it matches
any of the values.  Only the last value was used in public-inbox
1.4 and earlier.

Default: none

=item publicinboxwatch.spamcheck

This may be set to C<spamc> to enable the use of SpamAssassin
L<spamc(1)> for filtering spam before it is imported into git
history.  Other spam filtering backends may be supported in
the future.

Default: none

=item publicinboxwatch.watchspam

A Maildir to watch for confirmed spam messages to appear in.
Messages which appear in this folder with the (S)een flag
will be hidden from all configured inboxes based on Message-ID
and content matching.

Messages without the (S)een flag are not considered for hiding.
This hiding affects all configured public-inboxes in PI_CONFIG.

As with C<publicinbox.$NAME.watch>, C<imap://> and C<imaps://> URLs
are supported in public-inbox 1.6.0+, and C<MH> in 2.0+.

Default: none; only for L<public-inbox-watch(1)> users

=item imap.Starttls / imap.$URL.Starttls

Whether or not to use C<STARTTLS> on plain C<imap://> connections.

May be specified for certain URLs via L<git-config(1)/--get-urlmatch>
in C<git(1)> 1.8.5+.

Default: C<true>

=item imap.Compress / imap.$URL.Compress

Whether or not to use the IMAP COMPRESS (RFC4978) extension to
save bandwidth.  This is not supported by all IMAP servers and
some advertising this feature may not implement it correctly.

May be specified only for certain URLs if L<git(1)> 1.8.5+ is
installed to use L<git-config(1)/--get-urlmatch>

Default: C<false>

=item nntp.Starttls / nntp.$URL.Starttls

Whether or not to use C<STARTTLS> on plain C<nntp://> connections.

May be specified for certain URLs via L<git-config(1)/--get-urlmatch>
in C<git(1)> 1.8.5+.

Default: C<false> if the hostname is a Tor C<.onion>, C<true> otherwise

=back

=head1 SIGNALS

=over 8

=item SIGHUP

Reload the config file (default: ~/.public-inbox/config)

=item SIGUSR1

Rescan all watched mailboxes.  This is done automatically after
startup.

=item SIGQUIT / SIGTERM / SIGINT

Gracefully shut down.  In-flight messages will be stored
and indexed.

=back

=head1 ENVIRONMENT

=over 8

=item PI_CONFIG

config file. default: ~/.public-inbox/config
See L<public-inbox-config(5)>

=item PERL_INLINE_DIRECTORY

This may affect any public-inbox processes, but is intended
for long-lived ones such as C<public-inbox-watch> or network
daemons.  See L<public-inbox-daemon(8)>.

=back

=head1 CONTACT

Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>

The mail archives are hosted at L<https://public-inbox.org/meta/> and
L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>

=head1 COPYRIGHT

Copyright all contributors L<mailto:meta@public-inbox.org>

License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>

=head1 SEE ALSO

L<public-inbox-config(5)>

git clone https://public-inbox.org/public-inbox.git
git clone http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/public-inbox.git