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 public-inbox-extindex creates and updates an external search and
  14 overview database used by the read-only public-inbox PSGI (HTTP),
  15 NNTP, and IMAP interfaces.  This requires either the
  16 L<Search::Xapian> XS bindings OR the L<Xapian> SWIG bindings,
  17 along with L<DBD::SQLite> and L<DBI> Perl modules.
  18
  19 =head1 OPTIONS
  20
  21 =over
  22
  23 =item -j JOBS
  24
  25 =item --jobs=JOBS
  26
  27 =item --no-fsync
  28
  29 =item --dangerous
  30
  31 =item --rethread
  32
  33 =item --max-size SIZE
  34
  35 =item --batch-size SIZE
  36
  37 These switches behave as they do for L<public-inbox-index(1)>
  38
  39 =item --all
  40
  41 Index all C<publicinbox> entries in C<PI_CONFIG>.
  42
  43 C<publicinbox> entries indexed by C<public-inbox-extindex> can
  44 have full Xapian searching abilities with the per-C<publicinbox>
  45 C<indexlevel> set to C<basic> and their respective Xapian
  46 (C<xap15> or C<xapian15>) directories removed.  For multiple
  47 public-inboxes where cross-posting is common, this allows
  48 significant space savings on Xapian indices.
  49
  50 =item --gc
  51
  52 Perform garbage collection instead of indexing.  Use this if
  53 inboxes are removed from the extindex, or if messages are
  54 purged or removed from some inboxes.
  55
  56 =item --reindex
  57
  58 Forces a re-index of all messages in the extindex.  This can be
  59 used for in-place upgrades and bugfixes while read-only server
  60 processes are utilizing the index.  Keep in mind this roughly
  61 doubles the size of the already-large Xapian database.
  62
  63 The extindex locks will be released roughly every 10s to
  64 allow L<public-inbox-mda(1)> and L<public-inbox-watch(1)>
  65 processes to write to the extindex.
  66
  67 =item --fast
  68
  69 Used with C<--reindex>, it will only look for new and stale
  70 entries and not touch already-indexed messages.
  71
  72 =back
  73
  74 =head1 FILES
  75
  76 L<public-inbox-extindex-format(5)>
  77
  78 =head1 CONFIGURATION
  79
  80 public-inbox-extindex does not currently write to the
  81 L<public-inbox-config(5)> file, configuration may be entered
  82 manually.  The extindex name of C<all> is a special case which
  83 corresponds to indexing C<--all> inboxes.  An example for
  84 C<--all> is as follows:
  85
  86         [extindex "all"]
  87                 topdir = /path/to/extindex_dir
  88                 url = all
  89                 coderepo = foo
  90                 coderepo = bar
  91
  92 See L<public-inbox-config(5)> for more details.
  93
  94 =head1 ENVIRONMENT
  95
  96 =over 8
  97
  98 =item PI_CONFIG
  99
 100 Used to override the default "~/.public-inbox/config" value.
 101
 102 =item XAPIAN_FLUSH_THRESHOLD
 103
 104 The number of documents to update before committing changes to
 105 disk.  This environment is handled directly by Xapian, refer to
 106 Xapian API documentation for more details.
 107
 108 Setting C<XAPIAN_FLUSH_THRESHOLD> or
 109 C<publicinbox.indexBatchSize> for a large C<--reindex> may cause
 110 L<public-inbox-mda(1)>, L<public-inbox-learn(1)> and
 111 L<public-inbox-watch(1)> tasks to wait long and unpredictable
 112 periods of time during C<--reindex>.
 113
 114 Default: none, uses C<publicinbox.indexBatchSize>
 115
 116 =back
 117
 118 =head1 UPGRADING
 119
 120 Occasionally, public-inbox will update it's schema version and
 121 require a full index by running this command.
 122
 123 =head1 CONTACT
 124
 125 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 126
 127 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 128 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 129
 130 =head1 COPYRIGHT
 131
 132 Copyright all contributors L<mailto:meta@public-inbox.org>
 133
 134 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 135
 136 =head1 SEE ALSO
 137
 138 L<Search::Xapian>, L<DBD::SQLite>