doc/book/policy.adoc - qpid-dispatch - Git at Google

 ////
 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 = {
     name: 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
 | name                        |          | Vhost name. A unique name is required.
 | maxConnections              | 65535    | Maximum number of concurrent client connections allowed
 | maxConnectionsPerUser       | 65535    | Maximum number of concurrent client connections allowed for any single 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 token
 '*{user}*' or a trailing asterisk.

 The _{user}_ 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.

 ////
	////
	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 = {
	name: 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
	\| name \| \| Vhost name. A unique name is required.
	\| maxConnections \| 65535 \| Maximum number of concurrent client connections allowed
	\| maxConnectionsPerUser \| 65535 \| Maximum number of concurrent client connections allowed for any single 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 token
	'{user}' or a trailing asterisk.

	The _{user}_ 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.

	////