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