public-inbox-watch(1)

1PUBLIC-INBOX-WATCH(1)      public-inbox user manual      PUBLIC-INBOX-WATCH(1)
2
3
4

NAME

6       public-inbox-watch - mailbox watcher for public-inbox
7

SYNOPSIS

9               public-inbox-watch
10
11       In ~/.public-inbox/config:
12
13               [publicinbox "test"]
14                       ; generic public-inbox-config keys:
15                       address = test@example.com
16                       url = http://example.com/test
17                       inboxdir = /path/to/test.example.com.git
18
19                       ; config keys specific to public-inbox-watch:
20
21                       watch = maildir:/path/to/maildirs/.INBOX.test/
22
23                       ; optional, emails that don't have a header matching
24                       ; value will be skipped
25                       watchheader = List-Id:<test.example.com>
26
27               [publicinboxwatch]
28                       ; optional, enable use of spamc(1) for checking:
29                       spamcheck = spamc
30
31                       ; optional, emails marked as read which appear
32                       ; here will be trained as spam and deleted from
33                       ; the inboxdirs of any public-inboxes which are
34                       ; configured for watch.
35                       ; This is global for all publicinbox.* sections
36                       watchspam = maildir:/path/to/maildirs/.INBOX.spam
37

DESCRIPTION

39       public-inbox-watch allows watching a mailbox or newsgroup for the
40       arrival of new messages and automatically importing them into public-
41       inbox git repositories and indices.  public-inbox-watch is useful in
42       situations when a user wishes to mirror an existing mailing list, but
43       has no access to run public-inbox-mda(1) on a server.  Unlike public-
44       inbox-mda which is invoked once per-message, public-inbox-watch is a
45       persistent process, making it faster for after-the-fact imports of
46       large Maildirs.
47
48       Upon startup, it scans the mailbox for new messages to be imported
49       while it was not running.
50
51       As of public-inbox 1.6.0, Maildirs, IMAP folders, and NNTP newsgroups
52       are supported.  Previous versions of public-inbox only supported
53       Maildirs.
54
55       public-inbox-watch should be run inside a screen(1) session or as a
56       systemd(1) service.  Errors are emitted to stderr.
57

OPTIONS

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

CONFIGURATION

62       These configuration knobs should be used in the public-inbox-config(5)
63       file
64
65       publicinbox.<name>.watch
66               A location to watch.  public-inbox 1.5.0 and earlier only
67               supported "maildir:" paths:
68
69                       [publicinbox "test"]
70                               watch = maildir:/path/to/maildirs/.INBOX.test/
71
72               public-inbox 1.6.0 supports "nntp://", "nntps://", "imap://"
73               and "imaps://" URLs:
74
75                               watch = nntp://news.example.com/inbox.test.group
76                               watch = imaps://user@mail.example.com/INBOX.test
77
78               This may be specified multiple times to combine several
79               mailboxes into a single public-inbox.  URLs requiring
80               authentication will require netrc(5) and/or git-credential(1)
81               (preferred) to fill in the username and password.
82
83               Default: none
84
85       publicinbox.<name>.watchheader
86                       [publicinbox "test"]
87                               watchheader = List-Id:<test.example.com>
88
89               If specified, public-inbox-watch(1) will only process mail
90               matching the given header.  If specified multiple times in
91               public-inbox 1.5 or later, mail will be processed if it matches
92               any of the values.  Only the last value was used in public-
93               inbox 1.4 and earlier.
94
95               Default: none
96
97       publicinboxwatch.spamcheck
98               This may be set to "spamc" to enable the use of SpamAssassin
99               spamc(1) for filtering spam before it is imported into git
100               history.  Other spam filtering backends may be supported in the
101               future.
102
103               Default: none
104
105       publicinboxwatch.watchspam
106               A Maildir to watch for confirmed spam messages to appear in.
107               Messages which appear in this folder with the (S)een flag will
108               be hidden from all configured inboxes based on Message-ID and
109               content matching.
110
111               Messages without the (S)een flag are not considered for hiding.
112               This hiding affects all configured public-inboxes in PI_CONFIG.
113
114               As with "publicinbox.$NAME.watch", "imap://" and "imaps://"
115               URLs are supported in public-inbox 1.6.0+.
116
117               Default: none; only for public-inbox-watch(1) users
118
119       imap.Starttls / imap.$URL.Starttls
120               Whether or not to use "STARTTLS" on plain "imap://"
121               connections.
122
123               May be specified for certain URLs via "--get-urlmatch" in
124               git-config(1) in git(1) 1.8.5+.
125
126               Default: "true"
127
128       imap.Compress / imap.$URL.Compress
129               Whether or not to use the IMAP COMPRESS (RFC4978) extension to
130               save bandwidth.  This is not supported by all IMAP servers and
131               some advertising this feature may not implement it correctly.
132
133               May be specified only for certain URLs if git(1) 1.8.5+ is
134               installed to use "--get-urlmatch" in git-config(1)
135
136               Default: "false"
137
138       nntp.Starttls / nntp.$URL.Starttls
139               Whether or not to use "STARTTLS" on plain "nntp://"
140               connections.
141
142               May be specified for certain URLs via "--get-urlmatch" in
143               git-config(1) in git(1) 1.8.5+.
144
145               Default: "false" if the hostname is a Tor ".onion", "true"
146               otherwise
147

SIGNALS

149       SIGHUP  Reload the config file (default: ~/.public-inbox/config)
150
151       SIGUSR1 Rescan all watched mailboxes.  This is done automatically after
152               startup.
153
154       SIGQUIT / SIGTERM / SIGINT
155               Gracefully shut down.  In-flight messages will be stored and
156               indexed.
157

ENVIRONMENT

159       PI_CONFIG
160               config file. default: ~/.public-inbox/config See
161               public-inbox-config(5)
162
163       PERL_INLINE_DIRECTORY
164               This may affect any public-inbox processes, but is intended for
165               long-lived ones such as "public-inbox-watch" or network
166               daemons.  See public-inbox-daemon(8).
167

CONTACT

169       Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>
170
171       The mail archives are hosted at <https://public-inbox.org/meta/> and
172       <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
173

COPYRIGHT

175       Copyright 2016-2021 all contributors <mailto:meta@public-inbox.org>
176
177       License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
178