Skip to content

Document how to use TLS/SSL with RabbitMQ #848

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Kami merged 3 commits into from
Feb 8, 2019
Merged

Document how to use TLS/SSL with RabbitMQ #848

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c89eec6
Document how to use TLS/SSL with RabbitMQ.
Kami Feb 6, 2019
464de23
Fix syntax.
Kami Feb 6, 2019
9468257
Add a note on client side cert auth not being supported yet.
Kami Feb 7, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions docs/source/install/config/config.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,8 @@ In :github_st2:`/etc/st2/st2.conf <conf/st2.prod.conf>` include the following se
* To understand more about setting up a MongoDB replica set, see
https://docs.mongodb.com/v3.4/tutorial/deploy-replica-set/

|st2| also supports SSL/TLS to encrypt connections. A few extra properties need be added to the
configuration apart from the ones outlined above.
|st2| also supports SSL/TLS to encrypt MongoDB connections. A few extra properties need be added to
the configuration apart from the ones outlined above.

In :github_st2:`/etc/st2/st2.conf <conf/st2.prod.conf>` include the following section:

Expand All @@ -76,7 +76,7 @@ In :github_st2:`/etc/st2/st2.conf <conf/st2.prod.conf>` include the following se
* ``ssl_match_hostname`` - Enable or disable hostname matching. Not recommended to disable and
defaults to True.

.. note::
.. note::

Only certain distributions of MongoDB support SSL/TLS:

Expand All @@ -98,6 +98,25 @@ In :github_st2:`/etc/st2/st2.conf <conf/st2.prod.conf>` include the following se

The ``#RMQ_VHOST`` property is optional and can be left blank.

|st2| also supports SSL/TLS to encrypt RabbitMQ connections. To enable SSL, you need to pass
``?ssl=true`` query parameter at the end of the connection URL.

For example:

.. code-block:: ini

url = amqp://guest:guest@127.0.0.1:5671/?ssl=true
Copy link
Member

@arm4b arm4b Feb 6, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there anything else that's required on ST2 conf side to configure certificates/trusted/chain to communicate with SSL-enabled RabbitMQ server, the right way?

Just for reference, I'm looking at RabbitMQ clients from the examples like:
https://www.rabbitmq.com/ssl.html#java-client-connecting-with-peer-verification
https://pika.readthedocs.io/en/latest/examples/tls_mutual_authentication.html
http://docs.celeryproject.org/projects/kombu/en/latest/reference/kombu.connection.html
which highlight more configuration and parameters like CA, cert chain and so forth.

Copy link
Member Author

@Kami Kami Feb 6, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change only enables secure communication to the server using TLS, but it doesn't do peer verification and it also doesn't support client certificate based authentication.

For that we will need to modify the code (similar to the user contribution for MongoDB not too long ago).

The plan is to use the same configuration option names as we use for MongoDB in the database section in st2.conf (for consistency reasons).

But yeah, that will be a separate change. I will open an issue in StackStorm/st2 to track it.

Copy link
Member

@arm4b arm4b Feb 6, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be good to add a small note about that part in st2docs then.


Keep in mind that RabbitMQ server needs to be configured to enable TLS support.
For more information, refer to the official documentation - `Enabling TLS Support in RabbitMQ
<https://www.rabbitmq.com/ssl.html#enabling-tls>`_.

.. note::

At the moment TLS / SSL is only supported for secure connections to RabbitMQ
server. Peer verification and client side certificate authentication is
currently not supported.

.. _ref-rabbitmq-cluster-config:

|st2| also supports `RabbitMQ cluster <https://www.rabbitmq.com/clustering.html>`_.
Expand All @@ -111,7 +130,6 @@ In :github_st2:`/etc/st2/st2.conf <conf/st2.prod.conf>` include the following se
amqp://#RMQ_USER:#RMQ_PASSWD@#RMQ_NODE_2:#RMQ_PORT/#RMQ_VHOST,
amqp://#RMQ_USER:#RMQ_PASSWD@#RMQ_NODE_3:#RMQ_PORT/#RMQ_VHOST


* To understand more about setting up a RabbitMQ cluster, see
https://www.rabbitmq.com/clustering.html
* RabbitMQ HA guide - https://www.rabbitmq.com/ha.html
Expand Down