--- /dev/null
+== L3VPN Service: User Guide
+
+=== Overview
+L3VPN Service in Opendaylight provides a framework to create L3VPN based on BGP-MP. It also helps to create Network Virtualization for DC Cloud environment.
+
+=== Modules & Interfaces
+L3VPN service can be realized using the following modules -
+
+==== VPN Service Modules
+. *VPN Manager* : Creates and manages VPNs and VPN Interfaces
+. *BGP Manager* : Configures BGP routing stack and provides interface to routing services
+. *FIB Manager* : Provides interface to FIB, creates and manages forwarding rules in Dataplane
+. *Nexthop Manager* : Creates and manages nexthop egress pointer, creates egress rules in Dataplane
+. *Interface Manager* : Creates and manages different type of network interfaces, e.g., VLAN, l3tunnel etc.,
+. *Id Manager* : Provides cluster-wide unique ID for a given key. Used by different modules to get unique IDs for different entities.
+. *MD-SAL Util* : Provides interface to MD-SAL. Used by service modules to access MD-SAL Datastore and services.
+
+All the above modules can function independently and can be utilized by other services as well.
+
+==== Configuration Interfaces
+The following modules expose configuration interfaces through which user can configure L3VPN Service.
+
+. BGP Manager
+. VPN Manager
+. Interface Manager
+. FIB Manager
+
+===== Configuration Interface Details
+
+.BGP Manager Interface
+. Data Node Path : _/config/bgp:bgp-router/_
+.. Fields :
+... local-as-identifier
+... local-as-number
+.. REST Methods : GET, PUT, DELETE, POST
+. Data Node Path : _/config/bgp:bgp-neighbors/_
+.. Fields :
+... List of bgp-neighbor
+.. REST Methods : GET, PUT, DELETE, POST
+. Data Node Path : _/config/bgp:bgp-neighbors/bgp-neighbor/`{as-number}`/_
+.. Fields :
+... as-number
+... ip-address
+.. REST Methods : GET, PUT, DELETE, POST
+
+.VPN Manager Interface
+. Data Node Path : _/config/l3vpn:vpn-instances/_
+.. Fields :
+... List of vpn-instance
+.. REST Methods : GET, PUT, DELETE, POST
+. Data Node Path : _/config/l3vpn:vpn-interfaces/vpn-instance_
+.. Fields :
+... name
+... route-distinguisher
+... import-route-policy
+... export-route-policy
+.. REST Methods : GET, PUT, DELETE, POST
+. Data Node Path : _/config/l3vpn:vpn-interfaces/_
+.. Fields :
+... List of vpn-interface
+.. REST Methods : GET, PUT, DELETE, POST
+. Data Node Path : _/config/l3vpn:vpn-interfaces/vpn-interface_
+.. Fields :
+... name
+... vpn-instance-name
+.. REST Methods : GET, PUT, DELETE, POST
+. Data Node Path : _/config/l3vpn:vpn-interfaces/vpn-interface/`{name}`/adjacency_
+.. Fields :
+... ip-address
+... mac-address
+.. REST Methods : GET, PUT, DELETE, POST
+
+.Interface Manager Interface
+. Data Node Path : _/config/if:interfaces/interface_
+.. Fields :
+... name
+... type
+... enabled
+... of-port-id
+... tenant-id
+... base-interface
+.. type specific fields
+... when type = _l2vlan_
+.... vlan-id
+... when type = _stacked_vlan_
+.... stacked-vlan-id
+... when type = _l3tunnel_
+.... tunnel-type
+.... local-ip
+.... remote-ip
+.... gateway-ip
+... when type = _mpls_
+.... list labelStack
+.... num-labels
+.. REST Methods : GET, PUT, DELETE, POST
+
+.FIB Manager Interface
+. Data Node Path : _/config/odl-fib:fibEntries/vrfTables_
+.. Fields :
+... List of vrfTables
+.. REST Methods : GET, PUT, DELETE, POST
+. Data Node Path : _/config/odl-fib:fibEntries/vrfTables/`{routeDistinguisher}`/_
+.. Fields :
+... route-distinguisher
+... list vrfEntries
+.... destPrefix
+.... label
+.... nexthopAddress
+.. REST Methods : GET, PUT, DELETE, POST
+. Data Node Path : _/config/odl-fib:fibEntries/ipv4Table_
+.. Fields :
+... list ipv4Entry
+.... destPrefix
+.... nexthopAddress
+.. REST Methods : GET, PUT, DELETE, POST
+
+
+=== Provisioning Sequence & Sample Configurations
+
+[[install]]
+==== Installation
+1. Edit 'etc/custom.properties' and set the following property:
+'vpnservice.bgpspeaker.host.name = <bgpserver-ip>'
+'<bgpserver-ip>' here refers to the IP address of the host where BGP is running.
+
+2. Run ODL and install VPN Service
+'feature:install odl-vpnservice-core'
+
+Use REST interface to configure L3VPN service
+
+[[prer]]
+==== Pre-requisites:
+
+1. BGP stack with VRF support needs to installed and configured
+a. _Configure BGP as specified in Step 1 below._
+
+2. Create pairs of GRE/VxLAN Tunnels (using ovsdb/ovs-vsctl) between each switch and between each switch to the Gateway node
+a. _Create 'l3tunnel' interfaces corresponding to each tunnel in interfaces DS as specified in Step 2 below._
+
+==== Step 1 : Configure BGP
+
+===== 1. Configure BGP Router
+
+*REST API* : _PUT /config/bgp:bgp-router/_
+
+*Sample JSON Data*
+[source,json]
+-----------------
+{
+ "bgp-router": {
+ "local-as-identifier": "10.10.10.10",
+ "local-as-number": 108
+ }
+}
+-----------------
+
+
+===== 2. Configure BGP Neighbors
+
+*REST API* : _PUT /config/bgp:bgp-neighbors/_
+
+*Sample JSON Data*
+
+[source,json]
+-----------------
+ {
+ "bgp-neighbor" : [
+ {
+ "as-number": 105,
+ "ip-address": "169.144.42.168"
+ }
+ ]
+ }
+-----------------
+
+==== Step 2 : Create Tunnel Interfaces
+Create l3tunnel interfaces corresponding to all GRE/VxLAN tunnels created with ovsdb (<<prer, refer Prerequisites>>). Use following REST Interface -
+
+*REST API* : _PUT /config/if:interfaces/if:interfacce_
+
+*Sample JSON Data*
+
+[source,json]
+-----------------
+{
+ "interface": [
+ {
+ "name" : "GRE_192.168.57.101_192.168.57.102",
+ "type" : "odl-interface:l3tunnel",
+ "odl-interface:tunnel-type": "odl-interface:tunnel-type-gre",
+ "odl-interface:local-ip" : "192.168.57.101",
+ "odl-interface:remote-ip" : "192.168.57.102",
+ "odl-interface:portId" : "openflow:1:3",
+ "enabled" : "true"
+ }
+ ]
+}
+
+-----------------
+
+===== Following is expected as a result of these configurations
+
+1. Unique If-index is generated
+2. 'Interface-state' operational DS is updated
+3. Corresponding Nexthop Group Entry is created
+
+==== Step 3 : OS Create Neutron Ports and attach VMs
+
+At this step user creates VMs. <TBD>
+
+==== Step 4 : Create VM Interfaces
+Create l2vlan interfaces corresponding to VM created in step 3
+
+*REST API* : _PUT /config/if:interfaces/if:interface_
+
+*Sample JSON Data*
+
+[source,json]
+-----------------
+{
+ "interface": [
+ {
+ "name" : "dpn1-dp1.2",
+ "type" : "l2vlan",
+ "odl-interface:of-port-id" : "openflow:1:2",
+ "odl-interface:vlan-id" : "1",
+ "enabled" : "true"
+ }
+ ]
+}
+
+-----------------
+
+==== Step 5: Create VPN Instance
+
+*REST API* : _PUT /config/l3vpn:vpn-instances/l3vpn:vpn-instance/_
+
+*Sample JSON Data*
+
+[source,json]
+-----------------
+{
+ "vpn-instance": [
+ {
+ "description": "Test VPN Instance 1",
+ "vpn-instance-name": "testVpn1",
+ "ipv4-family": {
+ "route-distinguisher": "4000:1",
+ "export-route-policy": "4000:1,5000:1",
+ "import-route-policy": "4000:1,5000:1",
+ }
+ }
+ ]
+}
+
+-----------------
+
+===== Following is expected as a result of these configurations
+
+1. VPN ID is allocated and updated in data-store
+2. Corresponding VRF is created in BGP
+3. If there are vpn-interface configurations for this VPN, corresponding action is taken as defined in step 5
+
+==== Step 5 : Create VPN-Interface and Local Adjacency
+
+_this can be done in two steps as well_
+
+===== 1. Create vpn-interface
+
+*REST API* : _PUT /config/l3vpn:vpn-interfaces/l3vpn:vpn-interface/_
+
+*Sample JSON Data*
+
+[source,json]
+-----------------
+{
+ "vpn-interface": [
+ {
+ "vpn-instance-name": "testVpn1",
+ "name": "dpn1-dp1.2",
+ }
+ ]
+}
+-----------------
+
+[NOTE]
+name here is the name of VM interface created in step 3, 4
+
+===== 2. Add Adjacencies on vpn-interafce
+
+*REST API* : _PUT /config/l3vpn:vpn-interfaces/l3vpn:vpn-interface/dpn1-dp1.3/adjacency_
+
+*Sample JSON Data*
+
+[source,json]
+-----------------
+ {
+ "adjacency" : [
+ {
+ "ip-address" : "169.144.42.168",
+ "mac-address" : "11:22:33:44:55:66"
+ }
+ ]
+ }
+-----------------
+
+
+[quote]
+its a list, user can define more than one adjacency on a vpn_interface
+
+Above steps can be carried out in a single step as following
+
+[source,json]
+-----------------
+{
+ "vpn-interface": [
+ {
+ "vpn-instance-name": "testVpn1",
+ "name": "dpn1-dp1.3",
+ "odl-l3vpn:adjacency": [
+ {
+ "odl-l3vpn:mac_address": "11:22:33:44:55:66",
+ "odl-l3vpn:ip_address": "11.11.11.2",
+ }
+ ]
+ }
+ ]
+}
+
+-----------------
+
+
+===== Following is expected as a result of these configurations
+
+1. Prefix label is generated and stored in DS
+2. Ingress table is programmed with flow corresponding to interface
+3. Local Egress Group is created
+4. Prefix is added to BGP for advertisement
+5. BGP pushes route update to FIB YANG Interface
+6. FIB Entry flow is added to FIB Table in OF pipeline
Code Review / docs.git / commitdiff