95.1.58. pepsi-quota

Manage and reconcile per-account mailbox quotas

Manual section:

1

95.1.58.1.1. Name

pepsi-quota - set per-account mailbox quotas and re-measure mailboxes.

95.1.58.1.2. Synopsis

pepsi-quota [GLOBAL-OPTIONS] set LOGIN SIZE [–messages N]
pepsi-quota [GLOBAL-OPTIONS] unset LOGIN
pepsi-quota [GLOBAL-OPTIONS] show LOGIN
pepsi-quota [GLOBAL-OPTIONS] list [–full]
pepsi-quota [GLOBAL-OPTIONS] measure LOGIN
pepsi-quota [GLOBAL-OPTIONS] reconcile [–all]
pepsi-quota [GLOBAL-OPTIONS] remove LOGIN

GLOBAL-OPTIONS are -c FILE, -L LOGLEVEL and -v, and precede the sub-command (see Global Options).

95.1.58.1.3. Description

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

Quota is a property of a local account, so every row is keyed on the passwd login, not on an e-mail address and not on a uid. At RCPT time, pepsi-ingress(1) can compare an envelope recipient against a login without resolving aliases (which it must not do, and cannot). A login also stays one row when several addresses reach one mailbox.

95.1.58.1.3.1. Policy, measurement, estimate

Policy is [pepsi] MAILBOX_QUOTA (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 can only be taken by pepsi-helper-maildir-writer(1), which is the single process that becomes the user and can read a 0700 Maildir. measure and reconcile run it; nothing else here touches a mailbox.

Estimate is 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. That is exactly what 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.

95.1.58.1.3.2. Why reconcile exists

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

Two things prevent that. pepsi-ingress(1) refuses only on a measurement younger than [pepsi] MAILBOX_QUOTA_MAX_AGE (15 minutes by default), so a stale figure lets the message through and the delivery path looks again. And pepsi-quota reconcile, run from cron, re-measures the accounts that are at their limit. The sweep is cheap precisely because it covers only those accounts.

A site that enforces quotas must run it periodically. On a package install this is already done: pepsi-quota-reconcile.timer runs the sweep five minutes after boot and every ten minutes thereafter (Persistent=true, so a missed run is made up), and pepsi.target Wants= it, so the one switch that starts the pipeline starts this too. Do not add a cron job beside it; that would make two sweeps at the same interval, each of which spawns the setuid helper.

On a source install without systemd, the equivalent is:

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

95.1.58.1.4. Sub-commands

set LOGIN SIZE [–messages N]

Give one account its own limit, overriding the site default. SIZE accepts a plain byte count or a K/M/G/T suffix in powers of 1024 (2G, 500M, 1048576), or the literal none.

none is not the same as unset: it means explicitly unlimited, and is how a single account is exempted from a site-wide quota, whereas unset restores inheritance of it.

Without --messages, the message-count limit still inherits [pepsi] MAILBOX_QUOTA_COUNT; setting a byte quota does not silently lift it. --messages 0 lifts it explicitly. Note that this is a property of the stored row, not of the command: set writes the whole row, so omitting --messages on an account that already carried an explicit message limit discards that limit and returns it to inheritance. Repeat --messages when raising a byte quota on such an account; the printed row shows the result either way.

For a login with no passwd entry, the command warns but accepts the login, since the account may be created afterwards.

unset LOGIN

Drop the account’s own limits, so it inherits the site default again. The usage accounting is kept.

show LOGIN

Show one account’s limits and usage. An account with no row is not an error: it prints the inherited default and “never measured”.

list [–full]

List every account that Pepsi has accounted for, oldest measurement first. With --full, list only those whose estimate has reached their limit: the accounts that reconcile would re-measure, which are not necessarily over quota. An empty listing then prints (no accounts at or over their limit) rather than (no accounts), which is the one case worth telling apart.

measure LOGIN

Re-measure this mailbox now and store the result.

reconcile [–all]

Re-measure the accounts whose estimate is at or over their limit. With --all, also those whose measurement is older than [pepsi] MAILBOX_QUOTA_MAX_AGE. One unmeasurable mailbox (an account deleted since its last delivery, say) is logged and the sweep continues; the exit status is non-zero if any failed.

remove LOGIN

Forget the account entirely: its limits and its accounting. The next delivery re-creates the row and measures afresh, so this is also the “these numbers are wrong, start over” button.

95.1.58.1.5. Global Options

These global options precede the subcommand (a trailing flag is rejected).

-c FILE, –config FILE

Read the configuration from FILE instead of searching the default locations. Unlike pepsi-whitelist(1), this is not refused under the setgid bit: the caller check described under Privileges runs first, so only root and the pepsi service account get as far as reading it.

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity. LOGLEVEL is one of error, warn, info, debug or trace (default: [pepsi] LOG, else info).

-v, –verbose

Show log messages from all sources, including third-party libraries.

-h, –help

Print a usage summary and exit.

-V, –version

Print the version and exit.

95.1.58.1.6. Output

list, show, set and measure print one line per account:

alice             1200M/2G (58%)  4213 messages  measured 91s ago (maildirsize)
bob                 14M/unlimited 112 messages   measured never (-) [site default]

The usage shown is the measurement plus everything delivered since, which is the figure the delivery path acts on. measured is an age rather than a timestamp because the question that it answers is whether the figure is still worth believing: a refusal at RCPT rests on a measurement being fresh.

95.1.58.1.7. Privileges

pepsi-quota is installed set-group-id to the pepsi-maildir group, for the same reason as pepsi-stage-relay-to-maildir(1): measure and reconcile run the 4750 root:pepsi-maildir measuring helper, and the pepsi service account is deliberately not a member of that group. The setgid bit on the few programs that are allowed through is the gate. That is what lets an unattended reconcile from cron measure mailboxes without being root. The mode is 2550 with owner pepsi:pepsi-maildir: the owner may execute the program, but the world may not, because the setgid bit is the gate on the setuid-root helper. The exec right cannot come from the group bits either, because pepsi is deliberately not a member of the group.

When run as root, it drops to the pepsi service account, which is the role that owns these rows, before connecting to the database, and it keeps the pepsi-maildir group across the drop. When it runs from its timer as pepsi, the setgid bit supplies that group and no drop happens at all. Keeping the group across the drop makes measure work for an operator who types it as root, just as it does from cron. Root’s run thereby gains nothing that the timer’s run does not already have.

make install sets the bit up (its install-quota-tool step) provided it is run as root and the group exists; otherwise it prints the exact commands.

Because the setgid bit is that gate, the program enforces the same rule itself: unless the real user is root or the pepsi service account, it exits with an error before any configuration is read. Like the setuid crypto stages, it also strips the environment variables that steer configuration loading (HOME, XDG_CONFIG_HOME, PG*, TALER_*, PEPSI_*) and pins PATH to a safe default.

No unprivileged caller loses anything by that refusal: every subcommand reads or writes pepsi.mailbox_quota, and PostgreSQL peer authentication keys off the effective uid, so a caller who is not pepsi (or root, which becomes pepsi) could never have connected.

95.1.58.1.8. Exit Status

0

Successful completion.

1

An error occurred: the caller is neither root nor the pepsi service account (under the setgid bit), a malformed configuration or SIZE, a failed database connection or query, or a measurement that failed (for reconcile, after the remaining accounts were measured). The reason is written to the log.

2

The command line itself was wrong (an unknown subcommand or option, or a global option given after the subcommand).

78

The database schema belongs to another Pepsi release (not installed, older, newer or modified); run pepsi-setup schema (see pepsi-setup(1)).

95.1.58.1.9. Configuration

The policy options that this tool reads all live in the [pepsi] section and are documented in pepsi.conf(5): MAILBOX_QUOTA, MAILBOX_QUOTA_COUNT, MAILBOX_OVER_QUOTA, MAILBOX_QUOTA_MAX_AGE, MAILBOX_QUOTA_RCPT_CHECK and MAILBOX_FS_QUOTA. They are read from the effective configuration (the file plus the database overlay), the same view that the delivery stage has. One more option, also in [pepsi], belongs to this tool in particular:

MAILBOX_HELPER

(path, optional) The privileged helper that this tool runs to take a measurement. Default pepsi-helper-maildir-writer, located on the PATH of the pepsi-quota process unless given as an absolute path (under the setgid bit, this is the fixed system PATH that the program pins). The database configuration overlay may not set it: it names a program that runs with the pepsi-maildir group. It is the same binary that the delivery stage uses, in its measure mode: a Maildir is 0700, so it is the one process that can become the user and read one.

Set it only where the helper is not reachable under that name, chiefly in a source install with --prefix whose $PREFIX/bin is not on the timer’s PATH. Keep it in step with the HELPER option in the delivery stage’s own [stage-<name>] section (pepsi-stage-relay-to-maildir(1)): the two name the same program for two different callers, nothing cross-checks them, and delivery and reconciliation agree only when both are right.

95.1.58.1.10. Files

pepsi.mailbox_quota

The table this tool manages: one row per account, carrying its limits, the last measurement and what has been delivered since. pepsi-setup(1) creates it with the rest of the schema; rows appear by themselves on an account’s first local delivery, so nobody has to be pre-registered.

~/Maildir/maildirsize

The Maildir++ size file that the helper maintains, in the format that Dovecot, Courier and Exim also read and write.

95.1.58.1.11. See Also

pepsi-stage-relay-to-maildir(1), pepsi-helper-maildir-writer(1), pepsi-ingress(1), pepsi-status(1), pepsi.conf(5), maildir(5), quotactl(2); the setgid model and the quota availability rules are described in the Pepsi manual’s security and threat-model chapters.

95.1.58.1.12. Bugs

Report bugs to the Pepsi issue tracker.