Update documentation for IMAP, SMTP, LMTP, POP3, ManageSieve, TLS, OIDC#3040
Open
felixauringer wants to merge 3 commits into
Open
Update documentation for IMAP, SMTP, LMTP, POP3, ManageSieve, TLS, OIDC#3040felixauringer wants to merge 3 commits into
felixauringer wants to merge 3 commits into
Conversation
The extendable server is only referenced in very few places and is not included in the navigation. Furthermore, all of its pages include partials that are already included elsewhere and link to the postgres server in most cases. Additionally, all files that produce errors when building the docs are part of the documentation for the extendable server.
…r in own partials This also updates and completely reworks these parts of the documentation. Major corrections include: OIDC: - `oidc.oidcConfigurationURL`: This value is not used. - `oidc.scope`: This value is not used. - Clarify how tokens are validated depending on which config options are provided. Server: - `helloName` sometimes documented as `handler.helloName`. - Value of `helloName` is only used if `autodetect` is explicitly set to false. - It is `connectiontimeout`, NOT `connectionTimeout`. - Document default values.
…ieve, POP3, and TLS This includes the following major corrections: IMAP: - `auth.requireSSL`: This does not enforce TLS for authentication with OIDC - `disabledCaps`: Make clear that capabilities are enabled but only not advertised - Negative values for `timeout` throw an error. - Option `provisionDefaultMailboxes` was undocumented. POP3: - Properly document `handlerchain`. ManageSieve: No major corrections. SMTP: - Properly document `handlerchain`. - `authRequired` does not enforce authentication. - `auth.announce` influences announcement for PLAIN/LOGIN but disables OIDC. - `auth.requireSSL` only disallows clear text for OIDC. - `disabledFeatures`: Make clear that the features are not disabled. - Update security recommendations and add some warnings. LMTP: - Properly document `handlerchain`. TLS: - Document all options. - Strongly recommend to use implicit TLS everywhere except port 25. - Update commands for PEM and keystore certs. - Add some examples for using ACME clients for proper certificates.
felixauringer
force-pushed
the
refactor-server-docs
branch
from
7345cd4 to
6bbec73
Compare
chibenwa
reviewed
May 15, 2026
| | Local MX | ||
| | insecure: 24, no TLS port defined | ||
|
|
||
| TLS for LMTP is not supported by James. |
Contributor
There was a problem hiding this comment.
:-/ was not aware of this.
It seems weird not to offer the configuration option.
IMO we can plan follow up work in order to enable it.
Contributor
Author
There was a problem hiding this comment.
Should be relatively easy because the LMTP server extends an abstract server that supports it and just does not call getEncryption.
However, we have no use for this feature and I personally do not really know the LMTP codebase and have no idea what implications this change would have. I am not even sure whether STARTTLS is a thing with LMTP.
Contributor
That's some legacy from the original contribution, removing it is the right call |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Originally, I only wanted to update some documentation for ManageSieve after I did not include proper documentation in #2773 and #2808.
I noticed that every protocol had its own documentation for OIDC and PROXY protocol and introduced a new partial for OIDC and the common server configuration options.
As I found some inconsistencies between code and documented options, I also rewrote the documentation for the protocol-specific configuration options.
I know that this is a lot but I hope that you have a look at it at some time. I really think that these changes could make the configuration of James a little easier 🙂
A note regarding the extendable server: I noticed that building the docs throws some errors on master. All of them originate from the extendable server that includes partials incorrectly. As it is not included in the navigation and all included pages are also included in the distributed server, I just removed the docs for the extendable server altogether. It's a single commit, so I can drop it quickly if you have future plans to fix that part of the documentation.