5 1. [Overview](#overview)
6 2. [Module Description - What the module does and why it is useful](#module-description)
7 3. [Setup - The basics of getting started with rabbitmq](#setup)
8 * [What rabbitmq affects](#what-rabbitmq-affects)
9 * [Setup requirements](#setup-requirements)
10 * [Beginning with rabbitmq](#beginning-with-rabbitmq)
11 4. [Usage - Configuration options and additional functionality](#usage)
12 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
13 5. [Limitations - OS compatibility, etc.](#limitations)
14 * [RedHat module dependencies](#redhat-module-dependecies)
15 6. [Development - Guide for contributing to the module](#development)
19 This module manages RabbitMQ (www.rabbitmq.com)
22 The rabbitmq module sets up rabbitmq and has a number of providers to manage
23 everything from vhosts to exchanges after setup.
25 This module has been tested against 2.7.1 and is known to not support
26 all features against earlier versions.
30 ###What rabbitmq affects
32 * rabbitmq repository files.
34 * rabbitmq configuration file.
37 ###Beginning with rabbitmq
46 All options and configuration can be done through interacting with the parameters
47 on the main rabbitmq class. These are documented below.
51 To begin with the rabbitmq class controls the installation of rabbitmq. In here
52 you can control many parameters relating to the package and service, such as
53 disabling puppet support of the service:
57 service_manage => false,
59 delete_guest_user => true,
63 Or such as offline installation from intranet or local mirrors:
67 key_content => template('openstack/rabbit.pub.key'),
68 package_gpg_key => '/tmp/rabbit.pub.key',
72 And this one will use external package key source for any (apt/rpm) package provider:
76 package_gpg_key => 'http://www.some_site.some_domain/some_key.pub.key',
80 ### Environment Variables
81 To use RabbitMQ Environment Variables, use the parameters `environment_variables` e.g.:
86 environment_variables => {
87 'NODENAME' => 'node01',
88 'SERVICENAME' => 'RabbitMQ'
93 ### Variables Configurable in rabbitmq.config
94 To change RabbitMQ Config Variables in rabbitmq.config, use the parameters `config_variables` e.g.:
100 'hipe_compile' => true,
101 'frame_max' => 131072,
102 'log_levels' => "[{connection, info}]"
107 To change Erlang Kernel Config Variables in rabbitmq.config, use the parameters
108 `config_kernel_variables` e.g.:
113 config_kernel_variables => {
114 'inet_dist_listen_min' => 9100,
115 'inet_dist_listen_max' => 9105,
121 To use RabbitMQ clustering facilities, use the rabbitmq parameters
122 `config_cluster`, `cluster_nodes`, and `cluster_node_type`, e.g.:
126 config_cluster => true,
127 cluster_nodes => ['rabbit1', 'rabbit2'],
128 cluster_node_type => 'ram',
129 erlang_cookie => 'A_SECRET_COOKIE_STRING',
130 wipe_db_on_cookie_change => true,
138 * rabbitmq: Main class for installation and service management.
139 * rabbitmq::config: Main class for rabbitmq configuration/management.
140 * rabbitmq::install: Handles package installation.
141 * rabbitmq::params: Different configuration data for different systems.
142 * rabbitmq::service: Handles the rabbitmq service.
143 * rabbitmq::repo::apt: Handles apt repo for Debian systems.
144 * rabbitmq::repo::rhel: Handles rpm repo for Redhat systems.
150 Boolean, if enabled sets up the management interface/plugin for RabbitMQ.
152 ####`cluster_node_type`
154 Choose between disk and ram nodes.
158 An array of nodes for clustering.
160 ####`cluster_partition_handling`
162 Value to set for `cluster_partition_handling` RabbitMQ configuration variable.
166 The file to use as the rabbitmq.config template.
170 Boolean to enable or disable clustering support.
172 ####`config_kernel_variables`
174 Hash of Erlang kernel configuration variables to set (see [Variables Configurable in rabbitmq.config](#variables-configurable-in-rabbitmq.config)).
176 ####`config_mirrored_queues`
180 Configuring queue mirroring should be done by setting the according policy for
181 the queue. You can read more about it
182 [here](http://www.rabbitmq.com/ha.html#genesis)
186 The path to write the RabbitMQ configuration file to.
190 Boolean to enable or disable stomp.
192 ####`config_variables`
194 To set config variables in rabbitmq.config
198 Username to set for the `default_user` in rabbitmq.config.
202 Password to set for the `default_user` in rabbitmq.config.
204 ####`delete_guest_user`
206 Boolean to decide if we should delete the default guest user.
210 The template file to use for rabbitmq_env.config.
212 ####`env_config_path`
214 The path to write the rabbitmq_env.config file to.
216 ####`environment_variables`
218 RabbitMQ Environment Variables in rabbitmq_env.config
222 The erlang cookie to use for clustering - must be the same between all nodes.
223 This value has no default and must be set explicitly if using clustering.
227 Set rabbitmq file ulimit. Defaults to 16384. Only available on systems with
228 `$::osfamily == 'Debian'` or `$::osfamily == 'RedHat'`.
232 Uses content method for Debian OS family. Should be a template for apt::source
233 class. Overrides `package_gpg_key` behavior, if enabled. Undefined by default.
237 Boolean, set to true to enable LDAP auth.
241 LDAP server to use for auth.
243 ####`ldap_user_dn_pattern`
245 User DN pattern for LDAP auth.
247 ####`ldap_other_bind`
249 How to bind to the LDAP server. Defaults to 'anon'.
251 ####`ldap_config_variables`
253 Hash of other LDAP config variables.
257 Boolean, set to true to use SSL for the LDAP server.
261 Numeric port for LDAP server.
265 Boolean, set to true to log LDAP auth.
269 Boolean, whether or not to manage package repositories.
271 ####`management_port`
273 The port for the RabbitMQ management interface.
275 ####`node_ip_address`
277 The value of NODE_IP_ADDRESS in rabbitmq_env.config
281 Determines the ensure state of the package. Set to installed by default, but could
282 be changed to latest.
284 ####`package_gpg_key`
286 RPM package GPG key to import. Uses source method. Should be a URL for Debian/RedHat
287 OS family, or a file name for RedHat OS family.
288 Set to http://www.rabbitmq.com/rabbitmq-signing-key-public.asc by default.
289 Note, that `key_content`, if specified, would override this parameter for Debian OS family.
293 The name of the package to install.
295 ####`package_provider`
297 What provider to use to install the package.
301 Where should the package be installed from?
303 On Debian- and Arch-based systems using the default package provider,
304 this parameter is ignored and the package is installed from the
305 rabbitmq repository, if enabled with manage_repo => true, or from the
306 system repository otherwise. If you want to use dpkg as the
307 package_provider, you must specify a local package_source.
311 Location of RabbitMQ plugins.
319 The state of the service.
323 Determines if the service is managed.
327 The name of the service to manage.
331 Configures the service for using SSL.
335 Configures the service to only use SSL. No cleartext TCP listeners will be created.
336 Requires that ssl => true and port => UNSET also
340 CA cert path to use for SSL.
350 ####`ssl_management_port`
360 rabbitmq.config SSL verify setting.
362 ####`ssl_fail_if_no_peer_cert`
364 rabbitmq.config `fail_if_no_peer_cert` setting.
368 Choose which SSL versions to enable. Example: `['tlsv1.2', 'tlsv1.1']`.
370 Note that it is recommended to disable `sslv3` and `tlsv1` to prevent against POODLE and BEAST attacks. Please see the [RabbitMQ SSL](https://www.rabbitmq.com/ssl.html) documentation for more information.
374 Support only a given list of SSL ciphers. Example: `['dhe_rsa,aes_256_cbc,sha','dhe_dss,aes_256_cbc,sha','ecdhe_rsa,aes_256_cbc,sha']`.
376 Supported ciphers in your install can be listed with:
377 rabbitmqctl eval 'ssl:cipher_suites().'
378 Functionality can be tested with cipherscan or similar tool: https://github.com/jvehent/cipherscan.git
382 The port to use for Stomp.
386 Boolean to install the stomp plugin.
390 Boolean to enable TCP connection keepalive for RabbitMQ service.
394 Sets the version to install.
396 On Debian- and Arch-based operating systems, the version parameter is
397 ignored and the latest version is installed from the rabbitmq
398 repository, if enabled with manage_repo => true, or from the system
399 repository otherwise.
401 ####`wipe_db_on_cookie_change`
403 Boolean to determine if we should DESTROY AND DELETE the RabbitMQ database.
407 String: OS dependent, default defined in param.pp. The system user the rabbitmq daemon runs as.
411 String: OS dependent, default defined in param.pp. The system group the rabbitmq daemon runs as.
415 String: OS dependent. default defined in param.pp. The home directory of the rabbitmq deamon.
421 query all current users: `$ puppet resource rabbitmq_user`
424 rabbitmq_user { 'dan':
429 Optional parameter tags will set further rabbitmq tags like monitoring, policymaker, etc.
430 To set the administrator tag use admin-flag.
432 rabbitmq_user { 'dan':
435 tags => ['monitoring', 'tag1'],
442 query all current vhosts: `$ puppet resource rabbitmq_vhost`
445 rabbitmq_vhost { 'myvhost':
450 ### rabbitmq\_exchange
453 rabbitmq_exchange { 'myexchange@myvhost':
459 auto_delete => false,
462 hash-header => 'message-distribution-hash'
470 rabbitmq_queue { 'myqueue@myvhost':
474 auto_delete => false,
476 x-message-ttl => 123,
477 x-dead-letter-exchange => 'other'
483 ### rabbitmq\_binding
486 rabbitmq_binding { 'myexchange@myqueue@myvhost':
489 destination_type => 'queue',
496 ### rabbitmq\_user\_permissions
499 rabbitmq_user_permissions { 'dan@myvhost':
500 configure_permission => '.*',
501 read_permission => '.*',
502 write_permission => '.*',
509 rabbitmq_policy { 'ha-all@myvhost':
515 'ha-sync-mode' => 'automatic',
522 query all currently enabled plugins `$ puppet resource rabbitmq_plugin`
525 rabbitmq_plugin {'rabbitmq_stomp':
530 ### rabbitmq\_erlang\_cookie
532 This is essentially a private type used by the rabbitmq::config class
533 to manage the erlang cookie. It replaces the rabbitmq_erlang_cookie fact
534 from earlier versions of this module. It manages the content of the cookie
535 usually located at "${rabbitmq_home}/.erlang.cookie", which includes
536 stopping the rabbitmq service and wiping out the database at
537 "${rabbitmq_home}/mnesia" if the user agrees to it. We don't recommend using
542 This module has been built on and tested against Puppet 3.x.
544 The module has been tested on:
546 * RedHat Enterprise Linux 5/6
551 Testing on other platforms has been light and cannot be guaranteed.
553 ### Module dependencies
555 If running CentOS/RHEL, and using the yum provider, ensure the epel repo is present.
557 To have a suitable erlang version installed on RedHat and Debian systems,
558 you have to install another puppet module from http://forge.puppetlabs.com/garethr/erlang with:
560 puppet module install garethr-erlang
562 This module handles the packages for erlang.
563 To use the module, add the following snippet to your site.pp or an appropriate profile class:
568 class { 'erlang': epel_enable => true}
573 package { 'erlang-base':
577 This module also depends on the excellent nanliu/staging module on the Forge:
579 puppet module install nanliu-staging
583 Be advised that there were configuration file syntax and other changes made between RabbitMQ
584 versions 2 and 3. In order to downgrade from 3 to 2 (not that this is a terribly good idea)
585 you will need to manually remove all RabbitMQ configuration files (``/etc/rabbitmq``) and
586 the mnesia directory (usually ``/var/lib/rabbitmq/mnesia``). The latter action will delete
587 any and all messages stored to disk.
589 Failure to do this will result in RabbitMQ failing to start with a cryptic error message about
590 "init terminating in do_boot", containing "rabbit_upgrade,maybe_upgrade_mnesia".
594 Puppet Labs modules on the Puppet Forge are open projects, and community
595 contributions are essential for keeping them great. We can’t access the
596 huge number of platforms and myriad of hardware, software, and deployment
597 configurations that Puppet is intended to serve.
599 We want to keep it as easy as possible to contribute changes so that our
600 modules work in your environment. There are a few guidelines that we need
601 contributors to follow so that we can have a chance of keeping on top of things.
603 You can read the complete module contribution guide [on the Puppet Labs wiki.](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing)
606 * Jeff McCune <jeff@puppetlabs.com>
607 * Dan Bode <dan@puppetlabs.com>
608 * RPM/RHEL packages by Vincent Janelle <randomfrequency@gmail.com>
609 * Puppetlabs Module Team