Default config love

[sstrigler]

Collection of small changes to the default config

[weiss]

If registration_timeout: 3600 seems like a sane default, maybe we'd want to set that default in the code rather than adding another option to the example config file?

[weiss]

Cosmetical cosmetics, I'd guess dashed list syntax works slightly better for most admins:

auth_stored_password_types:
  - scram_sha1
  - scram_sha256
  - scram_sha512

[badlop]

Default values

In my opinion, it makes sense to set sane default values in the code, so ejabberd.yml.example can be simple, and only used to set specific options.

Newly enabled options

Regarding auth_stored_password_types and mod_invites:

The next ejabberd release is planned to be 26.03, and will include mostly bug fixes and security fixes. In principle, it would be preferable to only modify the example configuration file if it's fixing some problem; and delay improvements for the next major release.

In this particular case, if adding those specific options does not require any warning in the release notes, and it doesn't break upgrade, nor affect if an administrator forgets to read the upgrade notes, then they could be included in this fix-release.

Commented options

This commit from 2018 explains the current attempt (I think this is not mentioned anywhere else): 77163c4

If there is a need to explain something in the configuration file, then it probably means the documentation could be improved to cover that topic. Either the option explanation, or the option example, or the feature paragraph, or a new tutorial or page covering that user-case.

Right now only those options have comments:

• certfiles -- this is a very common topic
• ejabberd_stun turn_ipX_address
• mod_mam db_type -- this is fundamental for almost any deployment
• mod_pubsub force_node_config -- very specific config
• mod_register ip_access

[weiss]

As I mentioned in the ejabberd channel, personally I believe it's better to avoid adding documentation (beyond short hints) to the example config file. We had an endless example configuration in the past and decided to strip that down in 2018 due to our experiences. I get that some admins might have a workflow of reading through all available settings and like having their documentation inline. But I think the downsides clearly outweigh the benefits:

• Long, bloaty configuration files can easily scare aware newcomers.
• This is just our example configuration, distros often use their own, so we can't make assumptions about users actually seeing our in-place documentation.
• The official reference documentation should be the single place with the most-helpful documentation. Adding documentation to the configuration means we either duplicate the official documentation, or we scatter different documentation parts around different places.
• Keeping the documentation/defaults in sync is way harder that way.

Edit: Oh sorry, hadn't seen @badlop's comment.

[sstrigler]

While I agree with the general sentiment here, I've added things like trusted_proxies or registration_timeout since someone would have to read through the entire documentation from tip to toe to know about those features. That's just not what people do.

But then, maybe trusted_proxies could be set to include localhost by default rather than being [], I don't see how this could hurt anyone (whereas empty list gives people headaches). Similar with registration_timeout maybe? (Holger mentioned that in the channel already).

The comment I left on auth_stored_password_types could easily be moved to the documentation if we also change the default value. Neither adding this option nor enabling mod_invites hurts any updates nor does it need upgrade/release notes, since this is about the default config, that is typically only used for new installations.

How about we do it like this? We modify ejabberd.yml.example more or less like I suggested here (with some more changes as wished) and I create issues to ask for change of default values and maybe add documentation. This issues could then be addressed with the next release and the new options in the config can be removed again?

[sstrigler]

If registration_timeout: 3600 seems like a sane default, maybe we'd want to set that default in the code rather than adding another option to the example config file?

Should I uncomment it for now (see my other comment)?

[weiss]

The comment I left on auth_stored_password_types could easily be moved to the documentation if we also change the default value.

Aren't those unrelated questions?

1. Should we change the default in the code?
2. Should we document the option in the example config?

I see pros and cons for 1, but would personally opt against 2 either way. As important as we might view the implications of storing different hash algos in the DB, this is not a topic I'd actively try to bother newcomers with by throwing text at them. If you have zero idea what the hell this is about, chances are the explanation will leave you just as unsure whether and what to do about this option as without that text.

[sstrigler]

True, with this comment I didn't have newcomers in mind but rather backlash from some security concerned people who keep a close look at what we're doing. We can answer those questions in person if required, doesn't need to clutter the config for everyone.

[sstrigler]

TODO: apply changes as applicable to .github/container/ejabberd.yml.example