| //// |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License |
| //// |
| |
| [[policy]] |
| = Policy |
| |
| The Policy module is an optional authorization mechanism enforcing |
| user connection restrictions and AMQP resource access control. |
| |
| Policy is assigned when a connection is created. The connection |
| properties *AMQP virtual host*, *authenticated user name*, and *connection |
| remote host* are passed to the policy engine for a connection |
| allow/deny decision. If the connection is allowed then the user is |
| assigned to a group that names a set of AMQP resource limits that are |
| enforced for the lifetime of the connection. |
| |
| [NOTE] |
| ==== |
| Policy limits are applied only to incoming user network connections. |
| Policy limits are not applied to interrouter connections nor are they |
| applied to router connections outbound to waypoints. |
| ==== |
| |
| == Definitions |
| |
| === vhost |
| |
| A _vhost_ is typically the name of the host to which the client AMQP |
| connection is directed. For example, suppose a client application opens |
| connection URL: |
| |
| [options="nowrap"] |
| ---- |
| amqp://bigbroker.example.com:5672/favorite_subject |
| ---- |
| |
| The client will signal virtual host name _bigbroker.example.com_ to |
| the router during AMQP connection startup. Router Policy intercepts |
| the virtual host _bigbroker.example.com_ and applies a vhost policy |
| with that name to the connection. |
| |
| == Policy Features |
| |
| === Total Connection Limit |
| |
| A router may be configured with a total connection limit. This limit |
| controls the maximum number of simultaneous incoming user connections |
| that are allowed at any time. It protects the router from file |
| descriptor resource exhaustion in the face of many incoming client |
| connections. This limit is specified and enforced independently of |
| any other Policy settings. |
| |
| === Vhost Policy |
| |
| Vhost policy defines users and assigns them to user groups. Each |
| user group defines the remote hosts from which the members may connect |
| to the router network, and what resources in the router network the |
| group members are allowed to access. |
| |
| Vhost policy also defines connection count limits to control the |
| number of users that may be simultaneously connected to the vhost. |
| |
| [NOTE] |
| ==== |
| A vhost user may be assigned to one user group only. |
| ==== |
| |
| === Default Vhost |
| |
| A default vhost may be defined. The default vhost policy is used for |
| connections whose vhost is otherwise not defined in the policy database. |
| |
| xref:example2[Example 2] illustrates how the default vhost feature can |
| be used to apply a single vhost policy set of restrictions to any |
| number of vhost connections. |
| |
| == Policy Schema |
| |
| Policy configuration is specified in two schema objects. |
| |
| [options="nowrap"] |
| ---- |
| policy = { |
| <global settings> |
| } |
| |
| vhost = { |
| id: vhost-name |
| <connection limits> |
| groups: { |
| group-name: { |
| <user group settings> |
| } |
| } |
| } |
| ---- |
| |
| The _policy_ object is a singleton. Multiple _vhost_ objects may be |
| created as needed. |
| |
| === Global Policy |
| |
| [options="header", cols="35,15,50"] |
| |==== |
| | attribute | default | description |
| | maxConnections | 65535 | Global maximum number of concurrent client connections allowed. This limit is always enforced even if no other policy settings have been defined. This limit is applied to all incoming connections regardless of remote host, authenticated user, or targeted vhost. |
| | enableVhostPolicy | false | Enable vhost policy connection denial, and resource limit enforcement. |
| | policyDir | "" | Absolute path to a directory that holds vhost definition .json files. All vhost definitions in all .json files in this directory are processed. |
| | defaultVhost | "$default" | Vhost rule set name to use for connections with a vhost that is otherwise not defined. Default vhost processing may be disabled either by erasing the definition of _defaultVhost_ or by not defining a _vhost_ object named _$default_. |
| |==== |
| |
| === Vhost Policy |
| |
| [options="header", cols="35,15,50"] |
| |==== |
| | attribute | default | description |
| | id | | Vhost name must be unique. |
| | maxConnections | 65535 | Maximum number of concurrent client connections allowed. |
| | maxConnectionsPerUser | 65535 | Maximum number of concurrent client connections allowed for any user. |
| | maxConnectionsPerRemoteHost | 65535 | Maximum number of concurrent client connections allowed for any remote host. |
| | allowUnknownUser | false | Allow unknown users who are not members of a defined user group. Unknown users are assigned to the '$default' user group and receive '$default' settings. |
| | groups | | A map where each key is a user group name and the value is a Vhost User Group Settings map. |
| |==== |
| |
| === Vhost User Group Settings Map |
| |
| This object is the data value contained in entries in the policy/groups map. |
| |
| [options="header", cols="35,15,50"] |
| |==== |
| | Section/Attribute | default | description |
| | *Group Membership* | | |
| | users | "" | List of authenticated users in this group. |
| | *Connection Restrictions* | | |
| | remoteHosts | "" | List of remote hosts from which the users may connect. List values may be host names, numeric IP addresses, numeric IP address ranges, or the wildcard '*'. An empty list denies all access. |
| | *AMQP Connection Open Limits* | | |
| | maxFrameSize | 2^31-1 | Largest frame that may be sent on this connection. (AMQP Open, max-frame-size) |
| | maxSessions | 65535 | Maximum number of sessions that may be created on this connection. (AMQP Open, channel-max) |
| | *AMQP Session Begin Limits* | | |
| | maxSessionWindow | 2^31-1 |Incoming capacity for new sessions. (AMQP Begin, incoming-window) |
| | *AMQP Link Attach* | | |
| | maxMessageSize | 0 | Largest message size supported by links created on this connection. If this field is zero there is no maximum size imposed by the link endpoint. (AMQP Attach, max-message-size) |
| | maxSenders | 2^31-1 | Maximum number of sending links that may be created on this connection. |
| | maxReceivers | 2^31-1 | Maximum number of receiving links that may be created on this connection. |
| | allowDynamicSource | false | This connection is allowed to create receiving links using the Dynamic Link Source feature. |
| | allowAnonymousSender | false | This connection is allowed to create sending links using the Anonymous Sender feature. |
| | sources | "" | List of Source addresses allowed when creating receiving links. This list may be expressed as a CSV string or as a list of strings. An empty list denies all access. |
| | targets | "" | List of Target addresses allowed when creating sending links. This list may be expressed as a CSV string or as a list of strings. An empty list denies all access. |
| |==== |
| |
| == Policy Wildcard and User Name Substitution |
| |
| Policy provides several conventions to make writing rules easier. |
| |
| === Remote Host Wildcard |
| |
| Remote host rules may consist of a single asterisk character to |
| specify all hosts. |
| |
| [options="nowrap"] |
| ---- |
| remoteHosts: * |
| ---- |
| |
| The asterisk must stand alone and cannot be appended to a host name |
| or to an IP address fragment. |
| |
| === User Name Wildcard |
| |
| User names in group name lists may be specified by a name prefix |
| terminated with a single asterisk character. |
| |
| [options="nowrap"] |
| ---- |
| users: customer*, admin, employee* |
| ---- |
| |
| === AMQP Source and Target Wildcard and Name Substitution |
| |
| The rule definitions for `sources` and `targets` may include the username |
| substitution token |
| |
| [options="nowrap"] |
| ---- |
| {user} |
| ---- |
| |
| or a trailing asterisk. |
| |
| The username substitution token is replaced with the authenticated user name for |
| the connection. Using this token, an administrator may allow access to |
| some resources specific to each user without having to name each user |
| individually. This token is substituted once for the leftmost |
| occurrence in the link name. |
| |
| The asterisk is recognized only if it is the last character in the |
| link name. |
| |
| [options="nowrap"] |
| ---- |
| sources: tmp_{user}, temp*, {user}-home-* |
| ---- |
| |
| == Composing Policies |
| |
| This section shows policy examples designed to illustrate some common use cases. |
| |
| === Example 1. User Policy Disabled |
| |
| Policy is disabled when no policy configuation objects are defined. |
| Any number of connections are allowed and all users have |
| access to all AMQP resources in the network. |
| |
| [[example2]] |
| === Example 2. All Users Have Simple Connection Limits |
| |
| This example shows how to keep users from overwhelming the router with |
| connections. Any user can create up to ten connections and the router |
| will limit the aggregated user connection count to 100 connections |
| total. No other restrictions apply. |
| |
| This example also shows how to use a default vhost policy effectively. |
| Only one vhost policy is defined and all user connections regardless |
| of the requested vhost use that policy. |
| |
| [options="nowrap"] |
| ---- |
| policy { |
| maxConnections: 100 <1> |
| } |
| |
| vhost { |
| name: $default <2> |
| maxConnectionsPerUser: 10 <3> |
| groups: { |
| all: { |
| users: * <4> |
| remoteHosts: * <5> |
| sources: * <6> |
| targets: * <6> |
| } |
| } |
| } |
| ---- |
| |
| <1> The global maxConnections limit of 100 is enforced. |
| <2> No normal vhost names are defined; user is assigned to default vhost '$default'. |
| <3> The vhost maxConnectionsPerUser limit of 10 is enforced. |
| <4> User name is found in user group 'all' |
| <5> The user is allowed to connect from any remote host. The connection is approved and the user gets user group 'all' settings. |
| <6> The user is allowed to connect to any source or target in the AMQP network. Router system-wide values are used for the other AMQP settings that are unspecified in the vhost rules. |
| |
| === Example 3. Admins Must Connect From Localhost |
| |
| This example shows how an admin group may be created and restricted |
| to accessing a vhost only from localhost. The admin users are allowed |
| to connect to any AMQP resources while normal users are restricted. |
| |
| In this example a user connects to vhost 'example.com'. |
| |
| [options="nowrap"] |
| ---- |
| vhost { |
| name: example.com <1> |
| allowUnknownUser: true <3> |
| groups: { |
| admin: { |
| users: alice, bob <2> |
| remoteHosts: 127.0.0.1, ::1 <4> |
| sources: * <5> |
| targets: * <5> |
| }, |
| $default: { |
| remoteHosts: * <6> |
| sources: news*, sports*, chat* <7> |
| targets: chat* <7> |
| } |
| } |
| } |
| ---- |
| |
| <1> A connection to vhost 'example.com' locates this vhost rule set. |
| <2> If one of users _alice_ or _bob_ is connecting then she or he is assigned to the 'admin' user group. |
| <3> Any other user is not defined by a user group. However, since the _allowUnknownUser_ setting is true then this user is assigned to the '$default' user group. |
| <4> Users in the 'admin' user group must connect from localhost. Connections for an 'admin' user from other hosts on the network are denied. |
| <5> Users in the 'admin' user group are allowed to access any resource offered by the vhost service. |
| <6> Other users are allowed to connect from any host. |
| <7> Other users have source and target name lists that restrict the resources they are allowed to access. |
| |
| === Example 4. Limiting Possible Memory Consumption |
| |
| Policy provides a mechanism to control how much system buffer memory a |
| user connection can potentially consume. The formula for computing |
| buffer memory consumption for each session is |
| |
| [optons="nowrap"] |
| ---- |
| potential buffer usage = maxFrameSize * maxSessionWindow |
| ---- |
| |
| By adjusting _maxFrameSize_, _maxSessions_, and _maxSessionWindow_ an |
| administrator can prevent a user from consuming too much memory by |
| buffering messages in flight. |
| |
| [NOTE] |
| ==== |
| The settings passed into the AMQP protocol connection and session |
| negotiations. Normal AMQP session flow control limits buffer |
| consumption in due course with no processing cycles required by the |
| router. |
| ==== |
| |
| In this example normal users, the traders, are given smaller buffer |
| allocations while high-capacity, automated data feeds are given a |
| higher buffer allocation. This example skips the details of settings |
| unrelated to buffer allocation. |
| |
| [options="nowrap"] |
| ---- |
| vhost { |
| name: traders.com <1> |
| groups: { |
| traders: { |
| users: trader-* <2> |
| maxFrameSize: 10000 <3> |
| maxSessionWindow: 500 <3> |
| maxSessions: 1 <4> |
| ... |
| }, |
| feeds: { |
| users: nyse-feed, nasdaq-feed <5> |
| maxFrameSize: 60000 <6> |
| maxSessionWindow: 20000 <6> |
| maxSessions: 3 <7> |
| ... |
| } |
| } |
| } |
| ---- |
| |
| <1> These rules are for vhost traders.com. |
| <2> The 'traders' group includes any user whose name begins with _trader-_. |
| <3> _maxFrameSize_ and _maxSessionWindow_ allow for at most 5,000,000 bytes of data to be in flight on each session. |
| <4> Only one session per connection is allowed. |
| <5> In the 'feeds' group two users are defined. |
| <6> _maxFrameSize_ and _maxSessionWindow_ allow for at most 1,200,000,000 bytes of data to be in flight on each session. |
| <7> Up to three sessions per connection are allowed. |
| |
| //// |
| |
| - Should we used signed ints for limits to allow for magic values? |
| |
| - In example 3, alice and bob cannot connect from an outside server and |
| get the $default settings. |
| |
| - Limits are enforced per router, so a vhost policy of maxConnections |
| 10 across 10 routers will allow 100 connections to that vhost. |
| |
| //// |