Configuration versioning
All our YAML configuration files (e.g., smtpd.yaml, smtpd-app.yaml) include a "version" property. This property ensures backward compatibility when upgrading to newer software versions. Later versions of the configuration may introduce new features, syntax changes, and/or updates to default behaviors; these changes are documented in the release notes for each version. If you use a newer software version with an older configuration file version, the specific configuration version will always maintain consistent behavior.
Recommendations
We recommend always upgrading your configuration file version to match the running software version and restoring any previous default behaviors you prefer. This approach allows you to benefit from new features, improved defaults, and clearer syntax. By upgrading the configuration file with each release, you make the process easier and safer compared to skipping multiple versions at once.
For example, in version 6.2 of the smtpd-policy.yaml configuration, we changed the default rate algorithm from fixedwindow to tokenbucket. If the configuration version is 6.1 or earlier, the default is fixedwindow, whereas version 6.2 and later use tokenbucket. To maintain the existing behavior when upgrading to version 6.2, you need to explicitly specify the old rate algorithm.
version: "6.2"
rate:
algorithm: fixedwindow
Keep in mind that if you need to downgrade, you will need to reverse these changes.