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)>