shardpostctl-trace(1)

NAME

shardpostctl-trace - record the IMAP protocol of one account for a while

SYNOPSIS

shardpostctl trace on [-for duration] account
shardpostctl trace status [--json] account
shardpostctl trace off account

DESCRIPTION

Switches on a protocol trace for one account: every IMAP command and response of its sessions is written to the server log as event=protocol_trace. This is the tool for "it works with every client except this one".

The switch is stored with the account, so it applies on every server of the cluster, no matter which one the client happens to reach. It reaches the sessions that open after it: a session that is already running is not traced, and the user has to reconnect. The other direction is immediate — a session that is being traced re-reads the switch every trace.recheck_seconds (60 by default), so switching off, and extending a trace that is running, take effect without a reconnect.

A trace always expires on its own. Without -for it runs for trace.default_duration_seconds, and no trace can outlast trace.max_duration_seconds.

Credentials never reach the log: a LOGIN or AUTHENTICATE command stops the trace for that session, unlogged, until the next login, so neither the password nor pipelined SASL data can appear. PREVIEW responses, which quote message text, are masked.

Role: trace.

OPTIONS

-for duration

How long the trace lasts, for example 30m, 2h. Only for trace on. The server caps it at its maximum.

--json

Print the status as JSON.

EXAMPLES

A user's phone does not show new mail. Trace them for half an hour:

shardpostctl trace on -for 30m user@example.org
shardpostctl trace status user@example.org

Read what the client actually sent, on both servers:

for p in $(kubectl -n shardpost get pod \


        -l app.kubernetes.io/name=shardpost-server -o name); do


    kubectl -n shardpost logs $p -c server --since=10m \


        | grep protocol_trace | grep user@example.org
done

Switch it off as soon as you have what you need:

shardpostctl trace off user@example.org

EXIT STATUS

0

Done.

64

The duration is not valid, or -for was used with off or status.

67

No such account.

77

The caller lacks the role trace.

SEE ALSO

shardpostctl(1), shardpostctl-account(1)

The trace settings are described in docs/configuration.md.