In http://docs.mongodb.org/manual/tutorial/upgrade-cluster-to-ssl/ it is not clear that a certificate given to --sslPEMKeyFile must have either:

• both serverAuth and clientAuth extendedKeyUsage flags, or
• neither of them (which defaults to a certificate that is usable for any purpose).

This information is available in

• http://docs.mongodb.org/manual/tutorial/configure-x509-member-authentication/
• http://docs.mongodb.org/manual/tutorial/configure-x509-client-authentication/

but neither of these locations are obvious to a user following the upgrade tutorial, since they both refer to x.509 auth (which a user might not realise is still partially relevant in this particular case) — plus they're not linked from the page in question (either directly or indirectly).

If a serverAuth certificate is generated and given to --sslPEMKeyFile, without a corresponding clientAuth cert given to --sslClusterFile, then the upgrade procedure will not work (it fails when switching from allowSSL to preferSSL).

The required certificate flags should be spelled out in (or before) step 1 of the above URL. Otherwise, users may generate certificates that work for part of the process, but then mysteriously fail to work later on.

The viable approaches that should be listed are:

• Single cert with no extendedKeyUsage flags, passed to --sslPEMKeyFile
• Single cert with serverAuth and clientAuth extendedKeyUsage flags, passed to --sslPEMKeyFile
• One cert with serverAuth passed to --sslPEMKeyFile, and another cert with clientAuth passed to --sslClusterFile.