]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-tuning.pod
abc53d1ee0722c7561190bc805dcf5b4e6b81993
[public-inbox.git] / 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 =back
38
39 =head2 New inboxes: public-inbox-init -V2
40
41 If you're starting a new inbox (and not mirroring an existing one),
42 the L<-V2|public-inbox-v2-format(5)> requires L<DBD::SQLite>, but is
43 orders of magnitude more scalable than the original C<-V1> format.
44
45 =head2 Process spawning
46
47 Our optional use of L<Inline::C> speeds up subprocess spawning from
48 large daemon processes.
49
50 To enable L<Inline::C>, either set the C<PERL_INLINE_DIRECTORY>
51 environment variable to point to a writable directory, or create
52 C<~/.cache/public-inbox/inline-c> for any user(s) running
53 public-inbox processes.
54
55 More (optional) L<Inline::C> use will be introduced in the future
56 to lower memory use and improve scalability.
57
58 =head2 Performance on rotational hard disk drives
59
60 Random I/O performance is poor on rotational HDDs.  Xapian indexing
61 performance degrades significantly as DBs grow larger than available
62 RAM.  Attempts to parallelize random I/O on HDDs leads to pathological
63 slowdowns as inboxes grow.
64
65 While C<-V2> introduced Xapian shards as a parallelization
66 mechanism for SSDs; enabling C<publicInbox.indexSequentialShard>
67 repurposes sharding as mechanism to reduce the kernel page cache
68 footprint when indexing on HDDs.
69
70 Initializing a mirror with a high C<--jobs> count to create more
71 shards (in C<-V2> inboxes) will keep each shard smaller and
72 reduce its kernel page cache footprint.
73
74 Users with large amounts of RAM are advised to set a large value
75 for C<publicinbox.indexBatchSize> as documented in
76 L<public-inbox-config(5)>.
77
78 C<dm-crypt> users on Linux 4.0+ are advised to try the
79 C<--perf-same_cpu_crypt> C<--perf-submit_from_crypt_cpus>
80 switches of L<cryptsetup(8)> to reduce I/O contention from
81 kernel workqueue threads.
82
83 =head2 Btrfs (and possibly other copy-on-write filesystems)
84
85 L<btrfs(5)> performance degrades from fragmentation when using
86 large databases and random writes.  The Xapian + SQLite indices
87 used by public-inbox are no exception to that.
88
89 public-inbox 1.6.0+ disables copy-on-write (CoW) on Xapian and SQLite
90 indices on btrfs to achieve acceptable performance (even on SSD).
91 Disabling copy-on-write also disables checksumming, thus raid1
92 (or higher) configurations may corrupt on unsafe shutdowns.
93
94 Fortunately, these SQLite and Xapian indices are designed to
95 recoverable from git if missing.
96
97 Large filesystems benefit significantly from the C<space_cache=v2>
98 mount option documented in L<btrfs(5)>.
99
100 Older, non-CoW filesystems are generally work well out-of-the-box
101 for our Xapian and SQLite indices.
102
103 =head2 Performance on solid state drives
104
105 While SSD read performance is generally good, SSD write performance
106 degrades as the drive ages and/or gets full.  Issuing C<TRIM> commands
107 via L<fstrim(8)> or similar is required to sustain write performance.
108
109 =head2 Read-only daemons
110
111 L<public-inbox-httpd(1)>, L<public-inbox-imapd(1)>, and
112 L<public-inbox-nntpd(1)> are all designed for C10K (or higher)
113 levels of concurrency from a single process.  SMP systems may
114 use C<--worker-processes=NUM> as documented in L<public-inbox-daemon(8)>
115 for parallelism.
116
117 The open file descriptor limit (C<RLIMIT_NOFILE>, C<ulimit -n> in L<sh(1)>,
118 C<LimitNOFILE=> in L<systemd.exec(5)>) may need to be raised to
119 accomodate many concurrent clients.
120
121 Transport Layer Security (IMAPS, NNTPS, or via STARTTLS) significantly
122 increases memory use of client sockets, sure to account for that in
123 capacity planning.
124
125 =head1 CONTACT
126
127 Feedback encouraged via plain-text mail to L<mailto:meta@public-inbox.org>
128
129 Information for *BSDs and non-traditional filesystems especially
130 welcome.
131
132 Our archives are hosted at L<https://public-inbox.org/meta/>,
133 L<http://hjrcffqmbrq6wope.onion/meta/>, and other places
134
135 =head1 COPYRIGHT
136
137 Copyright 2020 all contributors L<mailto:meta@public-inbox.org>
138
139 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>