Synopsis
perch setup [OPTIONS]Description
setup calls the mxRaven control plane to provision a workspace domain, MTA listener, optional submission listener, API keys, inbound route, sending-domain policy, and optional S3_STORE rule. It then writes perch.yaml.
The control-plane token is used only during setup and is never written to the config. Listener and S3 secrets are written inline unless you replace them with *_env references.
Notes
- Publish the DNS records printed by the wizard, or pass –wait to wait for verification.
- Use –no-submission for inbound-only deployments.
- Rate-limit and policy flags map directly to mxRaven listener settings.
Options
| Option | Description |
|---|---|
--config <value> | configuration file (default: ~/.config/perch/perch.yaml) |
--data-dir <value> | data directory |
--hostname <value> | server hostname |
--token <value> | control-plane bearer token |
--base-url <value> | control-plane base URL |
--workspace <value> | mxRaven workspace slug |
--domain <value> | mail domain |
--inbound-domain <value> | inbound domain (defaults to –domain) |
--sending-domain <value> | sending domain (defaults to –domain) |
--no-submission | do not create a submission listener |
--auth-policy <value> | MTA auth policy: none, reject-dmarc-fail, reject-spf-fail, reject-unauthenticated (default: “none”) |
--rspamd | enable Rspamd scanning on the MTA listener |
--reject-malware | reject messages with malware verdicts |
--reject-high-confidence-spam | reject messages with spam score >= 10 |
--mta-message-rate <value> | MTA messages per minute (0 leaves default) (default: 0) |
--mta-recipient-rate <value> | MTA recipients per minute (default: 0) |
--mta-task-rate <value> | MTA tasks per minute (default: 0) |
--mta-burst <value> | MTA rate-limit burst (default: 0) |
--mta-concurrency <value> | MTA max concurrency (default: 0) |
--dry-run | print planned operations without calling mxRaven |
--force | overwrite an existing configuration |
--wait | wait for mxRaven DNS verification after setup |
--wait-timeout <value> | DNS verification timeout (default: 10m0s) |
--wait-interval <value> | DNS verification poll interval (default: 15s) |
--storage <value> | storage mode: sqlite or s3 (default: “sqlite”) |
--s3-endpoint <value> | S3 endpoint URL |
--s3-region <value> | S3 region |
--s3-bucket <value> | S3 bucket |
--s3-prefix <value> | S3 key prefix (default: “perch/”) |
--s3-access-key <value> | S3 access key |
--s3-secret-key <value> | S3 secret key |
--s3-path-style | use path-style S3 addressing |
--s3-key-template <value> | S3 object key template (defaults to prefix + mailbox.address) |
--tls-cert <value> | TLS certificate file |
--tls-key <value> | TLS private key file |
--acme-email <value> | Let’s Encrypt account email |
--acme-domain <value> | comma-separated ACME domains |
--public | bind standard public ports (143/993/587/465) |
--help, -h | show help |
Examples
export MXRAVEN_API_TOKEN=...
perch setup --config /etc/perch/perch.yaml --data-dir /var/lib/perch \
--workspace my-workspace --domain example.com --hostname mail.example.com
perch setup ... --storage s3 --s3-bucket my-mail-archive --s3-region auto \
--s3-endpoint https://<account>.r2.cloudflarestorage.com --s3-access-key <key>
perch setup ... --public --acme-email admin@example.com --acme-domain mail.example.comEnvironment
| Variable | Purpose |
|---|---|
MXRAVEN_API_TOKEN | control-plane bearer token used by setup |