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