Skip to main content
Version: 0.16

Caching

Stalwart keeps a set of in-memory caches in front of slower backends (the data store, the DNS resolver, the authentication subsystem). Caching frequently accessed records reduces latency and takes load off the underlying backends without changing their consistency guarantees.

The eviction policy is a modified Clock-PRO algorithm, close in spirit to the later S3-FIFO scheme. It is scan-resistant, so a transient burst of unrelated lookups does not evict hot entries, and it reaches hit rates comparable to LRU and W-TinyLFU on realistic workloads.

Memory usage​

Cache sizes should be matched to the workload. On hosts with ample memory and many users, larger caches reduce evictions and improve hit rates. On hosts with limited memory, smaller caches conserve RAM at the cost of some hit rate; monitoring resident set size and the cache-hit metrics published by the server is the normal way to pick an appropriate balance.

Configuration​

Every cache is configured through the Cache singleton (found in the WebUI under Settings › Storage › Cache). Each field is a byte-size value with a suffix (for example "50mb"); minimum size is 2048 bytes.

Data caches​

  • messages: email account data including message UIDs, flags, and mailbox metadata. Default "50mb".
  • events: calendar events, including start / end times and timezone data. Default "10mb".
  • scheduling: calendar scheduling state. Default "1mb".
  • contacts: address-book and contact data. Default "10mb".
  • files: file-storage metadata such as paths and permissions. Default "10mb".
  • mailingLists: mailing-list metadata. Default "2mb".
  • dkimSignatures: parsed DKIM signing configurations. Default "10mb".

Directory caches​

  • accounts: resolved account records. Default "20mb".
  • domains: domain records. Default "5mb".
  • domainNames: positive domain-name lookup results. Default "10mb".
  • domainNamesNegative: negative (not-found) domain-name lookup results. Default "1mb".
  • emailAddresses: positive email-address lookup results. Default "10mb".
  • emailAddressesNegative: negative email-address lookup results. Default "2mb".
  • tenants: tenant records. Default "5mb".
  • negativeTtl: how long to keep negative domain and account lookup entries. Default "1h".

Security caches​

  • accessTokens: resolved access tokens, reducing revalidation during authentication. Default "10mb".
  • httpAuth: short-lived state for HTTP authentication. Default "1mb".

DNS caches​

  • dnsTxt: TXT records used for SPF, DKIM, and DMARC. Default "5mb".
  • dnsMx: MX records used for outbound routing. Default "5mb".
  • dnsPtr: reverse (PTR) lookup results. Default "1mb".
  • dnsIpv4: forward IPv4 (A) lookup results. Default "5mb".
  • dnsIpv6: forward IPv6 (AAAA) lookup results. Default "5mb".
  • dnsTlsa: TLSA records used for DANE validation. Default "1mb".
  • dnsMtaSts: MTA-STS policy records. Default "1mb".
  • dnsRbl: DNSBL / RBL lookup results. Default "5mb".