Server configuration

The server loads its configuration once, before it opens Ceph, authentication and the listeners. Libraries: Viper and go-playground/validator.

shardpost --config /etc/shardpost/server.yaml
shardpost --config /etc/shardpost/server.yaml config check
shardpost --config /etc/shardpost/server.yaml scrub [--batch]
shardpost --config /etc/shardpost/server.yaml index backfill accounts [--restart]
shardpost --config /etc/shardpost/server.yaml index backfill kv [--restart]
shardpost --config /etc/shardpost/server.yaml index show kv [<key>...]
shardpost --config /etc/shardpost/server.yaml index backfill learning [--restart]
shardpost --config /etc/shardpost/server.yaml index show learning [<id>...]

scrub scrubs in its own process (scrub.users, else every account of the account directory, else every namespace of an index pool listing); scrub --batch submits the batch scrub the servers run and exits (see Scrub and Operations). index backfill accounts fills the account directory once after a rollout (see Operations); it has no configuration keys of its own. index backfill kv fills the admin store's hint indexes and due queues (see Operations); it uses admin.kv_index (refuses off) and jobs.retention_days. index show kv prints their state and that of the given admin store keys (read-only). index backfill learning fills the learning queue's due queue and owner index (see Operations); it uses imapsieve.learning.index (refuses off) and imapsieve.learning.queue_shards. index show learning prints their state and that of the given learning jobs (read-only).

Alternatively, SHARDPOST_CONFIG determines the file path. IMAP_CONFIG is kept as a fallback as long as SHARDPOST_CONFIG is not set. An explicit --config takes precedence over both variables. An explicitly empty SHARDPOST_CONFIG disables the old fallback. Precedence: built-in defaults, explicit YAML file, explicitly set legacy env variables. There is no implicit file lookup and no automatic reload. Changes in Kubernetes are applied through a controlled deployment rollout. Go runtime settings such as GOMEMLIMIT remain environment variables; additional standardized OTEL SDK options are still evaluated by the SDK.

The sections are server, ceph, rook, tls, nauthilus, auth (see auth cache), smtp, sieve, scrub, logging, telemetry, imapsieve, extprograms, quota, admin, fts, limits (see account limits) and jmap (see JMAP; without jmap.addr that front-end is not started). The complete field and env mapping is documented in internal/config/config.go, internal/config/imapsieve.go, internal/config/extprograms.go, internal/config/quota.go, internal/config/admin.go, internal/config/fts.go, internal/config/limits.go, internal/config/auth.go and internal/config/jmap.go (including jmap.push); extprograms, the learning rules, the quota rules and warnings as well as the admin roles and clients are configurable via YAML only (see docs/imapsieve.md, docs/quota.md and docs/admin-api.md).

server:
  imap_addr: ':1143'
  imaps_addr: ':1993'
  pop3_addr: ':1110'
  pop3s_addr: ':1995'
  lmtp_addr: ':2424'
  http_addr: ':8080'
  auth_backend: nauthilus
  insecure_auth: false
  memory_budget_bytes: 268435456
ceph:
  user: shardpost
  index_pool: shardpost-index
  data_pool: shardpost-data
rook:
  namespace: rook-ceph
nauthilus:
  transport: grpc
  grpc_addr: nauthilus.auth.svc.cluster.local:9444
  oidc_client_secret_file: /run/secrets/nauthilus/client-secret
tls:
  cert: /tls/tls.crt
  key: /tls/tls.key
sieve:
  addr: ':14190'
  global_dir: /etc/sieve
  before_dir: /etc/shardpost/sieve/before
  after_dir: /etc/shardpost/sieve/after
telemetry:
  protocol: http/protobuf
  endpoint: http://collector:4318
  sample_ratio: 0.1
  user_attributes: false   # account, mailbox and client address in spans

server.insecure_auth (default false) decides whether IMAP, POP3, ManageSieve and LMTP accept authentication on a connection without TLS. Turn it on only for an isolated test profile; JMAP has its own switch, jmap.insecure_auth (default false).

The rook section applies only while ceph.key is empty: the server then reads the key and, if ceph.mon_host is empty, the monitor list from the Rook-managed secret and ConfigMap through the Kubernetes API and follows key rotations. With ceph.key set, rook is ignored and no Kubernetes access happens; see running without Kubernetes.

Pools (ceph)

ceph.system_pool is not a switch to flip: a cluster has one placement, and the data says which. A server, the push worker and every other shardpost command check it when they open the store (two reads, no listing):

• without ceph.system_pool, a fence in the index pool that says the state has moved refuses the start (set ceph.system_pool);
• with it, the system pool must carry the mark of this index pool and cluster, written by shardpost system init (a new cluster) or shardpost system migrate (an existing one); otherwise the start is refused with the command to run.

A server and the push worker repeat the check every minute and end (after draining) when it reads a placement that contradicts the configuration; a check that cannot read logs a warning and goes on (a server or push worker that cannot read at startup starts in the state unknown; a short-lived command does not start). Set the key on the server, the push worker and the scrub CronJob together. The Kubernetes manifests set CEPH_SYSTEM_POOL (empty until the migration), and an environment variable that is set wins over the file even when it is empty: change it in the manifests, not in server.yaml. The system tools themselves (shardpost system …) do not check the placement and take the system pool from their options or from the fence; they run with the key empty and refuse a value that names another pool. They also refuse a ceph.client_options with rados_osd_op_timeout above 60 and raise the objecter throttles for their parallel copies (shardpost-system(1)). See Storage: placement and Operations.

ceph:
  index_pool: shardpost-index
  data_pool: shardpost-data
  system_pool: shardpost-system   # only after "shardpost system init" or "migrate"
  client_options:
    objecter_inflight_ops: "4096"
    objecter_inflight_op_bytes: "268435456"

Global Sieve scripts

sieve.global_dir holds the scripts a user script can pull in with include :global. sieve.before_dir and sieve.after_dir hold scripts that run for every delivery (LMTP and the local delivery API) around the account's active script, the way Pigeonhole runs sieve_before and sieve_after:

• Every regular file <name>.sieve of a directory is a script; they run in name order (10-spam.sieve before 50-lists.sieve). Other files and names starting with a dot are ignored. The directory is read for every delivery, so a changed ConfigMap takes effect without a restart.
• The order is: before scripts, the account's active script, after scripts. The next script runs only while the message is still kept (implicit or explicit keep); that keep is handed on instead of being carried out, and the actions of all scripts add up. A script that files the message elsewhere, discards or rejects it ends the sequence. So an after script only sees what the user's script left in INBOX, and a fileinto "INBOX" in a user script — unlike keep — ends the sequence too.
• An explicit keep is an action of its own, as within one script: once a script asked for it, no later script takes it away. A later fileinto or discard cancels only the implicit keep, so the message still lands in INBOX (and, with a fileinto, in the other mailbox as well); a later reject fails with an action conflict and the message stays kept. Policy decisions that must hold whatever the user's script does — a reject, a discard of known spam — therefore belong in sieve.before_dir, not in sieve.after_dir.
• A header edit (editheader) of one script is what the next one sees.
• A script that fails at runtime is skipped as if it had kept the message and logged; the others still run, and so do the other scripts of a directory when one file cannot be read. At startup and for config check a directory or file that cannot be read or a script that does not compile is an error.
• The flags of a keep are handed on with it: they are what the flag variable (imap4flags) of the next script starts with. So a script that marks the message (addflag, keep :flags) and keeps it does not lose the mark because a later script keeps the message too, and a later script can still remove it (removeflag, setflag, keep :flags).
• The startup check compiles the global scripts without an account, so one that uses include :personal is refused; include :global works.
• The environment variables SIEVE_BEFORE_DIR and SIEVE_AFTER_DIR win over the file when they are set, even to an empty value.
• The scripts run with the rights of the recipient. A fileinto into a public folder needs the p right of that account; without it the message stays in INBOX. That is how list mail is sorted into public folders for the accounts that may post there and left alone for everybody else.
• IMAPSieve does not run them, and neither does a delivery with sieve=false or into a named mailbox.

shardpostctl sieve check runs the same sequence, see admin API.

Delivery headers

Every copy LMTP or the local delivery API stores gets Return-Path: <envelope sender> and Delivered-To: <recipient> above its Received field, like Dovecot's LMTP; Return-Path fields the message brought along are removed. Details in Sieve during delivery.

Sieve settings (sieve.settings)

sieve.settings (SIEVE_SETTINGS) holds the Sieve implementation settings as key=value;key=value, under Pigeonhole's key names where Pigeonhole has the setting. Among them, with their defaults:

A ; inside a value is written \;, a backslash before it or at the end of a value \\; in YAML, put the whole value in single quotes (in double quotes every backslash has to be doubled). The startup and config check refuse periods that do not parse or contradict each other, an unknown sieve_reject_mode and a postmaster_address that is no address. What these settings do is described in Sieve during delivery.

Unknown keys, mistyped YAML values, invalid env numbers, invalid boolean values, contradictory TLS pairs and explicit secret files that are missing or read as empty cause a startup error. Env numbers are always interpreted as decimal. A secret file takes precedence over the corresponding direct secret value. Error messages never print values.

config check validates the configuration structure, reads the referenced secret files and compiles the global Sieve scripts of sieve.before_dir and sieve.after_dir. It is no proof of connectivity to Ceph, Nauthilus, SMTP or the external programs; program files are checked when they are invoked. Certificates are loaded when the server starts afterwards.

A running server looks every tls.reload_seconds (default 60; 0 loads once) whether the files of tls.cert/tls.key and jmap.tls_cert/jmap.tls_key changed and loads the renewed pair, so a certificate that cert-manager renews in a mounted Secret reaches the listeners without a restart; a renewal is recognised by the files' content, and the reload logs the new certificate's serial and expiry. A renewed pair that does not load is logged and the previous certificate stays in use. Mount the Secret as a volume, not with subPath: a subPath mount never sees an update. The kubelet itself takes up to about a minute to update a mounted Secret. Without a file path, the existing env-based deployments remain usable.

Client IP behind the Director

server.proxy_protocol_trusted_cidrs controls whether client addresses from PROXY protocol v1/v2 are adopted ahead of the actual mail protocol/TLS. For this to work, the Director must also set haproxy.enabled: true for the backends in question. The setting applies jointly to IMAP, POP3, ManageSieve, LMTP and JMAP; the list is global, one trust boundary for all listeners.

A proxy that reaches a listener through a Kubernetes NodePort has its address rewritten on the way: with externalTrafficPolicy: Cluster the pod sees a node address (the Calico tunnel address from another node, the node's own address from the same node), so the header is honoured for some connections and dropped for others. For JMAP behind HAProxy use externalTrafficPolicy: Local and list the proxy addresses here, and let the network policy admit the JMAP port only from those addresses — every peer in the list can name any client address.

The production overlay uses the verified Calico pod network 172.16.0.0/12 together with network-policy.yaml. The mail ports are reachable only for Director pods in the director namespace and for the controlled test tools mailtest/imaptest in the shardpost namespace. These test tools are explicitly part of the proxy trust boundary. HTTP health and metrics remain reachable. Whenever the Calico pools change, the CIDR list has to be reviewed as well; individual dynamic Director pod IP addresses are not recorded permanently.

Without a PROXY preamble, direct connections in which the server greets first can take up to five seconds of detection time. That is why the Director sends the preamble to the LMTP backend as well. Direct operator probes need a matching timeout or have to send PROXY protocol themselves.

Structured operational logs

slog writes JSON to stdout. logging.level (YAML) and LOG_LEVEL (the environment takes precedence) accept debug, info, warn, error; the default and the Kubernetes rollout use info. Invalid values prevent startup.

• info: connection start and end, authentication success and rejection, deliveries and the server lifecycle.
• debug: additionally the known command names and durations for IMAP, POP3 and ManageSieve. handler_error denotes a handler error, not every negative protocol status. IDLE appears once the command has ended.
• warn: temporarily disrupted authentication, connection limits and the existing fallback messages.
• error: storage errors, failed deliveries and internal errors.

Sessions carry proto, a random session_id, remote and local. remote holds the client address supplied by the trusted PROXY sender; for direct access it holds the TCP peer. Successful logins include the canonical user. The session ID stays the same across IMAP UNAUTHENTICATE, only the user binding is removed. connection_close carries the session duration in milliseconds. For LMTP, the backend session begins after LHLO. The tls field describes TLS to the backend, not a TLS channel already terminated at the Director.

Not even debug logs command arguments, SASL data, passwords, tokens, script texts or mail contents. The only exception is the time-limited protocol trace that is switched on explicitly per account (event=protocol_trace, see Admin API): it contains the protocol lines after login, with literals recorded only as a size. Unknown commands are named UNKNOWN. The logs contain client IP addresses and account names that are necessary for operations; these fields are not used as metric labels.

Example for Loki (replace the client IP with the public IP you are looking for):

{namespace="shardpost", app_kubernetes_io_name="shardpost-server"} | json | remote =~ "203\\.0\\.113\\.10:.*"

For further correlation, filter by session_id. At info, NOOP/FETCH/IDLE produce no individual command logs; open, login and close remain visible. Connections that were already closed before the rollout cannot be reconstructed after the fact. Changing the level requires a restart.

Protocol trace (trace)

YAML only. It is switched on through the Admin API (role trace), see Admin API.

Namespaces

A prefix is one level and ends with the separator, for example Other Users/ (Exchange, older Dovecot setups) or shared/ (Dovecot's own default) — a server whose users come from another one keeps their names by setting what they are used to. Changing the prefix renames what clients see: the mailboxes and their permissions stay as they are, but every client re-discovers the folders under the new name and treats them as new ones locally — local caches, folder settings and client-side filter rules that name a folder path have to be redone. Subscriptions survive: they are kept per account and per mailbox, not by name.

A prefix may contain non-ASCII characters. Like every mailbox name it reaches IMAP clients that enabled neither UTF8=ACCEPT nor IMAP4rev2 in modified UTF-7 (Öffentlich/ is &ANY-ffentlich/ in NAMESPACE and LIST), all other clients in UTF-8.

With an empty prefix no client can reach a shared mailbox, although the permissions remain in the store and the admin API still shows them. The same prefix switches the shared accounts of JMAP: with it empty, the JMAP session lists none (see JMAP: Sharing); so does an empty server.public_prefix for the public account.

Before changing a prefix on a running server, check that no account owns a mailbox below the new one:

shardpostctl mailbox list <account> | grep -E '^(Shared|Public)/'

Such a mailbox would still be listed but could no longer be opened: its name resolves to the other namespace. Rename it first (shardpostctl mailbox rename <account> <old> <new>); the server also logs a warning, with the mailbox name, when it lists one. Creating, renaming or importing a mailbox below a prefix is refused by the admin API for the same reason; over IMAP such a name never reaches the account's own namespace at all, so CREATE "Shared/Sub" answers NONEXISTENT instead.

While a namespace is switched off its prefix is not reserved, so an account can create a mailbox there in the meantime. Switching it back on is therefore the same migration step as changing it: check first.

Version 0.26.1 changed the default from Other Users/ to Shared/. A server that was running before it keeps the old name by setting server.shared_prefix: "Other Users/" explicitly.

Share notifications

A change of the rights an account holds on another account's mailbox or on a public folder — through IMAP SETACL or DELETEACL, the admin API or JMAP shareWith — leaves a notification in that account (RFC 9670 3), which a JMAP client reads as ShareNotification (see JMAP: Sharing). The notifications of an account are one server-managed METADATA entry of its own namespace, bounded by these two settings and by the 64 KiB of one entry; a second change of the same mailbox replaces the first. Writing one is best effort: an ACL change never fails because of it, and a failure is logged (share notification not written).

What an account starts with, and what it is subscribed to

server:
  autocreate:
    - { name: Drafts,  special_use: "\\Drafts" }
    - { name: Sent,    special_use: "\\Sent" }
    - { name: Trash,   special_use: "\\Trash" }
    - { name: Junk,    special_use: "\\Junk" }
    - { name: Archive, special_use: "\\Archive" }
    - { name: Projekte, subscribe: false }

Each entry has a name, an optional special_use attribute (RFC 6154, so a client finds the mailbox whatever it is called) and subscribe, which defaults to true. This is Dovecot's auto = create versus auto = subscribe, in one place instead of one block per mailbox. An empty list (autocreate: []) leaves an account with its INBOX.

Two rules decide when this happens:

• A mailbox is created when the account logs in and does not have it, so a mailbox added to the list reaches the accounts that log in afterwards, not only new ones. A mailbox the account deleted comes back the same way.
• A mailbox is subscribed only when it is created, never afterwards. An account that unsubscribed one keeps it unsubscribed; the server does not argue with its user.

Subscriptions are per account everywhere else too: a mailbox of another account carries its subscription in the pointer, a public folder in the reading account's registry by mailbox id, so a folder that is renamed stays subscribed. shardpostctl mailbox subscribe sets the flag for an account from outside, which is how a migration hands over what the old server had.

Public folders

Public folders live in the store namespace ~public and belong to no account, so they do not count against a user's quota. They are created and granted through the admin API, see Admin API: public folders.

Maintenance jobs (jobs)

| jobs.batch_parallel | 2 | how many accounts a batch over all accounts works on at once in the server that runs it (1–32; a batch scrub uses scrub.parallel) | | jobs.mailbox_delete_online | off | what a plan of mailbox_delete without online gets (since 0.52.0): auto the mailbox lock while the cluster mark mailbox/lock is set (only the mailboxes it removes are locked, users notice nothing else), off the account lock as before. auto needs jobs.settle_seconds of at least 7, the time IMAP sessions take to see the lock. online: true needs the mark either way (409 without) | | jobs.mailbox_lock_barrier_seconds | 120 | how long a mailbox_delete with the mailbox lock waits for the operations that started before its lock (10–900); after it the job is given back and tried again later |

YAML only, except jobs.max_parallel. For operating them see Admin API: maintenance jobs and batches over all accounts.

Background workers (workers.run)

workers.run is the switch of the topology; jmap.submission.delayed.worker switches one worker inside a process that runs workers. workers.run: false takes precedence: a front-end runs no submission worker whatever delayed.worker says, and is not warned about it; it warns once at startup when no job runner and no server with workers is registered. Set it through the environment (the runner component does): a way back to an image before 0.52.0 must not break on an unknown configmap key (the configmap is read strictly, see the strict configmap). See operations: job runners.

The strict configmap

The configuration file is decoded strictly: a key the image does not know refuses the start. A new key therefore goes into the configmap only once no older image can run any more, and a key that switches a topology (workers.run) or sizes one deployment apart from another (jobs.max_parallel) comes as an environment variable, which an older image ignores.

Quota recount (quota)

The online recount of quota_recalc (since 0.52.0, see Quota: recounting the usage and the runbook in operations):

The other quota keys (grace, rules, warnings, the over flag) are in Quota.

Scrub (scrub)

scrub.parallel, scrub.interval_days, scrub.orphan_source and scrub.intent_grace_seconds take effect in the servers that run the batch, not in the pod that submits it. For the switch from shadow to intents see operations.

IMAP watches (server.imap_max_watches)

The sessions of a process share their watches: one RADOS watch per mailbox or account object however many sessions follow it (see storage and the metric imapceph_imap_watches).

Admin clients with the scope of all accounts

admin.clients[].all_accounts: true (YAML only) lets an mTLS client list the account directory and plan, apply and cancel batches over every account, each with its role; it excludes admin.clients[].accounts. Socket callers always have it. See Admin API.

Support tools (admin.search_scan_limit)

YAML only. See Admin API: support tools.

Admin store indexes (admin.kv_index)

read is the default. It is correct on a cluster whose shardpost index backfill kv completed after the last server without the indexes (before 0.38.0, or with admin.kv_index: off) stopped. Without the completion marker a server configured for read logs a warning and behaves as in write mode until the marker exists (it looks for it every 30 seconds), so the gate keeps such a cluster on write until the backfill ran. A new installation runs the backfill once as well (it finds no records and completes at once). Set the same mode on every server (a server in read mode does not see what a server in off mode writes). Back to write is always possible. See Storage: admin store and Operations.

Learning queue index (imapsieve.learning.index)

read takes effect only once shardpost index backfill learning completed (with a start after the last server without the index stopped) or shardpost system init wrote the completion marker of the empty queue of a new cluster. Without the marker a server in read mode logs a warning and behaves as in write mode until the marker exists, so the default read changes nothing on a cluster that has not run the backfill. A cluster of the size of millions of accounts runs with admin.kv_index: read and imapsieve.learning.index: read: in write mode the learning worker lists the namespace ~learning of the data pool every second, a walk over every placement group of the largest pool. See Storage: learning queue and Operations.

Account limits (limits)

Upper bounds on what one account can grow. They keep the omap objects that hold an account's state (the mailbox registry, a mailbox header, the METADATA object) far below the size at which Ceph reports LARGE_OMAP_OBJECTS and one account slows down the OSD that serves it. The defaults are far above what accounts reach in normal use; 0 switches a limit off.

What a client sees when it reaches a limit is listed in Protocols: account limits. Delivery never loses mail to a limit: a Sieve fileinto that would have to create a mailbox beyond limits.mailboxes or limits.mailbox_names goes to INBOX like any other failed fileinto, and keywords a Sieve script adds beyond limits.keywords_per_mailbox are dropped (the message is stored with its system flags). The autocreated mailboxes (server.autocreate) are skipped for an account at its mailbox limit.

An account import (admin API) is held to the mailbox limits, which it checks before it writes anything for a mailbox, but not to the keyword limit: an import reproduces the source mailbox as it is, and refusing it halfway would leave messages whose keywords the mailbox does not list.

The keyword limit is checked in the same compare-and-swap as the change that adds the keywords, so it holds exactly (a MOVE checks it before it starts and then completes). The other limits count omap keys before the write and are advisory: writers that race past the check together can exceed a limit by one entry each.

Full-text index (fts)

Online runs and the reshard window (since 0.51.0). With the cluster mark fts/online (shardpostctl fts online enable) fts_layout and fts_rebuild can run without the account's lock: deliveries, logins and sessions go on while the target generation is built beside the current one (see storage).

New keys go into the overlay only after the image that knows them is running (the configuration is read with UnmarshalExact); on the way back they leave the overlay first.

YAML only. server.fts_shards keeps the object count of layout 2, which is also the target of a conversion back from layout 3.

The text. One preparation serves the index, IMAP SEARCH keys checked against the message, the JMAP header filter and the cached preview, so they agree:

• Header values are unfolded and decoded: RFC 2047 encoded words in any charset of the WHATWG list, raw 8-bit text in fts.fallback_charset. The index has the header field names as well, because IMAP TEXT covers the whole header. The JMAP Text form of a header value (header:…:asText) is decoded the same way.
• Every text/* part is converted from its charset parameter to UTF-8. A text/html part whose label is missing, US-ASCII or unknown is read in the charset its <meta charset> or <meta http-equiv="Content-Type"> names. A part labelled with a single-byte charset (ISO-8859-x, Windows-125x, KOI8, …) whose bytes are valid UTF-8 with at least one non-ASCII character is kept as UTF-8: that is UTF-8 under a wrong label, which is common, far more often than Latin-1 text that happens to be valid UTF-8.
• The file name of every part (Content-Type name, Content-Disposition filename, RFC 2231 in any charset, RFC 2047 words) and an attached message (message/rfc822, message/global) — its header as Name: value lines and its body text — belong to the body text, as does the text of a text/rfc822-headers part; with fts.attached_headers: nosig without their signature and trace fields. Other MIME part header fields do not.
• Bounds: at most 4 MiB of text per message; a part is read up to 4 MiB, a part other than HTML only as far as there is room left for its text, and all parts of a message together up to 8 MiB, before conversion. Words of more than 40 characters are indexed as overlapping pieces (see storage).

The preview is cut from the text parts alone (no file names, no attached messages), and of a multipart/alternative from one part: the plain text where it has text, else the HTML text (RFC 8970). It follows fts.html: with text an HTML part gives its visible text (without its title), with raw its markup, with skip nothing, so an HTML-only message has an empty preview.

IMAP SEARCH and what it costs. With substring, a text key matches when its value is a substring of the decoded text, without regard to case. The index supplies candidates — never fewer than the messages that match — separately for the header and the body of a key, and combines them over AND, OR and NOT. Each candidate is checked:

• the header against the decoded header the index keeps per message (read for 256 messages at a time, no message is read);
• the body by reading the message, only where the body candidates include it.

A word of the value narrows the candidates when the index can look it up completely: a whole word always; the start of a word unless more than 4096 index terms begin with it; the inside of a word in the subject, the addresses and the body when it has three or more characters and lies inside at most 4096 index terms. The inside of a word of another header field cannot be looked up, so a TEXT or HEADER <name> value that may begin inside a header word (any value not starting with a space or punctuation) checks the stored header of every message of the mailbox — a few omap reads per 256 messages, cheap next to reading them — and reads only the messages the body index allows. A key with no word the index can narrow by (BODY ab, a single letter) reads every message of the mailbox. fts.verify_parallel messages are checked at once, each under the memory budget; a message that is expunged meanwhile is no match, and a read the budget refuses is retried before the command fails. A search stops when its client closes the connection (noticed without reading what the client sends; not in a session with COMPRESS=DEFLATE) or the server closes it; the session then ends without an answer. word costs index lookups only and answers what earlier versions answered: all words of the value in any order, by stem and by part of a word.

Existing messages. The index keeps what a message was indexed with. An account indexed entirely by this version carries a version marker in its index (set for a new account with its first message and by fts_rebuild when it completes; a rebuild that stops midway leaves the account without it). Without the marker, substring search does not use the index at all — an older index (HTML markup, undecoded words, no file names) cannot be trusted even for whole words — and checks every message of the mailbox, reading the headers of messages without a stored header from the messages themselves: correct, but slow, until the rebuild. A changed fts.fallback_charset or fts.html reaches messages stored before only when they are indexed again; until then substring search can miss such a message where the index lacks its new words. Removing a message indexed under other rules leaves terms it was indexed with behind (harmless; the rebuild drops them). Run the rebuild for every account after the upgrade, see Admin API: maintenance jobs:

shardpostctl plan fts_rebuild user@example.org
shardpostctl apply -wait <plan-id>

The rebuild does not recompute the cached preview of an existing message. The index, including the stored headers, is in the index pool and does not count against the quota.

JMAP search bounds (jmap.search)

0 takes the default. The maintenance job attachment_backfill fills an account ahead of time (Admin API). A SearchSnippet/get reads at most jmap.max_objects_in_get messages, so one call reads at most that many times jmap.search.snippet_read_bytes. See JMAP: Search snippets and JMAP: hasAttachment. The other jmap.* keys are described in JMAP: Configuration.

JMAP load (jmap.*)

For the four limits 0 takes the default. A queue holds at most twice its limit; a request past it is answered 429 at once. jmap.limit_wait stays well below the response timeouts in front (the Director's backend_response_header, two minutes by default, and HAProxy's timeout server). With jmap.max_concurrent_per_ip set and server.proxy_protocol_trusted_cidrs empty the server warns at startup: behind a proxy every client then has the proxy's address. See JMAP: Load.

Delayed sending

JMAP delayed sending (FUTURERELEASE, see JMAP and operations):

The longest conversation with the relay is about ten step timeouts (jmap.submission.timeout_seconds, 30 by default: connection, greeting, EHLO, STARTTLS, XCLIENT, MAIL, DATA, the upload), plus the upload of the largest message at 256 KiB/s (jmap.submission.max_size, else jmap.max_size_upload: 200 s for 50 MiB), plus ten minutes for the relay's answer to the message — 1100 s with the defaults — and up to one step timeout more per recipient when the relay is that slow for each. sending_timeout_seconds has to stay above it; a server warns at startup when it does not (counting no recipients). A conversation that outlasts it is reported as unknown, never sent twice.

Push worker partitions (jmap.push.*)

The JMAP push worker shares 64 partitions among its pods (0.52.0, see JMAP: Push partitions and operations). The push deployment has no configmap; the keys come as environment variables and keep their defaults unless there is a reason.

The relations are checked at startup: lease_seconds ≥ 3 × take_seconds (a partition free for two cadences is contested), rebalance_settle_seconds ≥ lease_seconds (a dead record is gone before anyone sheds to it), handoff_seconds < lease_seconds − 5 (a hand-over ends before the holder would stop the partition itself), retry_seconds ≤ take_seconds, and full_scan_seconds 0 or at least scan_seconds. The partition count itself is not configurable: it is the shard count of the hint index ix.jmap/push/acct (64).

Nauthilus client (nauthilus.timeout, nauthilus.http_max_idle_per_host)

A backchannel token Nauthilus refuses is renewed and the request sent once more, but only when the time left of the login allows a second attempt as long as the first. A login as a whole is bounded to 15 s in IMAP, POP3 and ManageSieve.

Auth cache (auth)

The cache sits in front of Nauthilus only (server.auth_backend: nauthilus; the static test backend is never cached) and behind the master-user check: MasterUser{Cache{Nauthilus}}. The master password is never cached, the lookup of the master-user login's target is.

auth:
  cache:
    ttl: 30                  # seconds; 0 switches the whole cache off
    negative_ttl: 0          # refusals of identical credentials; 0 = not cached
    max_entries: 10000       # per operation (logins, lookups)
    key_client_ip: true      # the client IP is part of a login's key
    lookup_ttl: 30
    lookup_negative_ttl: 5   # at most lookup_ttl; ignored with lookup_ttl 0
    leader_budget: 0         # seconds for one shared backend call; 0 = 2 × nauthilus.timeout

What a login's entry is found by: an HMAC-SHA256, under a random key that lives in the process only, over the mechanism, the user name, the secret (password or token), the protocol, the TLS state, the local address and port Nauthilus is told and, with key_client_ip, the client's address. The login attempt ordinal is not part of it; PLAIN and LOGIN with the same password are two entries. Results are copied on the way in and out. A lookup's entry is found by the normalised name (without angle brackets, the domain in lower case) and the protocol: Nauthilus picks its search per protocol, and the jmap search returns more attributes.

Identical requests that arrive together share one backend call: the first starts it on a context of its own, bounded by leader_budget and carrying its trace span, and every caller, the first included, stops waiting when its own context ends; the call goes on and its answer is stored for the next. An Auth-Wait Nauthilus asks for over HTTP is waited out once, by that call, and every caller waits with it. An answer that a flush overtook while it was on its way is not stored, and a caller that comes after a flush starts a call of its own.

Lookups of the admin API (diagnosis, imports, deliveries) go past a cached "unknown" and store a found account, so an account created a moment ago is seen at once.

Entries are flushed with shardpostctl auth flush [<account>] on every server (see Operations: Auth cache, with what each change in LDAP costs until it takes effect) and by a restart. The metrics are imapceph_auth_cache_* and imapceph_auth_backend_seconds (Observability).

Rendered from docs/configuration.md in the ShardPost repository.