89. pepsi-quota

Manage and reconcile per-account mailbox quotas.

89.1. Role

pepsi-quota is the operator interface to the pepsi.mailbox_quota table: the per-account mailbox limits that pepsi-stage-relay-to-maildir enforces, and the usage accounting that both it and pepsi-ingress work from. It is not a stage.

Every row is keyed on the passwd login, not on an e-mail address and not on a uid. At RCPT time, pepsi-ingress can compare an envelope recipient against a login without resolving aliases. Ingress must not resolve aliases, and cannot, since the alias map and the passwd database belong to the delivery stage. A login also stays one row when several addresses reach one mailbox.

Reference: pepsi-quota(1).

89.2. Subcommands

  • set LOGIN SIZE [--messages N] — give one account its own limit (2G, 500M, a byte count, or none for explicitly unlimited, which is how a single account is exempted from a site-wide quota).

  • unset LOGIN — drop the account’s own limit, so it inherits the site default again. (Not the same as set … none.)

  • show LOGIN / list [--full] — one account’s limits and usage, or every accounted-for account, oldest measurement first (--full restricts the listing to those whose estimate has reached their limit).

  • measure LOGIN — re-measure one mailbox now.

  • reconcile [--all] — re-measure the accounts whose estimate is at or over their limit; --all also re-measures those whose measurement is older than MAILBOX_QUOTA_MAX_AGE.

  • remove LOGIN — forget the account’s limits and its accounting; the next delivery re-creates the row.

89.3. Three layers

Policy

[pepsi] MAILBOX_QUOTA is the site default (absent means unlimited), overridden per account by pepsi-quota set, and tightened further by the kernel’s own limit where the filesystem enforces one.

Measurement

Only pepsi-helper-maildir-writer(1) can take one: it is the single process that becomes the user, and a Maildir is mode 0700. measure and reconcile run it; nothing else here touches a mailbox.

Estimate

The used_* + since_* counters. Pepsi’s own deliveries add to them and nothing ever subtracts, because nothing tells Pepsi when a user deletes mail over IMAP.

The estimate is therefore an upper bound on real usage. This makes it safe as a trigger (“could this account be near its limit? then measure”) and unsafe as a verdict. Hence the rule: nothing refuses a message on an estimate, only on a measurement.

89.4. Why reconcile exists

An account at its limit is refused at RCPT by pepsi-ingress. Suppose its owner then empties the mailbox over IMAP. Nothing tells Pepsi, and because every message is being refused, no delivery ever runs to take a fresh measurement. The mailbox would stay shut for ever.

Three rules prevent that. pepsi-ingress refuses only on a measurement younger than [pepsi] MAILBOX_QUOTA_MAX_AGE (15 minutes by default), so a stale figure lets the message through. pepsi-stage-relay-to-maildir re-measures before it refuses (the helper is asked to measure whenever the measurement is stale or the estimate says the message might not fit), so the delivery path looks again. And pepsi-quota reconcile re-measures the accounts that are at their limit; the sweep is cheap precisely because it covers only those. The package runs it from pepsi-quota-reconcile.timer (five minutes after boot, then every ten minutes, Wants=ed by pepsi.target); do not add a cron job beside it. On a source install without systemd the equivalent is:

*/10 * * * *  pepsi  pepsi-quota -c /etc/pepsi/pepsi.conf reconcile

89.5. Privileges

Installed set-group-id to pepsi-maildir (mode 2550, owner pepsi:pepsi-maildir, not executable by others, so no other local user reaches the setgid bit), for the same reason as pepsi-stage-relay-to-maildir: measure/reconcile run the 4750 root:pepsi-maildir helper, and the pepsi service account is deliberately not a member of that group. Run as root it drops to pepsi before connecting to the database, keeping that one group across the drop. The tool therefore behaves the same by hand as it does from its timer, where the setgid bit supplies the group and no drop happens. Any other caller is refused before the configuration is read, and the environment that steers configuration loading is stripped (PATH is pinned to a fixed system path), since the setgid bit is the gate on a setuid-root helper. [pepsi] MAILBOX_HELPER, which names that helper, cannot be set from the database overlay.

89.6. See also

pepsi-stage-relay-to-maildir, pepsi-ingress, pepsi-status, pepsi-quota(1), pepsi-helper-maildir-writer(1), pepsi.conf(5). Security: the setgid model (The privilege split), the local-user adversary it is built against (A local shell user), and the quota rules in the availability table (Availability).