Documentation/public-inbox-tuning.pod

   1 =head1 NAME
   2
   3 public-inbox-tuning - tuning public-inbox
   4
   5 =head1 DESCRIPTION
   6
   7 public-inbox intends to support a wide variety of hardware.  While
   8 we strive to provide the best out-of-the-box performance possible,
   9 tuning knobs are an unfortunate necessity in some cases.
  10
  11 =over 4
  12
  13 =item 1
  14
  15 New inboxes: public-inbox-init -V2
  16
  17 =item 2
  18
  19 Optional Inline::C use
  20
  21 =item 3
  22
  23 Performance on rotational hard disk drives
  24
  25 =item 4
  26
  27 Btrfs (and possibly other copy-on-write filesystems)
  28
  29 =item 5
  30
  31 Performance on solid state drives
  32
  33 =item 6
  34
  35 Read-only daemons
  36
  37 =item 7
  38
  39 Other OS tuning knobs
  40
  41 =item 8
  42
  43 Scalability to many inboxes
  44
  45 =back
  46
  47 =head2 New inboxes: public-inbox-init -V2
  48
  49 If you're starting a new inbox (and not mirroring an existing one),
  50 the L<-V2|public-inbox-v2-format(5)> requires L<DBD::SQLite>, but is
  51 orders of magnitude more scalable than the original C<-V1> format.
  52
  53 =head2 Optional Inline::C use
  54
  55 Our optional use of L<Inline::C> speeds up subprocess spawning from
  56 large daemon processes.
  57
  58 To enable L<Inline::C>, either set the C<PERL_INLINE_DIRECTORY>
  59 environment variable to point to a writable directory, or create
  60 C<~/.cache/public-inbox/inline-c> for any user(s) running
  61 public-inbox processes.
  62
  63 If libgit2 development files are installed and L<Inline::C>
  64 is enabled (described above), per-inbox C<git cat-file --batch>
  65 processes are replaced with a single L<perl(1)> process running
  66 C<PublicInbox::Gcf2::loop> in read-only daemons.  libgit2 use
  67 will be available in public-inbox 1.7.0+
  68
  69 More (optional) L<Inline::C> use will be introduced in the future
  70 to lower memory use and improve scalability.
  71
  72 Note: L<Inline::C> is required for L<lei(1)>, but not public-inbox-*
  73
  74 =head2 Performance on rotational hard disk drives
  75
  76 Random I/O performance is poor on rotational HDDs.  Xapian indexing
  77 performance degrades significantly as DBs grow larger than available
  78 RAM.  Attempts to parallelize random I/O on HDDs leads to pathological
  79 slowdowns as inboxes grow.
  80
  81 While C<-V2> introduced Xapian shards as a parallelization
  82 mechanism for SSDs; enabling C<publicInbox.indexSequentialShard>
  83 repurposes sharding as mechanism to reduce the kernel page cache
  84 footprint when indexing on HDDs.
  85
  86 Initializing a mirror with a high C<--jobs> count to create more
  87 shards (in C<-V2> inboxes) will keep each shard smaller and
  88 reduce its kernel page cache footprint.  Keep in mind excessive
  89 sharding imposes a performance penalty for read-only queries.
  90
  91 Users with large amounts of RAM are advised to set a large value
  92 for C<publicinbox.indexBatchSize> as documented in
  93 L<public-inbox-index(1)>.
  94
  95 C<dm-crypt> users on Linux 4.0+ are advised to try the
  96 C<--perf-same_cpu_crypt> C<--perf-submit_from_crypt_cpus>
  97 switches of L<cryptsetup(8)> to reduce I/O contention from
  98 kernel workqueue threads.
  99
 100 =head2 Btrfs (and possibly other copy-on-write filesystems)
 101
 102 L<btrfs(5)> performance degrades from fragmentation when using
 103 large databases and random writes.  The Xapian + SQLite indices
 104 used by public-inbox are no exception to that.
 105
 106 public-inbox 1.6.0+ disables copy-on-write (CoW) on Xapian and SQLite
 107 indices on btrfs to achieve acceptable performance (even on SSD).
 108 Disabling copy-on-write also disables checksumming, thus C<raid1>
 109 (or higher) configurations may be corrupt after unsafe shutdowns.
 110
 111 Fortunately, these SQLite and Xapian indices are designed to
 112 recoverable from git if missing.
 113
 114 Disabling CoW does not prevent all fragmentation.  Large values
 115 of C<publicInbox.indexBatchSize> also limit fragmentation during
 116 the initial index.
 117
 118 Avoid snapshotting subvolumes containing Xapian and/or SQLite indices.
 119 Snapshots use CoW despite our efforts to disable it, resulting
 120 in fragmentation.
 121
 122 L<filefrag(8)> can be used to monitor fragmentation, and
 123 C<btrfs filesystem defragment -fr $INBOX_DIR> may be necessary.
 124
 125 Large filesystems benefit significantly from the C<space_cache=v2>
 126 mount option documented in L<btrfs(5)>.
 127
 128 Older, non-CoW filesystems are generally work well out-of-the-box
 129 for our Xapian and SQLite indices.
 130
 131 =head2 Performance on solid state drives
 132
 133 While SSD read performance is generally good, SSD write performance
 134 degrades as the drive ages and/or gets full.  Issuing C<TRIM> commands
 135 via L<fstrim(8)> or similar is required to sustain write performance.
 136
 137 Users of the Flash-Friendly File System
 138 L<F2FS|https://en.wikipedia.org/wiki/F2FS> may benefit from
 139 optimizations found in SQLite 3.21.0+.  Benchmarks are greatly
 140 appreciated.
 141
 142 =head2 Read-only daemons
 143
 144 L<public-inbox-httpd(1)>, L<public-inbox-imapd(1)>, and
 145 L<public-inbox-nntpd(1)> are all designed for C10K (or higher)
 146 levels of concurrency from a single process.  SMP systems may
 147 use C<--worker-processes=NUM> as documented in L<public-inbox-daemon(8)>
 148 for parallelism.
 149
 150 The open file descriptor limit (C<RLIMIT_NOFILE>, C<ulimit -n> in L<sh(1)>,
 151 C<LimitNOFILE=> in L<systemd.exec(5)>) may need to be raised to
 152 accommodate many concurrent clients.
 153
 154 Transport Layer Security (IMAPS, NNTPS, or via STARTTLS) significantly
 155 increases memory use of client sockets, sure to account for that in
 156 capacity planning.
 157
 158 =head2 Other OS tuning knobs
 159
 160 Linux users: the C<sys.vm.max_map_count> sysctl may need to be increased if
 161 handling thousands of inboxes (with L<public-inbox-extindex(1)>) to avoid
 162 out-of-memory errors from git.
 163
 164 Other OSes may have similar tuning knobs (patches appreciated).
 165
 166 =head2 Scalability to many inboxes
 167
 168 git 2.33+ startup time is orders-of-magnitude faster and uses
 169 less memory when dealing with thousands of alternates required
 170 for thousands of inboxes.
 171
 172 L<public-inbox-extindex(1)> allows any number of public-inboxes
 173 to share the same Xapian indices.
 174
 175 =head1 CONTACT
 176
 177 Feedback encouraged via plain-text mail to L<mailto:meta@public-inbox.org>
 178
 179 Information for *BSDs and non-traditional filesystems especially
 180 welcome.
 181
 182 Our archives are hosted at L<https://public-inbox.org/meta/>,
 183 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>, and other places
 184
 185 =head1 COPYRIGHT
 186
 187 Copyright 2020-2021 all contributors L<mailto:meta@public-inbox.org>
 188
 189 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>