SSL documentation needs improvement

[wdegeus]

First bug: starting gearmand in SSL mode when it hasn't been compiled with ssl support works without throwing issues. (and subsequently it accepts plain text connections just fine)

Next, I finally have gearmand running with a self-signed CA and certificate, can connect to it just fine using openssl s_client.
When I try to connect using gearadmin or the gearman client however it dies with an undebuggable
Error: error:00000001:lib(0):func(0):reason(1)
The certificates are fine but self-signed, but I have no idea what its desires are.
How can I get this to work?
Is there an option to skip Common Name (CN) verification, if it does that at all?
Basically: there is almost no documentation on this at all. This page http://gearman.info/gearmand/ssl.html is almost useless.

[esabol]

It took me a lot of trial and error to get working certificates. I started a thread in the Gearman Google Group in 2016 about that experience. Here's an excerpt from one of my posts in that thread:

According to http://stackoverflow.com/questions/19726138/openssl-error-18-at-0-depth-lookupself-signed-certificate, the Common Name value used for the CA certificate must be different from the Common Name of the client and server certificates generated from the CA certificate. When I generated them, I used the same Common Name for all three certificates. Sure enough, I just regenerated all of my certificates with different Common Name values and turned SSL_VERIFY_PEER back on, and the SSL connection worked and verified! Woo hoo!

I just encountered another gotcha using Gearman SSL... I'm reporting this here in the hope that it might save someone else some time and aggravation.

If you go by the instructions at http://gearman.info/gearmand/ssl.html, the client and server certificates you generate will expire in 30 days, because that is the default and openssl doesn't prompt you to specify a different expiration date. You need to add the argument "-days 3650" to the "openssl x509 -req" commands in order to generate the server and client certificates that don't expire in 30 days. The instructions for generating the gearmand-ca.pem certificate includes the "-days 3650", but that's not enough.

Is there a way to update the web page at http://gearman.info/gearmand/ssl.html? I think that would be worthwhile.

So I strongly agree the documentation should be improved. Unfortunately, nobody ever answered that question for me, so I still don't know how to update
http://gearman.info/gearmand/ssl.html.

And I agree that, if you don't compile with SSL enabled and try to use any SSL command line switch, you should get an error. That caused me a lot of trouble, too, until I realized I had to compile from source.

I'd even like to see SSL be enabled by default so that people who install gearmand packages with yum or apt-get will have it and you don't need to compile from source.

[p-alik]

So I strongly agree the documentation should be improved. Unfortunately, nobody ever answered that question for me, so I still don't know how to update
http://gearman.info/gearmand/ssl.html.

Moving the documentation to github-wiki wouldn't be an option?

[esabol]

So I strongly agree the documentation should be improved. Unfortunately, nobody ever answered that question for me, so I still don't know how to update
http://gearman.info/gearmand/ssl.html.

Moving the documentation to github-wiki wouldn't be an option?

I don't know. Have you looked at #144 ?

[p-alik]

Github Pages is a gut alternative. If PR will be merged, the documentation will be available at https://gearman.github.io/gearmand/docs/dev/html/. But someone who has access to settings of gearman organisation should generate appropriate token and configure GITHUB_TOKEN environment variable in Travis CI.

https://docs.travis-ci.com/user/deployment/pages/
https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-settings

[esabol]

FYI, the source file for that document is here:
https://github.com/gearman/gearmand/blob/master/docs/source/gearmand/ssl.rst

@wdegeus, do have you any suggestions for what needs to be added to that documentation?

[esabol]

The second answer at https://stackoverflow.com/questions/10175812/how-to-create-a-self-signed-certificate-with-openssl is quite thorough.

[SpamapS]

I don't actually know who owns gearman.org or gearman.info .. @BrianAker or @dormando maybe? Anyway, we can pretty easily get those docs to build in to github pages and be available on gearman.org. However, I just started a new job and I'm pretty much on fumes for OSS contribution for the next few months... so somebody else will have to drive. :-P

[p-alik]

@SpamapS, could you generate an auth token add GITHUB_TOKEN in to Travis CI configuration, please.
See this comment above.

[BrianAker]

While I provide support for the 2x branch, limited/personally, I am not sure what is need for v1.

…

Sent from my iPad

On Nov 26, 2018, at 01:43, Алексей Пастухов ***@***.***> wrote: @SpamapS, could you generate an auth token add GITHUB_TOKEN in to Travis CI configuration, please. See this comment above. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[p-alik]

@BrianAker, may I ask you to take a look at #192 (comment), please. Memcache test fails sporadically in Travis CI. I'm just asking your opinion how it should be solved.

[illuusio]

Setting up SSL trust chain can be very harsh. Should we first have test case which creates foo certs and keys and then tests everything works?

[p-alik]

Setting up SSL trust chain can be very harsh. Should we first have test case which creates foo certs and keys and then tests everything works?

There is no way around it, if ssl tests should be setup.

[illuusio]

Or do we have some certs which we use in git?

[p-alik]

Not yet but we could easily add some on demand.

[p-alik]

the issue was mentioned in https://stackoverflow.com/a/59072270/2789312

[esabol]

@p-alik : Are you able to rename issue titles? If so, please change the title of this issue from "SSL not working, lack of documentation" to "SSL documentation needs improvement" or similar. Thanks!