rabbitmq-server/deps/rabbitmq_auth_backend_cache/README.md

RabbitMQ Access Control Cache Plugin

This plugin provides a caching layer for access control operations performed by RabbitMQ nodes.

Project Maturity

This plugin is relatively young but has known production users. It's a candidate for inclusion into the RabbitMQ distribution.

Overview

This plugin provides a way to cache authentication and authorization backend results for a configurable amount of time. It's not an independent auth backend but a caching layer for existing backends such as the built-in, LDAP, or HTTP ones.

Cache expiration is currently time-based. It is not very useful with the built-in (internal) authn/authz backends but can be very useful for LDAP, HTTP or other backends that use network requests.

RabbitMQ Version Requirements

As with all authentication plugins, this plugin requires requires 2.3.1 or later.

master branch targest RabbitMQ master (future 3.7.0). To use this plugin with RabbitMQ 3.6.x, see the stable branch.

Erlang Version Requirements

This plugin requires Erlang 18.3 or a later version.

Binary Builds

Binary builds can be obtained from project releases on GitHub.

Building

You can build and install it like any other plugin (see the plugin development guide).

Authentication and Authorization Backend Configuration

To enable the plugin, set the value of the auth_backends configuration item for the rabbit application to include rabbit_auth_backend_cache. auth_backends is a list of authentication providers to try in order.

So a configuration fragment that enables this plugin only would look like:

auth_backends.1 = cache

Or using the classic config for both parameters:

[{rabbit, [{auth_backends, [rabbit_auth_backend_cache]}]}].

To configure upstream auth backend, you should use cached_backend configuration item for the rabbitmq_auth_backend_cache application.

Configuration that uses LDAP auth backend:

auth_cache.cached_backend = ldap

[{rabbitmq_auth_backend_cache, [{cached_backend, rabbit_auth_backend_ldap}]}].

It is still possible to use different backends for authorization and authentication.

The following example configures plugin to use LDAP backend for authentication but internal backend for authorisation:

auth_cache.cached_backend.authn = ldap
auth_cache.cached_backend.authz = internal

Or using the classic config for both parameters:

[{rabbitmq_auth_backend_cache, [{cached_backend, {rabbit_auth_backend_ldap,
                                                  rabbit_auth_backend_internal}}]}].

Cache Configuration

You can configure TTL for cache items, by using cache_ttl configuration item, specified in milliseconds

auth_cache.cached_backend = ldap
auth_cache.cache_ttl = 5000

Or using the classic config for both parameters:

[{rabbitmq_auth_backend_cache, [{cached_backend, rabbit_auth_backend_ldap}
                                {cache_ttl, 5000}]}].

You can also use a custom cache module to store cached requests. This module should be an erlang module implementing rabbit_auth_cache behaviour and (optionally) define start_link function to start cache process.

This repository provides several implementations:

• rabbit_auth_cache_dict stores cache entries in the internal process dictionary. This module is for demonstration only and should not be used in production.
• rabbit_auth_cache_ets stores cache entries in an ETS table and uses timers for cache invalidation. This is the default implementation.
• rabbit_auth_cache_ets_segmented stores cache entries in multiple ETS tables and does not delete individual cache items but rather uses a separate process for garbage collection.
• rabbit_auth_cache_ets_segmented_stateless same as previous, but with minimal use of gen_server state, using ets tables to store information about segments.

To specify module for caching you should use cache_module configuration item and specify start args with cache_module_args. Start args should be list of arguments passed to module start_link function

Cache module can be set via sysctl config format:

auth_cache.cache_module = rabbit_auth_backend_ets_segmented

Cache module additional arguments can be defined via the classic-style config only:

[{rabbitmq_auth_backend_cache, [{cache_module_args, [10000]}]}].

The above two snippets used in the classic config format:

[{rabbitmq_auth_backend_cache, [{cache_module, rabbit_auth_backend_ets_segmented},
                                {cache_module_args, [10000]}]}].

The default values are rabbit_auth_cache_ets and [], respectively.

License and Copyright

(c) 2016-2017 Pivotal Software Inc.

Released under the Mozilla Public License 1.1, same as RabbitMQ.