On 05/13/2014 06:00 PM, Alexander Shorin wrote:
> I understand the position "RTFM First", but that's the actual problem
> of all configurations: you're reading the config, you're don't
> understand what the options actually does, you're going to google
> (nobody reads the docs) to find the answer or to ML to ask the same
> question again.

I agree, we should definitely try to give good explanations in the
documentation.  Creating high-quality documentation is one way to get
people to actually read the documentation ;)

> Name should reflect the behaviour clearly. "Fail" is good for Erlang
> since "Let it crash!", […]

You're mixing up different things here.  This is not about the Erlang
"let it crash" philosophy.  Are we talking here about the `ssl`
configuration section, and the corresponding section in the
documentation which is captioned "Secure Socket Level Options"?  Isn't
it clear from the context that this is not about Erlang/OTP principles?

I updated the documentation to make it more clear that this is about the
TLS/SSL handshake.  The purpose of such a handshake is to establish a
TLS/SSL session.  If the server decides that it doesn't want to
establish a session because the client does not send a certificate, it
will send a "handshake failure" alert message and close the connection,
which means that the handshake "failed".  Using the term "fail" in that
context is not something made up by me or by the people who created the
ssl application with that very "fail_if_no_peer_cert" option, it's the
technical terminology that has been introduced in the respective RFCs,
and which is actually used by the people who are talking about that
stuff.

> […] but CouchDB wouldn't actually "fail" because of empty client
> certificate: it will just reject such requests and keep going.

I agree that this makes a difference, at least for us.  However, end
users usually don't care if the server is actually running or not when
their browser can't establish a connection it, as their experience is
exactly the same: the server is "down"; something "failed", apparently.

> I understand the reasons why you picked such name, but I feel that it
> could be better. Or at least comment should clarify what the "fail"
> actually stands for.

I checked again and updated the section in the documentation to make it
more clear what the configuration does.