Configuration

Mon, 01 Jan 0001 00:00:00 +0000

perch init and perch setup write YAML with 0600 permissions. The default path is $XDG_CONFIG_HOME/perch/perch.yaml (usually ~/.config/perch/perch.yaml), but production deployments should pass --config explicitly.

data_dir: /var/lib/perch
hostname: mail.example.com

imap:
 addr: 127.0.0.1:1143
 imaps_addr: ""
 allow_plaintext_loopback: true

submission:
 addr: 127.0.0.1:1587
 tls_addr: ""

tls:
 cert_file: ""
 key_file: ""
 acme:
 enabled: false
 email: ""
 domains: []
 http_addr: ":80"

storage:
 mode: sqlite # sqlite | s3
 s3:
 endpoint: ""
 region: ""
 bucket: ""
 prefix: "perch/"
 access_key: ""
 secret_key: ""
 secret_key_env: PERCH_S3_SECRET_KEY
 force_path_style: false
 key_template: "perch/{{.mailbox.address}}/{{.task.id}}.eml"
 reconcile_every: 5m
 spool: false
 spool_max_bytes: 268435456

limits:
 max_connections: 512
 ingest_concurrency: 2
 blob_cache_bytes: 67108864
 max_message_bytes: 26214400
 max_recipients: 100

mxraven:
 submission_host: smtp.mxraven.email
 submission_port: 587
 notification_url: wss://notifications.mxraven.com
 feedback_url: https://api.mxraven.com
 listeners:
 - id: ...
 kind: mta
 key_prefix: ...
 key_secret_env: PERCH_MXRAVEN_KEY_SECRET
 consumer: notify-...
 - id: ...
 kind: submission
 key_prefix: ...
 key_secret_env: PERCH_MXRAVEN_SUBMISSION_KEY_SECRET

Secrets can be inline (protected by file permissions) or referenced through environment variables. The mxRaven control-plane token is used only by perch setup and is never written to the config.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Run the doctor

perch doctor --config /etc/perch/perch.yaml

perch doctor checks SQLite integrity and FTS5, TLS certificate files, DNS, S3 connectivity, and mxRaven listeners. Run it as the same user that runs perch serve.

Mail clients cannot connect

Check the listener addresses in perch.yaml.
Plaintext is only allowed on loopback. Use TLS or STARTTLS from other hosts.
For the quickstart defaults, IMAP is 127.0.0.1:1143 and submission is 127.0.0.1:1587.
If you generated a self-signed certificate, the client must trust it or you must explicitly allow the certificate.
Off-loopback connections always require TLS.

`perch mail` cannot connect

For an explicit loopback address, add --plaintext or --smtp-plaintext.
Config-derived loopback listeners select plaintext automatically.
For remote servers, use imaps://host / smtps://host or imap://host / smtp://host for STARTTLS.
Use --ca-file for a private CA and --insecure only for testing.

Authentication fails

perch mail uses the account password, not the mxRaven API key.
perch account passwd changes the local account password.
Check authlimit logs if logins are being throttled.
For submission, the From address must be an account address, alias, or authorized plus-address.

Messages are delivered but not visible locally

In S3 mode, check perch reconcile and the S3 prefix/key template.
The key template must start with storage.s3.prefix.
perch gc --s3-delete removes objects for deleted messages.
Check perch outbound list for submission status and SMTP errors.

S3 errors

Verify the endpoint, region, bucket, access key, and secret.
secret_key_env names the environment variable; systemd reads it from EnvironmentFile.
Run perch reconcile to force a scan.
Check that mxRaven’s S3_STORE rule writes to the same bucket and prefix.

systemd service exits

Run journalctl -u perch -f.
ExecReload sends SIGHUP. Only keep it when tls.cert_file and tls.key_file are configured; otherwise SIGHUP terminates the process.
ProtectHome/ProtectSystem must allow the configured data_dir.
The service user must be able to read the config and write the data dir.

Versions and releases

perch version
gh release view --repo synqronlabs/perch

Manpages are installed with release archives; perch <command> --help always reflects the installed binary.

Documentation on perch docs