]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-extindex.pod
cmd_ipc4: retry sendmsg on ENOBUFS/ENOMEM/ETOOMANYREFS
[public-inbox.git] / Documentation / public-inbox-extindex.pod
1 =head1 NAME
2
3 public-inbox-extindex - create and update external search indices
4
5 =head1 SYNOPSIS
6
7 public-inbox-extindex [OPTIONS] EXTINDEX_DIR INBOX_DIR...
8
9 public-inbox-extindex [OPTIONS] [EXTINDEX_DIR] --all
10
11 =head1 DESCRIPTION
12
13 FIXME: behavior not finalized  It should probably write to the
14 config file the first time --all is used.
15
16 public-inbox-extindex creates and updates an external search and
17 overview database used by the read-only public-inbox PSGI (HTTP),
18 NNTP, and IMAP interfaces.  This requires either the
19 L<Search::Xapian> XS bindings OR the L<Xapian> SWIG bindings,
20 along with L<DBD::SQLite> and L<DBI> Perl modules.
21
22 =head1 OPTIONS
23
24 =over
25
26 =item -j JOBS
27
28 =item --jobs=JOBS
29
30 ... TODO, see L<public-inbox-index(5)>
31
32 =item --all
33
34 Index all C<publicinbox> entries in C<PI_CONFIG>.
35
36 C<publicinbox> entries indexed by C<public-inbox-extindex> can
37 have full Xapian searching abilities with the per-C<publicinbox>
38 C<indexlevel> set to C<basic> and their respective Xapian
39 (C<xap15> or C<xapian15>) directories removed.  For multiple
40 public-inboxes where cross-posting is common, this allows
41 significant space savings on Xapian indices.
42
43 =item --gc
44
45 Perform garbage collection instead of indexing.  Use this if
46 inboxes are removed from the extindex, or if messages are
47 purged or removed from some inboxes.
48
49 =item --reindex
50
51 Forces a re-index of all messages in the extindex.  This can be
52 used for in-place upgrades and bugfixes while read-only server
53 processes are utilizing the index.  Keep in mind this roughly
54 doubles the size of the already-large Xapian database.
55
56 The extindex locks will be released roughly every 10s to
57 allow L<public-inbox-mda(1)> and L<public-inbox-watch(1)>
58 processes to write to the extindex.
59
60 =item --fast
61
62 Used with C<--reindex>, it will only look for new and stale
63 entries and not touch already-indexed messages.
64
65 =back
66
67 =head1 FILES
68
69 L<public-inbox-extindex-format(5)>
70
71 =head1 CONFIGURATION
72
73 ... TODO, see L<public-inbox-index(5)>
74
75 =head1 ENVIRONMENT
76
77 =over 8
78
79 =item PI_CONFIG
80
81 Used to override the default "~/.public-inbox/config" value.
82
83 =item XAPIAN_FLUSH_THRESHOLD
84
85 The number of documents to update before committing changes to
86 disk.  This environment is handled directly by Xapian, refer to
87 Xapian API documentation for more details.
88
89 Setting C<XAPIAN_FLUSH_THRESHOLD> or
90 C<publicinbox.indexBatchSize> for a large C<--reindex> may cause
91 L<public-inbox-mda(1)>, L<public-inbox-learn(1)> and
92 L<public-inbox-watch(1)> tasks to wait long and unpredictable
93 periods of time during C<--reindex>.
94
95 Default: none, uses C<publicinbox.indexBatchSize>
96
97 =back
98
99 =head1 UPGRADING
100
101 Occasionally, public-inbox will update it's schema version and
102 require a full index by running this command.
103
104 =head1 CONTACT
105
106 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
107
108 The mail archives are hosted at L<https://public-inbox.org/meta/> and
109 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
110
111 =head1 COPYRIGHT
112
113 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
114
115 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
116
117 =head1 SEE ALSO
118
119 L<Search::Xapian>, L<DBD::SQLite>