-
Notifications
You must be signed in to change notification settings - Fork 9
RabbitHub Administrators Guide
This page will discuss how to Install and Administer the RabbitHub plugin for Rabbitmq.
This release is for rabbitmq 3.6.6. For prior versions of Rabbitmq please use the latest 3.6.3 branch. To install from source (requires Erlang R18.3 or higher due to SSL bugs in 17.x.):
git clone https://github.com/brc859844/rabbithub cd rabbithub make deps make make package cp dist/*.ez $RABBITMQ_HOME/plugins
Note that Windows users can build the plugin using the commands under Cygwin. When working with Cygwin ensure that the Erlang bin directory is in your PATH (so that rebar can find erl and erlc) and that the zip utility is installed with your Cygwin installation (required to create the plugin ez file).
Enable the plugin:
rabbitmq-plugins enable rabbithub
By default the plugin will listen for HTTP requests on port 15670.
Note that if no username is specified for HTTP requests submitted to RabbitHub then RabbitHub checks to see whether a default username has been specified for the rabbithub application, and if so uses it. By default RabbitHub is configured to use a default username of guest (see the definition of default_username in rabbithub.app). This configuration might be reasonable for development and testing (aside from security testing); however for production environments this will most likely not be ideal, and the default username should therefore be deleted or changed to a RabbitMQ username that has only the required permissions. It is generally also a good idea to disable the RabbitMQ guest user, or to at least reduce the permissions of guest (when RabbitMQ is initially installed, the username guest has full permissions and a rather well-known password).
A Rabbitmq Management Plugin for RabbitHub can be found here https://github.com/gfiehler/rabbithub_management
Unfortunately due to changes in mnesia tables from older versions of RabbitHub, at this time, an upgrade from a previous version of RabbitHub requires that the mnesia directory (/var/lib/rabbitmq/mnesia) directory is deleted before the upgrade. This will mean a loss of all Rabbitmq messages and configuration. Configuration can be saved via the rabbitmq-management ui/api by downloading the Rabbitmq definitions and then uploading them after the update. However, this does not save in flight messages. It is highly suggested that all publishers are turned off temporarily, wait until all in flight messages are consumed, export Rabbitmq definitions, then perform the upgrade.
RabbitHub uses Rabbitmq security so the use of RabbitHub requires a valid Rabbitmq user for the vhost being used.
Some RabbitHub api's require the use of the administrator tag for the user, also required to access the RabbitHub Management UI PLugin, and also the RabbitHub specific tag of rabbithub_admin.
To import/export RabbitHub subscribers via the subscriptions resource, the rabbithub_admin' tag is required.
RabbitHub environment variables can be set in the rabbitmq.config file typically found in /etc/rabbitmq on linux systems.
Values: true/false
true: (default)will not requeue, message may be lost.
false: will requeue, best utilized when queue has a dead-letter-exchange configured
Values: true/false
true: (default) on HTTP Post error to subscriber, the consumer will be unsubscribed.
false: on HTTP Post error to subscriber the consumer will not be unsubscribed.
Note: If this variable is set to false, it will NOT override unsubscribe_on_http_post_error_limit and unsubscribe_on_http_post_error_timeout_milliseconds and will unsubscribe when reaching the configured limits.
Values: integer
Integer value is how many errors are allowed prior to the consumer being unsubscribed Note: unsubscribe_on_http_post_error_limit and unsubscribe_on_http_post_error_timeout_milliseconds must be set as a pair as it designates that unsubscribe_on_http_post_error_limit may occur within unsubscribe_on_http_post_error_timeout_milliseconds time interval before the consumer is unsubscribed
Values: milliseconds
Time interval where unsubscribe_on_http_post_error_limit errors are allowed to happen prior to unsubscribing the consumer
Note: unsubscribe_on_http_post_error_limit and unsubscribe_on_http_post_error_timeout_milliseconds must be set as a pair as it designates that unsubscribe_on_http_post_error_limit may occur within unsubscribe_on_http_post_error_timeout_milliseconds time interval before the consumer is unsubscribed
Values: milliseconds
If a consumer fails, the configured interval will be waited prior to attemtping a restart. This is useful when a master queue fails over to a new host.
Values: all/Integer
none: default behaviour is when a subscription is created to start a consumer on the node to which the subscription request was sent.
all: when a subscription is created start a consumer on all nodes in the cluster.
Int: When a subscription is created start a consumer on (Int) nodes in the cluster. The nodes are picked at random. If (Int) is greater than the number of nodes it will behave like (all).
Note: See Configuration Section to find default value used when not provided in the creation of a Subscriber
Values: true/false
true: Log messages being Posted to RabbitHUb subscribers.
false: (default) Do not log messages being Posted to RabbitHUb subscribers
Values: true/false
true: (default) Append hub.topic parameter when Posting a message to a subscriber.
false: Do not append hub.topic parameter when Posting a message to a subscriber
Values: true/false
true: Add local server name to standard consumer tag [amq.http.consumer.localservername-AhKV3L3eH2gZbrF79v2kig].
false: (default) Use standard consumer tag [amq.http.consumer-AhKV3L3eH2gZbrF79v2kig].
Note: Consumer tags can be viewed in the queue details screen
Values: comma delimited list of http headers
A comma separated list of http headers to be logged with each published event.
Note: E.g.
['content_type', 'Authorization']
Values: true/false
true: (default) To unsubscribe or deactivate a subscription, the callback URL must be active and validate to allow deactivation.
false: RabbitHub will not validate a unsubscribe/deactivation with the callback URL
Values: http header name
The name of a http header to use as a message correlation id, when recieved on a publish event, the id will be passed to the subscriber in the same http header.
Note: E.g. 'x-correlation-id'
Values: http header name
The name of a http header to use to pass a RabbitHub generated message id to subscribers.
Note: E.g. 'x-message-id'
Values: true/false
true: Log all messages published via RabbitHub.
false: (default) Do not log all published messages.
Note: log_message_body only works when this is set to true
Values: true/false
true: Log Message body when message is published.
false: (default) Do not log message body when messages are published<.
Note: log_message_body only works when log_published_messages is set to true
Values: rabbitmq user name
This is the username that RabbitHub will use if one is not explicitly sent to the RabbitHub apis.
Values: RabbitHub API Listening Port
This is the port on which the RabbitHub apis will listen.
Values:
{
"max_keep_alive_length": 0,
"max_pipeline_length": 0,
"max_sessions": 4
}
These are options that can be set to control the http client behaviour in json format.
Values:
{
"timeout": 5000
}
These are options that can be set to control http request to the subscriber in json format.
Values: true/false
true: If subscriber has Max TPS set (non zero) do not log the delay time for each POST.
false: (default) If subscriber has Max TPS set (non zero) log the delay time for each POST.
Note: Max TPS can be set when creating a subscriber with the hub.maxttps parameter, this value is used to calculate how long to delay between POSTs to a subscriber. See documentation for details.
Values: true/false
true: (default) Backwards compatibility setting, by default RabbitHub uses an internally declared queue when a subscription is made directly to an exchange. In this mode some new features in error management are not avaiable and consumers are not assigned to the queue.
false: Generate a queue and assign to a standard consumer, all RabbitHUb features are available.
Note: See documentation for details.
Values: Days (Integer)
Days: When a message is sent to a subscriber, log the expiration date of the subscriber if the number of days before expiration is less than this value
Values: seconds (Integer)
This is the default number of seconds a lease will be given when hub.lease_seconds is not given when a suscriber is created. If this variable is not present the default value is 30 days.
Note: See Configuration Section to find default value used when not provided in the creation of a Subscriber
More details on the above configurations will be found in the following sections.
RabbitHub now creates copies of its 3 mnesia tables across all nodes of a cluster for enhanced cluster failover ability.
- rabbithub_lease (disc_copy)
- rabbithub_outbound_auth (disc_copy)
- rabbithub_subscriber_contact_info (disc_copy)
- rabbithub_subscription_pid (ram_copy)
- rabbithub_subscription_err (ram_copy)
Consumer Tags show up in the Rabbitmq Management UI on the detail screen for a queue. This helps identify the RabbitHub consumer that was created for a subscriber. However, since a consumer runs on a single node in a cluster, it does not help identify where the Consumer is located in the cluster. The server that a Consumer is created on in a cluster is governed by the ha_consumers environment variable discussed below.
The Environment Variable: include_servername_in_consumer_tag set to true will add the server name on which the Consumer is running to the Consumer Tag.
amq.http.consumer.*localservername*-AhKV3L3eH2gZbrF79v2kig
where the localservername is the server name of the rabbitmq cluster node on which the consumer was created by setting RabbitHub environment variable include_servername_in_consumer_tag to true.
By not setting this variable the backwards compatible consumer tag of
amq.http.consumer-AhKV3L3eH2gZbrF79v2kig
will be used. An example can of setting this variable can be found in the test folder in the file: rabbitmq.config.consumertag.
RabbitHub now supports several modes in which you can create more than 1 consumer for a subscription across the cluster for high availability.
By setting the ha_consumers environment variable to one of the following modes
all: when a subscription is created a copy of the consumer is created on all nodes of the cluster n: where n is an integer, in this mode a copy of the consumer will be started on n number of nodes plus the original node to which the subscription was made. Therefore if ha_consumers=1 and there are more than 1 node in the cluster, 2 consumers will be created. The n consumers will be created on randomly selected cluster nodes other than the original node.
Note: In these modes Rabbithub will first create the consumer on the local node to which the subscription was made, if that consumer starts, it will always return a positive return code to the subscriber, even if some or all of the remote consumers do not start. The body of the response will include status of all attempted consumer starts. The following is an example response
{ "consumers": [{ "node": "rabbit@rabbit1", "status": "ok" }, { "node": "rabbit@rabbit2", "status": "ok" }] }
If HA Queues are being used in the Rabbitmq cluster and a node goes down, those queues will failover to another node according to the Rabbitmq policies set for HA Queues. When this happens The consumers that are connected to that queue will also go down. However, Rabbithub will attempt to restart all consumers that fail. However, the restart attempts generally happen too quickly for the master queues to failover and be ready to accept new connection. To solve this issue a new environment variable can be set to set a wait interval between a consumer going down and the restart attempt which will, in most cases, allow the master queue to failover and be ready to accept new connections.
Environment Variable: wait_for_consumer_restart_milliseconds = N where N is an integer in milliseconds.
If RabbitHub is being used behind a firewall, it may be necessary to route HTTP(s) requests to callback URLs via a proxy server. A proxy server can be specified for RabbitHub by defining http_client_options in rabbitmq.config as illustrated below, where the same proxy server has been specified for both HTTP and HTTPS, and the proxy server will not be used for requests to localhost.
[
{rabbithub, [
{http_client_options, [
{proxy, {{"10.1.1.1", 8080), ["localhost]}}
]}
]}
].
Note that proxy server support is only available in RabbitHub for RabbitMQ 3.2.1 or higher.
To help troubleshoot or just log activity an option is available to log the payload of all http posts to subscribers.
Environment Variable: log_http_post_request = true/false ..* true: will log all posts to subscribers ..* false: (default) will not log posts to subscribers
Environment Variable: log_published_messages = true/false ..* true: will log all messages published to RabbitHUb with Message ID (if configured), Correlation ID (if present) and Configured Message Headers. ..* false: (default) will not log messages published to RabbitHub
Environment Variable: log_message_body = true/false ..* true: if log_published_messages is set to true, also log the message body with published messages ..* false: (default) will not log message body for published messages
To log other values that may be useful for troubleshooting or for archive records the following Environment Variables are available:
Environment Variable: log_http_headers = [header1,] ..* List of HTTP Headers: a comma separated list of http headers in single quotes. E.g. ['content-type',] Each http header, if it exists, when a message is published to RabbitHub will be logged.
Environment Variable: set_correlation_id = 'http header' ..* HTTP Header: the name of an http header that will have a value of a correlation id. E.g. 'x-correlation-id' If this header exists when a message is published to RabbitHub, the value will be passed on to all subscribers using the same http header on the Post to the subscriber.
Environment Variable: set_message_id = 'http header' ..* HTTP Header: the name of an http header to send a message id to the subscriber. E.g. 'x-message-id' If this variable is set, when a message is published to RabbitHub, a message id will be generated and logged with the publication and then the message id will be sent to all subscribers as the value to this http header.
By default the subscriber callback URL must be active and available to validate subscribe and unsubscribe requests. The following environment variable allows for unsubscribing (deactivating) a subscriber without the validation to the callback URL. This can be useful if a subscriber is down and it is desired to keep the subscription record in an inactive state until it is back up and available.
Environment Variable: validate_callback_on_unsubscribe = true/false ..* true (default): default behavior requires the callback URL to validate all unsubscribe/deactivate requests ..* false: when a unsubscribe request is made, do not validate with the callback URL, shutdown any active consumers and change status to inactive.
Options that are used when sending a HTTP POST request to the subscriber. E.g. timeout and connect_timeout. Please see the HTTP Option section of http://erlang.org/doc/man/httpc.html#request-5.
[ {rabbithub, [ {http_request_options, [ {timeout, 2000} ]} ]} ].
By default, any action to the subscriber must be validated. This is done by making a GET request to the subscriber with a token value and the subscriber must respond with the token. Validation is done on subscribe and unsubscribe commands. Subscribe is always required, however, unsubscribe validation can be turned off with the following environment variable. This can be useful if a subscriber has stopped without unsubscribing and large numbers of messages are being backed up.
validate_callback_on_unsubscribe = (true, false) ..* true: default value. Requires validation by calling subscriber to unsubscribe. ..* false: does not require validation to unsubscribe.
RabbitHub environment variable- append_hub_topic_to_callback: (true, false) ..* true: (default) Append hub.topic parameter when Posting a message to a subscriber ..* false: Do not append hub.topic parameter when Posting a message to a subscriber
Two new rabbithub environment parameters are now available to control what happens when a HTTP POST to a consumer fails. The following parameters can be defined in the rabbitmq.config file These are set in the rabbitmq.config file as illustrated below
-
requeue_on_http_post_error = (true, false)
- true: will not requeue, message may be lost
- false: will requeue, best utilized when queue has a dead-letter-exchange configured
-
unsubscribe_on_http_post_error = (true, falise)
- true: (default) on HTTP Post error to subscriber, the consumer will be unsubscribed
- false: on HTTP Post error to subscriber the consumer will not be unsubscribed
- Note: If this variable is set to false, it will override unsubscribe_on_http_post_error_limit and unsubscribe_on_http_post_error_timeout_milliseconds and not unsubscribe even when reaching the configured limits.
-
unsubscribe_on_http_post_error_limit = integer
- Integer value is how many errors are allowed prior to the consumer being unsubscribed
-
unsubscribe_on_http_post_error_timeout_milliseconds = milliseconds
- Time interval where unsubscribe_on_http_post_error_limit errors are allowed to happen prior to unsubscribing the consumer
- NOTE: unsubscribe_on_http_post_error_limit and unsubscribe_on_http_post_error_timeout_milliseconds must be set as a pair as it designates that unsubscribe_on_http_post_error_limit may occur within unsubscribe_on_http_post_error_timeout_milliseconds time interval before the consumer is unsubscribed. Also if these are set unsubscribe_on_http_post_error will not be used as the above overrides it.
This sample configuration will send rejected messages to the configured dead letter queue and if more than 5 of these errors occur within a 60 second period, the subscriber will be deactivated.
[
{rabbithub, [
{requeue_on_http_post_error, false},
{unsubscribe_on_http_post_error_limit, 5},
{unsubscribe_on_http_post_error_timeout_milliseconds, 60000}
]}
].
Note: an example of this configuration can be found in the test folder in file: rabbitmq.config.errormanagement.
These errors are tracked per subscriber and re-subscribing will reset the error tracking for that subscriber.
To help understand how many errors have occurred the following rest endpoint returns a list of all error counts currently being tracked.
GET http://localhost:15670/subscriptions/errors
- resource: vhost
- queue: queue name
- topic: routing key from hub.topic parameter
- callback: url of callback subscriber
- error_count: number of HTTP POST errors for this subscriber since the first_error_time_microsec
- first_error_time_microsec: time in microseconds for the first error in this interval
- last_error_time_microsec: time in microseconds of the last error that occurred
[{
"resource": "/",
"queue": "foo2",
"topic": "foo2",
"callback": "http://localhost:8999/rest/testsubscriber2",
"error_count": 1,
"first_error_time_microsec": 1467326540248893,
"last_error_time_microsec": 1467326540248893
}, {
"resource": "/",
"queue": "foo1",
"topic": "foo1",
"callback": "http://localhost:8999/rest/testsubscriber1",
"error_count": 2,
"first_error_time_microsec": 1467326520609017,
"last_error_time_microsec": 1467326522694452
}]
The following api will return a json formatted list of the current subscribers for RabbitHub.
Note: both import and export of subscribers requires a user with rabbitmq tags (roles) administrator,rabbithub_admin
curl --request GET http://guest:guest@localhost:15670/subscriptions
- vhost: vhost
- resource_type: queue or exchange
- resource_name: name of resource
- topic: routing key from hub.topic parameter
- callback: url of callback subscriber
- lease_expiry_time_microsec: date time of subscription expiration in microseconds- http://localhost:15670/subscriptions. * This field is ignored on a POST.
- lease_seconds: the lease time in seconds as given at time of subscription
- ha_mode: HA Mode (all, n, none)
- status: active/inactive (equivalent to hub.mode subscribe/unsubscribe
- max_tps: number of transactions per second allowed to this subscriber
- pseudo_queue: when subscribing to an exchange, a queue is created for the subscription by RabbitHub, this is the definition of this queue. This field is ignored on a POST.
- outbound_auth: section to hold authentication values for calling a subscribers callback url. This has 2 data fields, * * * auth_type and auth_config. Currently only basic_auth is supported.
- auth_type: basic_auth is the only currently supported auth_type.
- auth_config: the base64 encoded string for the user:pass for basic authentication when calling the subscriber callback url
- contact: this section hold contact information about the subscriber
- app_name: the name of the subscribing application
- contact_name: the contact person for the subscription
- phone: the contact phone number for the subscription
- email: the contact email address for the subscription
- description: a description of the subscription
{
"subscriptions": [{
"vhost": "rhtest2",
"resource_type": "exchange",
"resource_name": "xfanout1",
"topic": "testx1",
"callback": "http://localhost:8999/rabbithub/s1",
"lease_expiry_time_microsec": 4638804849466651,
"lease_seconds": 3153600000,
"ha_mode": 1,
"status": "active",
"max_tps": 0,
"pseudo_queue": "[{amqqueue,{resource,<<\"rhtest2\">>,queue, <<\"amq.http.pseudoqueue-BeIw7rnvjx9i2p_6CS5-0Q\">>}, true,false,none,[],<0.6145.2>,[],[],[],undefined,[],[],live,0}]",
"outbound_auth": "undefined",
"contact": "undefined"
}, {
"vhost": "rhtest2",
"resource_type": "queue",
"resource_name": "q1",
"topic": "testq1allparams",
"callback": "http://localhost:8999/rabbithub/s1",
"lease_expiry_time_microsec": 1485291249262811,
"lease_seconds": 86400,
"ha_mode": "all",
"status": "active",
"max_tps": 2,
"pseudo_queue": "[undefined]",
"outbound_auth": {
"auth_type": "basic_auth",
"auth_config": "base64encodedstring"
},
"contact": {
"app_name": "my est app 2",
"contact_name": "my name",
"phone": "111-111-1111",
"email": "me@mail.com",
"description": "my test app description"
}
}]
}
The file that was exported in the previous section can then be imported with the following API
Note: both import and export of subscribers requires a user with rabbitmq tags (roles) administrator,rabbithub_admin
curl -d '{
"subscriptions": [{
"vhost": "rhtest2",
"resource_type": "exchange",
"resource_name": "xfanout1",
"topic": "testx1",
"callback": "http://localhost:8999/rabbithub/s1",
"lease_expiry_time_microsec": 4638804849466651,
"lease_seconds": 3153600000,
"ha_mode": 1,
"status": "active",
"max_tps": 0,
"pseudo_queue": "[{amqqueue,{resource,<<\"rhtest2\">>,queue, <<\"amq.http.pseudoqueue-BeIw7rnvjx9i2p_6CS5-0Q\">>}, true,false,none,[],<0.6145.2>,[],[],[],undefined,[],[],live,0}]",
"outbound_auth": "undefined",
"contact": "undefined"
}, {
"vhost": "rhtest2",
"resource_type": "queue",
"resource_name": "q1",
"topic": "testq1allparams",
"callback": "http://localhost:8999/rabbithub/s1",
"lease_expiry_time_microsec": 1485291249262811,
"lease_seconds": 86400,
"ha_mode": "all",
"status": "active",
"max_tps": 2,
"pseudo_queue": "[undefined]",
"outbound_auth": {
"auth_type": "basic_auth",
"auth_config": "base64encodedstring"
},
"contact": {
"app_name": "my est app 2",
"contact_name": "my name",
"phone": "111-111-1111",
"email": "me@mail.com",
"description": "my test app description"
}
}]
}' --header "content-type:application/json" http://guest:guest@localhost:15670/subscriptions
Both export and import are also available via the RabbitHub Management UI.
If you need to update the configuration, such as expiration or ha mode, and the subscriber is already running and active, you must first deactivate the subscriber, then activate it with the new configuration. If you update the subscriber configuration while it is active, it will not affect the current running subscriber, but will take affect on the next consumer restart. This can be done via the API, UI or via batch updates.