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