=========================
Usage
=========================

RabbitMQ is a complete and highly reliable enterprise messaging
system based on the emerging AMQP standard.

Sample pillars
==============

Standalone Broker
-----------------

RabbitMQ as AMQP broker with admin user and vhosts:

.. code-block:: yaml

    rabbitmq:
      server:
        enabled: true
        memory:
          vm_high_watermark: 0.4
        bind:
          address: 0.0.0.0
          port: 5672
        secret_key: rabbit_master_cookie
        admin:
          name: adminuser
          password: pwd
        plugins:
        - amqp_client
        - rabbitmq_management
        host:
          '/monitor':
            enabled: true
            user: 'monitor'
            password: 'password'

RabbitMQ as a Stomp broker:

.. code-block:: yaml

    rabbitmq:
      server:
        enabled: true
        secret_key: rabbit_master_cookie
        bind:
          address: 0.0.0.0
          port: 5672
        host:
          '/monitor':
            enabled: true
            user: 'monitor'
            password: 'password'
        plugins_runas_user: rabbitmq
        plugins:
        - rabbitmq_stomp

RabbitMQ cluster
----------------

RabbitMQ as base cluster node:

.. code-block:: yaml

    rabbitmq:
      server:
        enabled: true
        bind:
          address: 0.0.0.0
          port: 5672
        secret_key: rabbit_master_cookie
        admin:
          name: adminuser
          password: pwd
      cluster:
        enabled: true
        role: master
        mode: disc
        members:
        - name: openstack1
          host: 10.10.10.212
        - name: openstack2
          host: 10.10.10.213

HA Queues definition:

.. code-block:: yaml

    rabbitmq:
      server:
        enabled: true
        ...
        host:
          '/monitor':
            enabled: true
            user: 'monitor'
            password: 'password'
            policies:
            - name: HA
              pattern: '^(?!amq\.).*'
              definition: '{"ha-mode": "all"}'

Enable TLS support
------------------

To enable support of TLS for rabbitmq-server you need to provide
a path to cacert, server cert and private key:

.. code-block:: yaml

   rabbitmq:
      server:
        enabled: true
        ...
        ssl:
          enabled: True
          key_file: /etc/rabbitmq/ssl/key.pem
          cert_file: /etc/rabbitmq/ssl/cert.pem
          ca_file: /etc/rabbitmq/ssl/ca.pem

To manage content of these files you can either use the following
options:

.. code-block:: yaml

   rabbitmq:
      server:
        enabled: true
        ...
        ssl:
          enabled: True

          key_file: /etc/rabbitmq/ssl/key.pem
          key: |
          -----BEGIN RSA PRIVATE KEY-----
                    ...
          -----END RSA PRIVATE KEY-------

          ca_file: /etc/rabbitmq/ssl/ca.pem
          cacert_chain: |
          -----BEGIN CERTIFICATE-----
                    ...
          -----END CERTIFICATE-------

          cert_file: /etc/rabbitmq/ssl/cert.pem
          cert: |
          -----BEGIN CERTIFICATE-----
                    ...
          -----END CERTIFICATE-------


Or you can use the `salt.minion.cert` salt state which
creates all required files according to defined reclass model.
See
https://github.com/Mirantis/reclass-system-salt-model/tree/master/salt/minion/cert/rabbitmq
for details. In this case you need just to enable ssl and nothing more:

.. code-block:: yaml

   rabbitmq:
      server:
        enabled: true
        ...
        ssl:
          enabled: True

Defaut port for TLS is ``5671``:

.. code-block:: yaml

  rabbitmq:
    server:
      bind:
        ssl:
         port: 5671

Manage environment variables
----------------------------

Create a config file with variable settings that override the defaults
built in to the RabbitMQ startup scripts:

.. code-block:: yaml

   rabbitmq:
      server:
        enabled: true
        ...
        env_variables:
          hostname: localhost
          node_port: 5671
          export:
            home: /var/lib/rabbitmq
            erl_inetrc: /etc/rabbitmq/inetrc


Usage
=====

Check cluster status, example shows running cluster with 3 nodes:
ctl-1, ctl-2, ctl-3

.. code-block:: yaml

    > rabbitmqctl cluster_status

    Cluster status of node 'rabbit@ctl-1' ...
    [{nodes,[{disc,['rabbit@ctl-1','rabbit@ctl-2','rabbit@ctl-3']}]},
     {running_nodes,['rabbit@ctl-3','rabbit@ctl-2','rabbit@ctl-1']},
     {partitions,[]}]
    ...done.

Setup management user:

.. code-block:: yaml

    > rabbitmqctl add_vhost vhost
    > rabbitmqctl add_user user alive
    > rabbitmqctl set_permissions -p vhost user ".*" ".*" ".*"
    > rabbitmqctl set_user_tags user management

EPD process is Erlang Port Mapper Daemon. It's a feature of the
Erlang runtime that helps Erlang nodes to find each other. It's a
pretty tiny thing and doesn't contain much state (other than "what
Erlang nodes are running on this system?") so it's not a huge deal for
it to still be running.

Although it's running as user rabbitmq, it was started automatically
by the Erlang VM when we started. We've considered adding "epmd -kill"
to our shutdown script - but that would break any other Erlang apps
running on the system; it's more "global" than RabbitMQ.

Upgrades
========

The rabbitmq formula provide set of phases (logical bloks) that will help to
build flexible upgrade orchestration logic for particular components. The list
of phases might and theirs descriptions are listed in table below:

+-------------------------------+------------------------------------------------------+
| State                         | Description                                          |
+===============================+======================================================+
| <app>.upgrade.service_running | Ensure that all services for particular application  |
|                               | are enabled for autostart and running                |
+-------------------------------+------------------------------------------------------+
| <app>.upgrade.service_stopped | Ensure that all services for particular application  |
|                               | disabled for autostart and dead                      |
+-------------------------------+------------------------------------------------------+
| <app>.upgrade.pkgs_latest     | Ensure that packages used by particular application  |
|                               | are installed to latest available version.           |
+-------------------------------+------------------------------------------------------+
| <app>.upgrade.render_config   | Ensure configuration is rendered actual version.     +
+-------------------------------+------------------------------------------------------+
| <app>.upgrade.pre             | We assume this state is applied on all nodes in the  |
|                               | cloud before running upgrade.                        |
|                               | Only non destructive actions will be applied during  |
|                               | this phase. Perform service built in service check   |
|                               | like (rabbitmqctl cluster_status)                    |
+-------------------------------+------------------------------------------------------+
| <app>.upgrade.upgrade.pre     | Do nothing for now                                   |
+-------------------------------+------------------------------------------------------+
| <app>.upgrade.upgrade         | This state will basically upgrade application on     |
|                               | particular target. Stop services, render             |
|                               | configuration, install new packages, start services  |
+-------------------------------+------------------------------------------------------+
| <app>.upgrade.upgrade.post    | Do nothing for now                                   |
+-------------------------------+------------------------------------------------------+
| <app>.upgrade.post            | This phase should be launched only when upgrade of   |
|                               | the cloud is completed. Cleanup temporary files,     |
|                               | perform other post upgrade tasks.                    |
+-------------------------------+------------------------------------------------------+
| <app>.upgrade.verify          | Verify current node is present in running_nodes on   |
|                               | the cluster.                                         |
+-------------------------------+------------------------------------------------------+


Read more
=========

* http://www.rabbitmq.com/admin-guide.html
* https://github.com/saltstack/salt-contrib/blob/master/states/rabbitmq_plugins.py
* http://docs.saltstack.com/ref/states/all/salt.states.rabbitmq_user.html
* http://stackoverflow.com/questions/14699873/how-to-reset-user-for-rabbitmq-management
* http://www.rabbitmq.com/memory.html

Clustering
==========

* http://www.rabbitmq.com/clustering.html#auto-config
* https://github.com/jesusaurus/hpcs-salt-state/tree/master/rabbitmq
* http://gigisayfan.blogspot.cz/2012/06/rabbit-mq-clustering-python-fabric.html
* http://docwiki.cisco.com/wiki/OpenStack_Havana_Release:_High-Availability_Manual_Deployment_Guide#RabbitMQ_Installation

Documentation and Bugs
======================

* http://salt-formulas.readthedocs.io/
   Learn how to install and update salt-formulas

* https://github.com/salt-formulas/salt-formula-rabbitmq/issues
   In the unfortunate event that bugs are discovered, report the issue to the
   appropriate issue tracker. Use the Github issue tracker for a specific salt
   formula

* https://launchpad.net/salt-formulas
   For feature requests, bug reports, or blueprints affecting the entire
   ecosystem, use the Launchpad salt-formulas project

* https://launchpad.net/~salt-formulas-users
   Join the salt-formulas-users team and subscribe to mailing list if required

* https://github.com/salt-formulas/salt-formula-rabbitmq
   Develop the salt-formulas projects in the master branch and then submit pull
   requests against a specific formula

* #salt-formulas @ irc.freenode.net
   Use this IRC channel in case of any questions or feedback which is always
   welcome