]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-index.pod
viewvcs: prepopulate search bar with dfpost + dfn
[public-inbox.git] / Documentation / public-inbox-index.pod
1 =head1 NAME
2
3 public-inbox-index - create and update search indices
4
5 =head1 SYNOPSIS
6
7 public-inbox-index [OPTIONS] INBOX_DIR...
8
9 public-inbox-index [OPTIONS] --all
10
11 =head1 DESCRIPTION
12
13 public-inbox-index creates and updates the search, overview and
14 NNTP article number database used by the read-only public-inbox
15 HTTP and NNTP interfaces.  Currently, this requires
16 L<DBD::SQLite> and L<DBI> Perl modules.  L<Search::Xapian>
17 is optional, only to support the PSGI search interface.
18
19 Once the initial indices are created by public-inbox-index,
20 L<public-inbox-mda(1)> and L<public-inbox-watch(1)> will
21 automatically maintain them.
22
23 Running this manually to update indices is only required if
24 relying on L<git-fetch(1)> to mirror an existing public-inbox;
25 or if upgrading to a new version of public-inbox using
26 the C<--reindex> option.
27
28 Having the overview and article number database is essential to
29 running the NNTP interface, and strongly recommended for the
30 HTTP interface as it provides thread grouping in addition to
31 normal search functionality.
32
33 =head1 OPTIONS
34
35 =over
36
37 =item -j JOBS
38
39 =item --jobs=JOBS
40
41 Influences the number of Xapian indexing shards in a
42 (L<public-inbox-v2-format(5)>) inbox.
43
44 See L<public-inbox-init(1)/--jobs> for a full description
45 of sharding.
46
47 C<--jobs=0> is accepted as of public-inbox 1.6.0
48 to disable parallel indexing regardless of the number of
49 pre-existing shards.
50
51 If the inbox has not been indexed or initialized, C<JOBS - 1>
52 shards will be created (one job is always needed for indexing
53 the overview and article number mapping).
54
55 Default: the number of existing Xapian shards
56
57 =item -c
58
59 =item --compact
60
61 Compacts the Xapian DBs after indexing.  This is recommended
62 when using C<--reindex> to avoid running out of disk space
63 while indexing multiple inboxes.
64
65 While option takes a negligible amount of time compared to
66 C<--reindex>, it requires temporarily duplicating the entire
67 contents of the Xapian DB.
68
69 This switch may be specified twice, in which case compaction
70 happens both before and after indexing to minimize the temporal
71 footprint of the (re)indexing operation.
72
73 Available since public-inbox 1.4.0.
74
75 =item --reindex
76
77 Forces a re-index of all messages in the inbox.
78 This can be used for in-place upgrades and bugfixes while
79 NNTP/HTTP server processes are utilizing the index.  Keep in
80 mind this roughly doubles the size of the already-large
81 Xapian database.  Using this with C<--compact> or running
82 L<public-inbox-compact(1)> afterwards is recommended to
83 release free space.
84
85 public-inbox protects writes to various indices with
86 L<flock(2)>, so it is safe to reindex (and rethread) while
87 L<public-inbox-watch(1)>, L<public-inbox-mda(1)> or
88 L<public-inbox-learn(1)> run.
89
90 This does not touch the NNTP article number database.
91 It does not affect threading unless C<--rethread> is
92 used.
93
94 =item --all
95
96 Index all inboxes configured in ~/.public-inbox/config.
97 This is an alternative to specifying individual inboxes directories
98 on the command-line.
99
100 =item --rethread
101
102 Regenerate internal THREADID and message thread associations
103 when reindexing.
104
105 This fixes some bugs in older versions of public-inbox.  While
106 it is possible to use this without C<--reindex>, it makes little
107 sense to do so.
108
109 Available in public-inbox 1.6.0+.
110
111 =item --prune
112
113 Run L<git-gc(1)> to prune and expire reflogs if discontiguous history
114 is detected.  This is intended to be used in mirrors after running
115 L<public-inbox-edit(1)> or L<public-inbox-purge(1)> to ensure data
116 is expunged from mirrors.
117
118 Available since public-inbox 1.2.0.
119
120 =item --max-size SIZE
121
122 Sets or overrides L</publicinbox.indexMaxSize> on a
123 per-invocation basis.  See L</publicinbox.indexMaxSize>
124 below.
125
126 Available since public-inbox 1.5.0.
127
128 =item --batch-size SIZE
129
130 Sets or overrides L</publicinbox.indexBatchSize> on a
131 per-invocation basis.  See L</publicinbox.indexBatchSize>
132 below.
133
134 When using rotational storage but abundant RAM, using a large
135 value (e.g. C<500m>) with C<--sequential-shard> can
136 significantly speed up and reduce fragmentation during the
137 initial index and full C<--reindex> invocations (but not
138 incremental updates).
139
140 Available in public-inbox 1.6.0+.
141
142 =item --no-fsync
143
144 Disables L<fsync(2)> and L<fdatasync(2)> operations on SQLite
145 and Xapian.  This is only effective with Xapian 1.4+.  This is
146 primarily intended for systems with low RAM and the small
147 (default) C<--batch-size=1m>.  Users of large C<--batch-size>
148 may even find disabling L<fdatasync(2)> causes too much dirty
149 data to accumulate, resulting on latency spikes from writeback.
150
151 Available in public-inbox 1.6.0+.
152
153 =item --dangerous
154
155 Speed up initial index by using in-place updates and denying support for
156 concurrent readers.  This is only effective with Xapian 1.4+.
157
158 Available in public-inbox 1.8.0+
159
160 =item --sequential-shard
161
162 Sets or overrides L</publicinbox.indexSequentialShard> on a
163 per-invocation basis.  See L</publicinbox.indexSequentialShard>
164 below.
165
166 Available in public-inbox 1.6.0+.
167
168 =item --skip-docdata
169
170 Stop storing document data in Xapian on an existing inbox.
171
172 See L<public-inbox-init(1)/--skip-docdata> for description and caveats.
173
174 Available in public-inbox 1.6.0+.
175
176 =item -E EXTINDEX
177
178 =item --update-extindex=EXTINDEX
179
180 Update the given external index (L<public-inbox-extindex-format(5)>.
181 Either the configured section name (e.g. C<all>) or a directory name
182 may be specified.
183
184 Defaults to C<all> if C<[extindex "all"]> is configured,
185 otherwise no external indices are updated.
186
187 May be specified multiple times in rare cases where multiple
188 external indices are configured.
189
190 =item --no-update-extindex
191
192 Do not update the C<all> external index by default.  This negates
193 all uses of C<-E> / C<--update-extindex=> on the command-line.
194
195 =item --since=DATESTRING
196
197 =item --after=DATESTRING
198
199 =item --until=DATESTRING
200
201 =item --before=DATESTRING
202
203 Passed directly to L<git-log(1)> to limit changes for C<--reindex>
204
205 =back
206
207 =head1 FILES
208
209 For v1 (ssoma) repositories described in L<public-inbox-v1-format(5)>.
210 All public-inbox-specific files are contained within the
211 C<$GIT_DIR/public-inbox/> directory.
212
213 v2 inboxes are described in L<public-inbox-v2-format(5)>.
214
215 =head1 CONFIGURATION
216
217 =over 8
218
219 =item publicinbox.indexMaxSize
220
221 Prevents indexing of messages larger than the specified size
222 value.  A single suffix modifier of C<k>, C<m> or C<g> is
223 supported, thus the value of C<1m> to prevents indexing of
224 messages larger than one megabyte.
225
226 This is useful for avoiding memory exhaustion in mirrors
227 via git.  It does not prevent L<public-inbox-mda(1)> or
228 L<public-inbox-watch(1)> from importing (and indexing)
229 a message.
230
231 This option is only available in public-inbox 1.5 or later.
232
233 Default: none
234
235 =item publicinbox.indexBatchSize
236
237 Flushes changes to the filesystem and releases locks after
238 indexing the given number of bytes.  The default value of C<1m>
239 (one megabyte) is low to minimize memory use and reduce
240 contention with parallel invocations of L<public-inbox-mda(1)>,
241 L<public-inbox-learn(1)>, and L<public-inbox-watch(1)>.
242
243 Increase this value on powerful systems to improve throughput at
244 the expense of memory use.  The reduction of lock granularity
245 may not be noticeable on fast systems.  With SSDs, values above
246 C<4m> have little benefit.
247
248 For L<public-inbox-v2-format(5)> inboxes, this value is
249 multiplied by the number of Xapian shards.  Thus a typical v2
250 inbox with 3 shards will flush every 3 megabytes by default
251 unless parallelism is disabled via C<--sequential-shard>
252 or C<--jobs=0>.
253
254 This influences memory usage of Xapian, but it is not exact.
255 The actual memory used by Xapian and Perl has been observed
256 in excess of 10x this value.
257
258 This option is available in public-inbox 1.6 or later.
259 public-inbox 1.5 and earlier used the current default, C<1m>.
260
261 Default: 1m (one megabyte)
262
263 =item publicinbox.indexSequentialShard
264
265 For L<public-inbox-v2-format(5)> inboxes, setting this to C<true>
266 allows indexing Xapian shards in multiple passes.  This speeds up
267 indexing on rotational storage with high seek latency by allowing
268 individual shards to fit into the kernel page cache.
269
270 Using a higher-than-normal number of C<--jobs> with
271 L<public-inbox-init(1)> may be required to ensure individual
272 shards are small enough to fit into cache.
273
274 Warning: interrupting C<public-inbox-index(1)> while this option
275 is in use may leave the search indices out-of-date with respect
276 to SQLite databases.  WWW and IMAP users may notice incomplete
277 search results, but it is otherwise non-fatal.  Using C<--reindex>
278 will bring everything back up-to-date.
279
280 Available in public-inbox 1.6.0+.
281
282 This is ignored on L<public-inbox-v1-format(5)> inboxes.
283
284 Default: false, shards are indexed in parallel
285
286 =item publicinbox.<name>.indexSequentialShard
287
288 Identical to L</publicinbox.indexSequentialShard>,
289 but only affect the inbox matching E<lt>nameE<gt>.
290
291 =back
292
293 =head1 ENVIRONMENT
294
295 =over 8
296
297 =item PI_CONFIG
298
299 Used to override the default "~/.public-inbox/config" value.
300
301 =item XAPIAN_FLUSH_THRESHOLD
302
303 The number of documents to update before committing changes to
304 disk.  This environment is handled directly by Xapian, refer to
305 Xapian API documentation for more details.
306
307 For public-inbox 1.6 and later, use C<publicinbox.indexBatchSize>
308 instead.
309
310 Setting C<XAPIAN_FLUSH_THRESHOLD> or
311 C<publicinbox.indexBatchSize> for a large C<--reindex> may cause
312 L<public-inbox-mda(1)>, L<public-inbox-learn(1)> and
313 L<public-inbox-watch(1)> tasks to wait long and unpredictable
314 periods of time during C<--reindex>.
315
316 Default: none, uses C<publicinbox.indexBatchSize>
317
318 =back
319
320 =head1 UPGRADING
321
322 Occasionally, public-inbox will update it's schema version and
323 require a full index by running this command.
324
325 =head1 CONTACT
326
327 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
328
329 The mail archives are hosted at L<https://public-inbox.org/meta/> and
330 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
331
332 =head1 COPYRIGHT
333
334 Copyright all contributors L<mailto:meta@public-inbox.org>
335
336 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
337
338 =head1 SEE ALSO
339
340 L<Search::Xapian>, L<DBD::SQLite>, L<public-inbox-extindex-format(5)>