+== Group Based Policy User Guide
+
+=== Overview
+OpenDaylight Group Based Policy allows users to express network configuration in a declarative versus imperative way.
+
+This is often described as asking for *"what you want"*, rather than *"how to do it"*.
+
+In order to achieve this Group Based Policy (herein referred to as *GBP*) is an implementation of an *Intent System*.
+
+An *Intent System*:
+
+* is a process around an intent driven data model
+* contains no domain specifics
+* is capable of addressing multiple semantic definitions of intent
+
+To this end, *GBP* Policy views an *Intent System* visually as:
+
+.Intent System Process and Policy Surfaces
+image::groupbasedpolicy/IntentSystemPolicySurfaces.png[align="center",width=500]
+
+* *expressed intent* is the entry point into the system.
+* *operational constraints* provide policy for the usage of the system which modulates how the system is consumed. For instance _"All Financial applications must use a specific encryption standard"_.
+* *capabilities and state* are provided by _renderers_. _Renderers_ dynamically provide their capabilities to the core model, allowing the core model to remain non-domain specific.
+* *governance* provides feedback on the delivery of the _expressed intent_. i.e. _"Did we do what you asked us?"_
+
+In summary *GBP is about the Automation of Intent*.
+
+By thinking of *Intent Systems* in this way, it enables:
+
+* *automation of intent*
++
+By focusing on *Model. Process. Automation*, a consistent policy resolution process enables for mapping between the *expressed intent* and renderers responsible for providing the capabilities of implementing that intent.
+
+* recursive/intent level-independent behaviour.
++
+Where _one person's concrete is another's abstract_, intent can be fulfilled through a hierarchical implementation of non-domain specific policy resolution. Domain specifics are provided by the _renderers_, and exposed via the API, at each policy resolution instance.
+For example:
+
+** To DNS: The name "www.foo.com" is _abstract_, and it's IPv4 address 10.0.0.10 is _concrete_,
+** To an IP stack: 10.0.0.10 is _abstract_ and the MAC 08:05:04:03:02:01 is _concrete_,
+** To an Ethernet switch: The MAC 08:05:04:03:02:01 is _abstract_, the resolution to a port in it's CAM table is _concrete_,
+** To an optical network: The port maybe _abstract_, yet the optical wavelength is _concrete_.
+
+NOTE: _This is a very domain specific analogy, tied to something most readers will understand. It in no way implies the *GBP* should be implemented in an OSI type fashion.
+The premise is that by implementing a full *Intent System*, the user is freed from a lot of the constraints of how the expressed intent is realised._
+
+It is important to show the overall philosophy of *GBP* as it sets the project's direction.
+
+In the Lithium release of OpenDaylight, *GBP* focused on *expressed intent* and *capabilities*.
+
+=== GBP Base Architecture and Value Proposition
+==== Terminology
+In order to explain the fundamental value proposition of *GBP*, an illustrated example is given. In order to do that some terminology must be defined.
+
+The Access Model is the core of the *GBP* Intent System policy resolution process.
+
+.GBP Access Model Terminology - Endpoints, EndpointGroups, Contract
+image::groupbasedpolicy/GBPTerminology1.png[align="center",width=500]
+
+.GBP Access Model Terminology - Subject, Classifier, Action
+image::groupbasedpolicy/GBPTerminology2.png[align="center",width=500]
+
+.GBP Forwarding Model Terminology - L3 Context, L2 Bridge Context, L2 Flood Context/Domain, Subnet
+image::groupbasedpolicy/GBPTerminology3.png[align="center",width=500]
+
+* Endpoints:
++
+Define concrete uniquely identifiable entities. In Lithium, examples could be a Docker container, or a Neutron port
+* EndpointGroups:
++
+EndpointGroups are sets of endpoints that share a common set of policies. EndpointGroups can participate in contracts that determine the kinds of communication that are allowed. EndpointGroups _consume_ and _provide_ contracts.
+They also expose both _requirements and capabilities_, which are labels that help to determine how contracts will be applied. An EndpointGroup can specify a parent EndpointGroup from which it inherits.
+
+* Contracts:
++
+Contracts determine which endpoints can communicate and in what way. Contracts between pairs of EndpointGroups are selected by the contract selectors defined by the EndpointGroup.
+Contracts expose qualities, which are labels that can help EndpointGroups to select contracts. Once the contract is selected,
+contracts have clauses that can match against requirements and capabilities exposed by EndpointGroups, as well as any conditions
+that may be set on endpoints, in order to activate subjects that can allow specific kinds of communication. A contract is allowed to specify a parent contract from which it inherits.
+
+* Subject
++
+Subjects describe some aspect of how two endpoints are allowed to communicate. Subjects define an ordered list of rules that will match against the traffic and perform any necessary actions on that traffic.
+No communication is allowed unless a subject allows that communication.
+
+* Clause
++
+Clauses are defined as part of a contract. Clauses determine how a contract should be applied to particular endpoints and EndpointGroups. Clauses can match against requirements and capabilities exposed by EndpointGroups,
+as well as any conditions that may be set on endpoints. Matching clauses define some set of subjects which can be applied to the communication between the pairs of endpoints.
+
+==== Architecture and Value Proposition
+
+*GBP* offers an intent based interface, accessed via the <<UX,UX>>, via the <<REST,REST API>> or directly from a domain-specific-language such as <<Neutron,Neutron>> through a mapping interface.
+
+There are two models in *GBP*:
+
+* the access (or core) model
+* the forwarding model
+
+.GBP Access (or Core) Model
+image::groupbasedpolicy/GBP_AccessModel_simple.png[align="center",width=500]
+
+The _classifier_ and _action_ portions of the model can be thought of as hooks, with their definition provided by each _renderer_ about its domain specific capabilities. In *GBP* Lithium, there is one renderer,
+the _<<OfOverlay,OpenFlow Overlay renderer (OfOverlay).>>_
+
+These hooks are filled with _definitions_ of the types of _features_ the renderer can provide the _subject_, and are called *subject-feature-definitions*.
+
+This means an _expressed intent_ can be fulfilled by, and across, multiple renderers simultaneously, without any specific provisioning from the consumer of *GBP*.
+
+[[forwarding]]
+Since *GBP* is implemented in OpenDaylight, which is an SDN controller, it also must address networking. This is done via the _forwarding model_, which is domain specific to networking, but could be applied to many different _types_ of networking.
+
+.GBP Forwarding Model
+image::groupbasedpolicy/GBP_ForwardingModel_simple.png[align="center",width=500]
+
+Each endpoint is provisioned with a _network-containment_. This can be a:
+
+* subnet
++
+** normal IP stack behaviour, where ARP is performed in subnet, and for out of subnet, traffic is sent to default gateway.
+** a subnet can be a child of any of the below forwarding model contexts, but typically would be a child of a flood-domain
+* L2 flood-domain
+** allows flooding behaviour.
+** is a n:1 child of a bridge-domain
+** can have multiple children
+* L2 bridge-domain
+** is a layer2 namespace
+** is the realm where traffic can be sent at layer 2
+** is a n:1 child of a L3 context
+** can have multiple children
+* L3 context
+** is a layer3 namespace
+** is the realm where traffic is passed at layer 3
+** is a n:1 child of a tenant
+** can have multiple children
+
+A simple example of how the access and forwarding models work is as follows:
+
+.GBP Endpoints, EndpointGroups and Contracts
+image::groupbasedpolicy/GBP_Endpoint_EPG_Contract.png[align="center",width=300]
+
+In this example, the *EPG:webservers* is _providing_ the _web_ and _ssh_ contracts. The *EPG:client* is consuming those contracts. *EPG:client* is providing the _any_ contract, which is consumed by *EPG:webservers*.
+
+The _direction_ keyword is always from the perspective of the _provider_ of the contract. In this case contract _web_, being _provided_ by *EPG:webservers*, with the classifier to match TCP destination port 80, means:
+
+* packets with a TCP destination port of 80
+* sent to (_in_) endpoints in the *EPG:webservers*
+* will be _allowed_.
+
+.GBP Endpoints and the Forwarding Model
+image::groupbasedpolicy/GBP_Endpoint_EPG_Forwarding.png[align="center",width=300]
+
+When the forwarding model is considered in the figure above, it can be seen that even though all endpoints are communicating using a common set of contracts,
+their forwarding is _contained_ by the forwarding model contexts or namespaces.
+In the example shown, the endpoints associated with a _network-containment_ that has an ultimate parent of _L3Context:Sales_ can only communicate with other endpoints within this L3Context.
+In this way L3VPN services can be implemented without any impact to the *Intent* of the contract.
+
+===== High-level implementation Architecture
+
+The overall architecture, including _<<Neutron,Neutron>>_ domain specific mapping, and the <<OfOverlay,OpenFlow Overlay renderer>> looks as so:
+
+.GBP High Level Lithium Architecture
+image::groupbasedpolicy/GBP_High-levelLithiumArchitecture.png[align="center",width=300]
+
+The major benefit of this architecture is that the mapping of the domain-specific-language is completely separate and independent of the underlying renderer implementation.
+
+For instance, using the <<Neutron,Neutron Mapper>>, which maps the Neutron API to the *GBP* core model, any contract automatically generated from this mapping can be augmented via the <<UX,UX>>
+to use <<SFC,Service Function Chaining>>, a capability not currently available in OpenStack Neutron.
+
+When another renderer is added, for instance, NetConf, the same policy can now be leveraged across NetConf devices simultaneously:
+
+.GBP High Level Lithium Architecture - adding a renderer
+image::groupbasedpolicy/GBP_High-levelExtraRenderer.png[align="center",width=300]
+
+As other domain-specific mappings occur, they too can leverage the same renderers, as the renderers only need to implement the *GBP* access and forwarding models, and the domain-specific mapping need only manage mapping to the access and forwarding models. For instance:
+
+.GBP High Level Lithium Architecture - adding a renderer
+image::groupbasedpolicy/High-levelLithiumArchitectureEvolution2.png[align="center",width=300]
+
+In summary, the *GBP* architecture:
+
+* separates concerns: the Expressed Intent is kept completely separated from the underlying renderers.
+* is cohesive: each part does it's part and it's part only
+* is scalable: code can be optimised around model mapping/implementation, and functionality re-used
+
+==== Policy Resolution [[policyresolution]]
+
+===== Contract Selection
+
+The first step in policy resolution is to select the contracts that are in scope.
+
+EndpointGroups participate in contracts either as a _provider_ or as a _consumer_ of a contract. Each EndpointGroup can participate in many contracts at the same time, but for each contract it can be in only one role at a time.
+In addition, there are two ways for an EndpointGroup to select a contract: either with either a:
+
+* _named selector_
++
+Named selectors simply select a specific contract by its contract ID.
+* target selector.
++
+Target selectors allow for additional flexibility by matching against _qualities_ of the contract's _target._
+
+Thus, there are a total of 4 kinds of contract selector:
+
+* provider named selector
++
+Select a contract by contract ID, and participate as a provider.
+
+* provider target selector
++
+Match against a contract's target with a quality matcher, and participate as a provider.
+
+* consumer named selector
++
+Select a contract by contract ID, and participate as a consumer.
+
+* consumer target selector
++
+Match against a contract's target with a quality matcher, and participate as a consumer.
+
+To determine which contracts are in scope, contracts are found where either the source EndpointGroup selects a contract as either a provider or consumer,
+while the destination EndpointGroup matches against the same contract in the corresponding role. So if endpoint _x_ in EndpointGroup _X_ is communicating with endpoint _y_
+in EndpointGroup _Y_, a contract _C_ is in scope if either _X_ selects _C_ as a provider and _Y_ selects _C_ as a consumer, or vice versa.
+
+The details of how quality matchers work are described further in <<Matchers,Matchers>>.
+Quality matchers provide a flexible mechanism for contract selection based on labels.
+
+The end result of the contract selection phase can be thought of as a set of tuples representing selected contract scopes. The fields of the tuple are:
+
+* Contract ID
+* The provider EndpointGroup ID
+* The name of the selector in the provider EndpointGroup that was used to select the contract, called the _matching provider selector._
+* The consumer EndpointGroup ID
+* The name of the selector in the consumer EndpointGroup that was used to select the contract, called the _matching consumer selector._
+
+===== Subject Selection
+
+The second phase in policy resolution is to determine which subjects are in scope.
+The subjects define what kinds of communication are allowed between endpoints in the EndpointGroups.
+For each of the selected contract scopes from the contract selection phase, the subject selection procedure is applied.
+
+Labels called, capabilities, requirements and conditions are matched against to bring a Subject _into scope_.
+EndpointGroups have capabilities and requirements, while endpoints have conditions.
+
+===== Requirements and Capabilities
+
+When acting as a _provider_, EndpointGroups expose _capabilities,_ which are labels representing specific pieces of functionality that can be exposed to other
+EndpointGroups that may meet functional requirements of those EndpointGroups.
+
+When acting as a _consumer_, EndpointGroups expose _requirements_, which are labels that represent that the EndpointGroup requires some specific piece of functionality.
+
+As an example, we might create a capability called "user-database" which indicates that an EndpointGroup contains endpoints that implement a database of users.
+
+We might create a requirement also called "user-database" to indicate an EndpointGroup contains endpoints that will need to communicate with the endpoints that expose this service.
+
+Note that in this example the requirement and capability have the same name, but the user need not follow this convention.
+
+The matching provider selector (that was used by the provider EndpointGroup to select the contract) is examined to determine the capabilities exposed by the provider EndpointGroup for this contract scope.
+
+The provider selector will have a list of capabilities either directly included in the provider selector or inherited from a parent selector or parent EndpointGroup. (See <<Inheritance,Inheritance>>).
+
+Similarly, the matching consumer selector will expose a set of requirements.
+
+===== Conditions
+
+Endpoints can have _conditions_, which are labels representing some relevant piece of operational state related to the endpoint.
+
+An example of a condition might be "malware-detected," or "authentication-succeeded." Conditions are used to affect how that particular endpoint can communicate.
+
+To continue with our example, the "malware-detected" condition might cause an endpoint's connectivity to be cut off, while "authentication-succeeded" might open up communication with services
+that require an endpoint to be first authenticated and then forward its authentication credentials.
+
+===== Clauses
+
+Clauses perform the actual selection of subjects.
+A clause has lists of matchers in two categories. In order for a clause to become active, all lists of matchers must match.
+A matching clause will select all the subjects referenced by the clause.
+Note that an empty list of matchers counts as a match.
+
+The first category is the consumer matchers, which match against the consumer EndpointGroup and endpoints. The consumer matchers are:
+
+* Group Idenfication Constraint: Requirement matchers
++
+Matches against requirements in the matching consumer selector.
+
+* Group Identification Constraint: GroupName
++
+Matches against the group name
+
+* Consumer condition matchers
++
+Matches against conditions on endpoints in the consumer EndpointGroup
+
+* Consumer Endpoint Identification Constraint
++
+Label based criteria for matching against endpoints. In Lithium this can be used to label endpoints based on IpPrefix.
+
+The second category is the provider matchers, which match against the provider EndpointGroup and endpoints. The provider matchers are:
+
+* Group Idenfication Constraint: Capability matchers
++
+Matches against capabilities in the matching provider selector.
+
+* Group Identification Constraint: GroupName
++
+Matches against the group name
+
+* Consumer condition matchers
++
+Matches against conditions on endpoints in the provider EndpointGroup
+
+* Consumer Endpoint Identification Constraint
++
+Label based criteria for matching against endpoints. In Lithium this can be used to label endpoints based on IpPrefix.
+
+Clauses have a list of subjects that apply when all the matchers in the clause match. The output of the subject selection phase logically is a set of subjects that are in scope for any particular pair of endpoints.
+
+===== Rule Application
+
+Now subjects have been selected that apply to the traffic between a particular set of endpoints, policy can be applied to allow endpoints to communicate.
+The applicable subjects from the previous step will each contain a set of rules.
+
+Rules consist of a set of _classifiers_ and a set of _actions_. Classifiers match against traffic between two endpoints.
+An example of a classifier would be something that matches against all TCP traffic on port 80, or one that matches against HTTP traffic containing a particular cookie.
+Actions are specific actions that need to be taken on the traffic before it reaches its destination.
+Actions could include tagging or encapsulating the traffic in some way, redirecting the traffic, or applying a <<SFC,service function chain>>.
+
+Rules, subjects, and actions have an _order_ parameter, where a lower order value means that a particular item will be applied first.
+All rules from a particular subject will be applied before the rules of any other subject, and all actions from a particular rule will be applied before the actions from another rule.
+If more than item has the same order parameter, ties are broken with a lexicographic ordering of their names, with earlier names having logically lower order.
+
+====== Matchers [[Matchers]]
+
+Matchers specify a set of labels (which include requirements, capabilities, conditions, and qualities) to match against.
+There are several kinds of matchers that operate similarly:
+
+* Quality matchers
++
+used in target selectors during the contract selection phase. Quality matchers provide a more advanced and flexible way to select contracts compared to a named selector.
+
+* Requirement and capability matchers
++
+used in clauses during the subject selection phase to match against requirements and capabilities on EndpointGroups
+
+* Condition matchers
++
+used in clauses during the subject selection phase to match against conditions on endpoints
+
+A matcher is, at its heart, fairly simple. It will contain a list of label names, along with a _match type_.
+The match type can be either:
+
+* "all"
++
+which means the matcher matches when all of its labels match
+
+* "any"
++
+which means the matcher matches when any of its labels match,
+* "none"
++
+which means the matcher matches when none of its labels match.
+
+Note a _match all_ matcher can be made by matching against an empty set of labels with a match type of "all."
+
+Additionally each label to match can optionally include a relevant name field. For quality matchers, this is a target name.
+For capability and requirement matchers, this is a selector name. If the name field is specified, then the matcher will only match against targets or selectors with that name, rather than any targets or selectors.
+
+===== Inheritance [[Inheritance]]
+
+Some objects in the system include references to parents, from which they will inherit definitions.
+The graph of parent references must be loop free. When resolving names, the resolution system must detect loops and raise an exception.
+Objects that are part of these loops may be considered as though they are not defined at all.
+Generally, inheritance works by simply importing the objects in the parent into the child object. When there are objects with the same name in the child object,
+then the child object will override the parent object according to rules which are specific to the type of object. We'll next explore the detailed rules for inheritance for each type of object
+
+*EndpointGroups*
+
+EndpointGroups will inherit all their selectors from their parent EndpointGroups. Selectors with the same names as selectors in the parent EndpointGroups will inherit their behavior as defined below.
+
+*Selectors*
+
+Selectors include provider named selectors, provider target selectors, consumer named selectors, and consumer target selectors. Selectors cannot themselves have parent selectors, but when selectors have the same name as a selector of the same type in the parent EndpointGroup, then they will inherit from and override the behavior of the selector in the parent EndpointGroup.
+
+*Named Selectors*
+
+Named selectors will add to the set of contract IDs that are selected by the parent named selector.
+
+*Target Selectors*
+
+A target selector in the child EndpointGroup with the same name as a target selector in the parent EndpointGroup will inherit quality matchers from the parent. If a quality matcher in the child has the same name as a quality matcher in the parent, then it will inherit as described below under Matchers.
+
+*Contracts*
+
+Contracts will inherit all their targets, clauses and subjects from their parent contracts. When any of these objects have the same name as in the parent contract, then the behavior will be as defined below.
+
+*Targets*
+
+Targets cannot themselves have a parent target, but it may inherit from targets with the same name as the target in a parent contract. Qualities in the target will be inherited from the parent. If a quality with the same name is defined in the child, then this does not have any semantic effect except if the quality has its inclusion-rule parameter set to "exclude." In this case, then the label should be ignored for the purpose of matching against this target.
+
+*Subjects*
+
+Subjects cannot themselves have a parent subject, but it may inherit from a subject with the same name as the subject in a parent contract.
+The order parameter in the child subject, if present, will override the order parameter in the parent subject.
+The rules in the parent subject will be added to the rules in the child subject. However, the rules will not override rules of the same name. Instead, all rules in the parent subject will be considered to run with a higher order than all rules in the child; that is all rules in the child will run before any rules in the parent. This has the effect of overriding any rules in the parent without the potentially-problematic semantics of merging the ordering.
+
+*Clauses*
+
+Clauses cannot themselves have a parent clause, but it may inherit from a clause with the same name as the clause in a parent contract.
+The list of subject references in the parent clause will be added to the list of subject references in the child clause. This is just a union operation.
+A subject reference that refers to a subject name in the parent contract might have that name overridden in the child contract.
+Each of the matchers in the clause are also inherited by the child clause.
+Matchers in the child of the same name and type as a matcher from the parent will inherit from and override the parent matcher. See below under Matchers for more information.
+
+*Matchers*
+
+Matchers include quality matchers, condition matchers, requirement matchers, and capability matchers.
+Matchers cannot themselves have parent matchers, but when there is a matcher of the same name and type in the parent object,
+then the matcher in the child object will inherit and override the behavior of the matcher in the parent object.
+The match type, if specified in the child, overrides the value specified in the parent.
+Labels are also inherited from the parent object. If there is a label with the same name in the child object, this does not have any semantic effect except if the label has its inclusion-rule parameter set to "exclude."
+In this case, then the label should be ignored for the purpose of matching. Otherwise, the label with the same name will completely override the label from the parent.
+
+=== Using the GBP UX interface [[UX]]
+
+include::odl-groupbasedpolicy-ui-user-guide.adoc[]
+
+=== Using the GBP API [[REST]]
+
+Please see:
+
+* <<OfOverlay,Using the GBP OpenFlow Overlay (OfOverlay) renderer>>
+* <<policyresolution, Policy Resolution>>
+* <<forwarding, Forwarding Model>>
+* <<demo, the *GBP* demo and development environments for tips>>
+
+It is recommended to use either:
+
+* <<Neutron, Neutron mapper>>
+* <<UX, the UX>>
+
+If the REST API must be used, and the above resources are not sufficient:
+
+* feature:install odl-mdsal-apidocs or odl-dlux-yangui
+* browse to: http://<odl-controller>:8181/apidoc/explorer/index.html
+
+to explore the various *GBP* REST options
+
+
+=== Using OpenStack with GBP [[Neutron]]
+
+
+include::odl-groupbasedpolicy-neutronmapper-user-guide.adoc[]
+
+
+=== Using the GBP OpenFlow Overlay (OfOverlay) renderer [[OfOverlay]]
+
+
+include::odl-groupbasedpolicy-ofoverlay-user-guide.adoc[]
+
+
+=== Using Service Function Chaining (SFC) with GBP [[SFC]]
+
+
+include::odl-groupbasedpolicy-sfc-user-guide.adoc[]
+
+
+=== Demo/Development environment[[demo]]
+
+The *GBP* project for Lithium has two demo/development environments.
+
+* Docker based GBP and GBP+SFC integration Vagrant environment
+* DevStack based GBP+Neutron integration Vagrant environment
+
+https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)/Consumability/Demo[Demo @ GBP wiki]