3rdparty/modules/rabbitmq/README.md

   1 #rabbitmq
   2
   3 ####Table of Contents
   4
   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)
  16
  17 ##Overview
  18
  19 This module manages RabbitMQ (www.rabbitmq.com)
  20
  21 ##Module Description
  22 The rabbitmq module sets up rabbitmq and has a number of providers to manage
  23 everything from vhosts to exchanges after setup.
  24
  25 This module has been tested against 2.7.1 and is known to not support
  26 all features against earlier versions.
  27
  28 ##Setup
  29
  30 ###What rabbitmq affects
  31
  32 * rabbitmq repository files.
  33 * rabbitmq package.
  34 * rabbitmq configuration file.
  35 * rabbitmq service.
  36
  37 ###Beginning with rabbitmq
  38
  39
  40 ```puppet
  41 include '::rabbitmq'
  42 ```
  43
  44 ##Usage
  45
  46 All options and configuration can be done through interacting with the parameters
  47 on the main rabbitmq class.  These are documented below.
  48
  49 ##rabbitmq class
  50
  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:
  54
  55 ```puppet
  56 class { '::rabbitmq':
  57   service_manage    => false,
  58   port              => '5672',
  59   delete_guest_user => true,
  60 }
  61 ```
  62
  63 Or such as offline installation from intranet or local mirrors:
  64
  65 ```puppet
  66 class { '::rabbitmq':
  67    key_content      => template('openstack/rabbit.pub.key'),
  68    package_gpg_key  => '/tmp/rabbit.pub.key',
  69 }
  70 ```
  71
  72 And this one will use external package key source for any (apt/rpm) package provider:
  73
  74 ```puppet
  75 class { '::rabbitmq':
  76    package_gpg_key  => 'http://www.some_site.some_domain/some_key.pub.key',
  77 }
  78 ```
  79
  80 ### Environment Variables
  81 To use RabbitMQ Environment Variables, use the parameters `environment_variables` e.g.:
  82
  83 ```puppet
  84 class { 'rabbitmq':
  85   port              => '5672',
  86   environment_variables   => {
  87     'NODENAME'     => 'node01',
  88     'SERVICENAME'  => 'RabbitMQ'
  89   }
  90 }
  91 ```
  92
  93 ### Variables Configurable in rabbitmq.config
  94 To change RabbitMQ Config Variables in rabbitmq.config, use the parameters `config_variables` e.g.:
  95
  96 ```puppet
  97 class { 'rabbitmq':
  98   port              => '5672',
  99   config_variables   => {
 100     'hipe_compile'  => true,
 101     'frame_max'     => 131072,
 102     'log_levels'    => "[{connection, info}]"
 103   }
 104 }
 105 ```
 106
 107 To change Erlang Kernel Config Variables in rabbitmq.config, use the parameters
 108 `config_kernel_variables` e.g.:
 109
 110 ```puppet
 111 class { 'rabbitmq':
 112   port              => '5672',
 113   config_kernel_variables  => {
 114     'inet_dist_listen_min' => 9100,
 115     'inet_dist_listen_max' => 9105,
 116   }
 117 }
 118 ```
 119
 120 ### Clustering
 121 To use RabbitMQ clustering facilities, use the rabbitmq parameters
 122 `config_cluster`, `cluster_nodes`, and `cluster_node_type`, e.g.:
 123
 124 ```puppet
 125 class { 'rabbitmq':
 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,
 131 }
 132 ```
 133
 134 ##Reference
 135
 136 ##Classes
 137
 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.
 145
 146 ###Parameters
 147
 148 ####`admin_enable`
 149
 150 Boolean, if enabled sets up the management interface/plugin for RabbitMQ.
 151
 152 ####`cluster_node_type`
 153
 154 Choose between disk and ram nodes.
 155
 156 ####`cluster_nodes`
 157
 158 An array of nodes for clustering.
 159
 160 ####`cluster_partition_handling`
 161
 162 Value to set for `cluster_partition_handling` RabbitMQ configuration variable.
 163
 164 ####`config`
 165
 166 The file to use as the rabbitmq.config template.
 167
 168 ####`config_cluster`
 169
 170 Boolean to enable or disable clustering support.
 171
 172 ####`config_kernel_variables`
 173
 174 Hash of Erlang kernel configuration variables to set (see [Variables Configurable in rabbitmq.config](#variables-configurable-in-rabbitmq.config)).
 175
 176 ####`config_mirrored_queues`
 177
 178 DEPRECATED
 179
 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)
 183
 184 ####`config_path`
 185
 186 The path to write the RabbitMQ configuration file to.
 187
 188 ####`config_stomp`
 189
 190 Boolean to enable or disable stomp.
 191
 192 ####`config_variables`
 193
 194 To set config variables in rabbitmq.config
 195
 196 ####`default_user`
 197
 198 Username to set for the `default_user` in rabbitmq.config.
 199
 200 ####`default_pass`
 201
 202 Password to set for the `default_user` in rabbitmq.config.
 203
 204 ####`delete_guest_user`
 205
 206 Boolean to decide if we should delete the default guest user.
 207
 208 ####`env_config`
 209
 210 The template file to use for rabbitmq_env.config.
 211
 212 ####`env_config_path`
 213
 214 The path to write the rabbitmq_env.config file to.
 215
 216 ####`environment_variables`
 217
 218 RabbitMQ Environment Variables in rabbitmq_env.config
 219
 220 ####`erlang_cookie`
 221
 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.
 224
 225 ####`file_limit`
 226
 227 Set rabbitmq file ulimit. Defaults to 16384. Only available on systems with
 228 `$::osfamily == 'Debian'` or `$::osfamily == 'RedHat'`.
 229
 230 ####`key_content`
 231
 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.
 234
 235 ####`ldap_auth`
 236
 237 Boolean, set to true to enable LDAP auth.
 238
 239 ####`ldap_server`
 240
 241 LDAP server to use for auth.
 242
 243 ####`ldap_user_dn_pattern`
 244
 245 User DN pattern for LDAP auth.
 246
 247 ####`ldap_other_bind`
 248
 249 How to bind to the LDAP server. Defaults to 'anon'.
 250
 251 ####`ldap_config_variables`
 252
 253 Hash of other LDAP config variables.
 254
 255 ####`ldap_use_ssl`
 256
 257 Boolean, set to true to use SSL for the LDAP server.
 258
 259 ####`ldap_port`
 260
 261 Numeric port for LDAP server.
 262
 263 ####`ldap_log`
 264
 265 Boolean, set to true to log LDAP auth.
 266
 267 ####`manage_repos`
 268
 269 Boolean, whether or not to manage package repositories.
 270
 271 ####`management_port`
 272
 273 The port for the RabbitMQ management interface.
 274
 275 ####`node_ip_address`
 276
 277 The value of NODE_IP_ADDRESS in rabbitmq_env.config
 278
 279 ####`package_ensure`
 280
 281 Determines the ensure state of the package.  Set to installed by default, but could
 282 be changed to latest.
 283
 284 ####`package_gpg_key`
 285
 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.
 290
 291 ####`package_name`
 292
 293 The name of the package to install.
 294
 295 ####`package_provider`
 296
 297 What provider to use to install the package.
 298
 299 ####`package_source`
 300
 301 Where should the package be installed from?
 302
 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.
 308
 309 ####`plugin_dir`
 310
 311 Location of RabbitMQ plugins.
 312
 313 ####`port`
 314
 315 The RabbitMQ port.
 316
 317 ####`service_ensure`
 318
 319 The state of the service.
 320
 321 ####`service_manage`
 322
 323 Determines if the service is managed.
 324
 325 ####`service_name`
 326
 327 The name of the service to manage.
 328
 329 ####`ssl`
 330
 331 Configures the service for using SSL.
 332
 333 ####`ssl_only`
 334
 335 Configures the service to only use SSL.  No cleartext TCP listeners will be created.
 336 Requires that ssl => true and port => UNSET also
 337
 338 ####`ssl_cacert`
 339
 340 CA cert path to use for SSL.
 341
 342 ####`ssl_cert`
 343
 344 Cert to use for SSL.
 345
 346 ####`ssl_key`
 347
 348 Key to use for SSL.
 349
 350 ####`ssl_management_port`
 351
 352 SSL management port.
 353
 354 ####`ssl_stomp_port`
 355
 356 SSL stomp port.
 357
 358 ####`ssl_verify`
 359
 360 rabbitmq.config SSL verify setting.
 361
 362 ####`ssl_fail_if_no_peer_cert`
 363
 364 rabbitmq.config `fail_if_no_peer_cert` setting.
 365
 366 ####`ssl_versions`
 367
 368 Choose which SSL versions to enable. Example: `['tlsv1.2', 'tlsv1.1']`.
 369
 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.
 371
 372 ####`ssl_ciphers`
 373
 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']`.
 375
 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
 379
 380 ####`stomp_port`
 381
 382 The port to use for Stomp.
 383
 384 ####`stomp_ensure`
 385
 386 Boolean to install the stomp plugin.
 387
 388 ####`tcp_keepalive`
 389
 390 Boolean to enable TCP connection keepalive for RabbitMQ service.
 391
 392 ####`version`
 393
 394 Sets the version to install.
 395
 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.
 400
 401 ####`wipe_db_on_cookie_change`
 402
 403 Boolean to determine if we should DESTROY AND DELETE the RabbitMQ database.
 404
 405 ####`rabbitmq_user`
 406
 407 String: OS dependent, default defined in param.pp. The system user the rabbitmq daemon runs as.
 408
 409 ####`rabbitmq_group`
 410
 411 String: OS dependent, default defined in param.pp. The system group the rabbitmq daemon runs as.
 412
 413 ####`rabbitmq_home`
 414
 415 String: OS dependent. default defined in param.pp. The home directory of the rabbitmq deamon.
 416
 417 ##Native Types
 418
 419 ### rabbitmq\_user
 420
 421 query all current users: `$ puppet resource rabbitmq_user`
 422
 423 ```
 424 rabbitmq_user { 'dan':
 425   admin    => true,
 426   password => 'bar',
 427 }
 428 ```
 429 Optional parameter tags will set further rabbitmq tags like monitoring, policymaker, etc.
 430 To set the administrator tag use admin-flag.
 431 ```puppet
 432 rabbitmq_user { 'dan':
 433   admin    => true,
 434   password => 'bar',
 435   tags     => ['monitoring', 'tag1'],
 436 }
 437 ```
 438
 439
 440 ### rabbitmq\_vhost
 441
 442 query all current vhosts: `$ puppet resource rabbitmq_vhost`
 443
 444 ```puppet
 445 rabbitmq_vhost { 'myvhost':
 446   ensure => present,
 447 }
 448 ```
 449
 450 ### rabbitmq\_exchange
 451
 452 ```puppet
 453 rabbitmq_exchange { 'myexchange@myvhost':
 454   user     => 'dan',
 455   password => 'bar',
 456   type     => 'topic',
 457   ensure   => present,
 458   internal => false,
 459   auto_delete => false,
 460   durable => true,
 461   arguments => {
 462     hash-header => 'message-distribution-hash'
 463   }
 464 }
 465 ```
 466
 467 ### rabbitmq\_queue
 468
 469 ```puppet
 470 rabbitmq_queue { 'myqueue@myvhost':
 471   user        => 'dan',
 472   password    => 'bar',
 473   durable     => true,
 474   auto_delete => false,
 475   arguments   => {
 476     x-message-ttl => 123,
 477     x-dead-letter-exchange => 'other'
 478   },
 479   ensure      => present,
 480 }
 481 ```
 482
 483 ### rabbitmq\_binding
 484
 485 ```puppet
 486 rabbitmq_binding { 'myexchange@myqueue@myvhost':
 487   user             => 'dan',
 488   password         => 'bar',
 489   destination_type => 'queue',
 490   routing_key      => '#',
 491   arguments        => {},
 492   ensure           => present,
 493 }
 494 ```
 495
 496 ### rabbitmq\_user\_permissions
 497
 498 ```puppet
 499 rabbitmq_user_permissions { 'dan@myvhost':
 500   configure_permission => '.*',
 501   read_permission      => '.*',
 502   write_permission     => '.*',
 503 }
 504 ```
 505
 506 ### rabbitmq\_policy
 507
 508 ```puppet
 509 rabbitmq_policy { 'ha-all@myvhost':
 510   pattern    => '.*',
 511   priority   => 0,
 512   applyto    => 'all',
 513   definition => {
 514     'ha-mode'      => 'all',
 515     'ha-sync-mode' => 'automatic',
 516   },
 517 }
 518 ```
 519
 520 ### rabbitmq\_plugin
 521
 522 query all currently enabled plugins `$ puppet resource rabbitmq_plugin`
 523
 524 ```puppet
 525 rabbitmq_plugin {'rabbitmq_stomp':
 526   ensure => present,
 527 }
 528 ```
 529
 530 ### rabbitmq\_erlang\_cookie
 531
 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
 538 this type directly.
 539
 540 ##Limitations
 541
 542 This module has been built on and tested against Puppet 3.x.
 543
 544 The module has been tested on:
 545
 546 * RedHat Enterprise Linux 5/6
 547 * Debian 6/7
 548 * CentOS 5/6
 549 * Ubuntu 12.04/14.04
 550
 551 Testing on other platforms has been light and cannot be guaranteed.
 552
 553 ### Module dependencies
 554
 555 If running CentOS/RHEL, and using the yum provider, ensure the epel repo is present.
 556
 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:
 559
 560     puppet module install garethr-erlang
 561
 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:
 564
 565 For RedHat systems:
 566
 567     include 'erlang'
 568     class { 'erlang': epel_enable => true}
 569
 570 For Debian systems:
 571
 572     include 'erlang'
 573     package { 'erlang-base':
 574       ensure => 'latest',
 575     }
 576
 577 This module also depends on the excellent nanliu/staging module on the Forge:
 578
 579     puppet module install nanliu-staging
 580
 581 ### Downgrade Issues
 582
 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.
 588
 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".
 591
 592 ##Development
 593
 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.
 598
 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.
 602
 603 You can read the complete module contribution guide [on the Puppet Labs wiki.](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing)
 604
 605 ### Authors
 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