]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-watch.pod
wwwtext: support $INBOX_URL/_/text/config/raw
[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                 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-2019 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)>