<commit_before>BaGPipe BGP
===========

.. image:: https://badges.gitter.im/Join%20Chat.svg
    :target: https://gitter.im/Orange-OpenSource/bagpipe-bgp
    :alt: Join Glitter Chat

BaGPipe BGP is a lightweight implementation of BGP VPNs (IP VPNs and
E-VPNs), targeting deployments on servers hosting VMs, in particular for
Openstack/KVM platforms.

The goal is *not* to fully implement BGP specifications, but only the
subset of specifications required to implement IP VPN VRFs and E-VPN
EVIs (`RFC4364 <http://tools.ietf.org/html/rfc4364>`__ a.k.a RFC2547bis,
`RFC7432 <http://tools.ietf.org/html/rfc7432>`__/`draft-ietf-bess-evpn-overlay <http://tools.ietf.org/html/draft-ietf-bess-evpn-overlay>`__,
and `RFC4684 <http://tools.ietf.org/html/RFC4684>`__).

BaGPipe BGP is designed to use encapsulations over IP (such as
MPLS-over-GRE or VXLAN), and thus does not require the use of LDP. Bare
MPLS over Ethernet is also supported and can be used if servers/routers
have direct Ethernet connectivity.

Typical Use
-----------

BaGPipe-BGP has been designed to provide VPN (IP VPN or E-VPN)
connectivity to VMs running on a local server.

The target is to provide VPN connectivity to VMs deployed by Openstack.
A typical target architecture is to have BaGPipe-BGP be driven by
Openstack Neutron components:

*  the `bagpipe driver for the BGP VPN interconnection service
   plugin <https://github.com/openstack/networking-bgpvpn>`__
*  the `bagpipe ML2 mechanism
   driver <https://github.com/openstack/networking-bagpipe>`__ using E-VPN

BaGPipe-BGP can also be used standalone (e.g. for testing purposes),
with for instance VMs tap interfaces or veth interfaces to network
namespaces (see `below <#netns-example>`__).

Installation
------------

Installation can be done with ``python setup.py install``.

Running ``install.sh`` will take care of this and will *also* install
startup scripts in ``/etc/init.d`` and sample config files in
``/etc/bagpipe-bgp``.

BGP and Route Reflection
------------------------

If you only want to test how to interconnect one server running
bagpipe-bgp and an IP/MPLS router, you don't need to setup a BGP Route
Reflector. But to use BaGPipe BGP on more than one server, the current
code currently requires setting up a BGP Route Reflector (see
`Caveats <#caveats>`__).

The term "BGP Route Reflector" refers to a BGP implementation that
redistribute routes between iBGP peers
`RFC4456 <http://tools.ietf.org/html/RFC4456>`__.

When using bagpipe-bgp on more than one server, we thus need each
instance of BaGPipe BGP to be configured to peer with at least one route
reflector (see `Configuration <#config>`__).

We provide a tool that can be used to emulate a route reflector to
interconnect **2** BaGPipe BGP implementations, typically for test
purposes (see `Fake RR <#fakerr>`__).

For more than 2 servers running BaGPipe BGP, you will need a real BGP
implementation supporting RFC4364 and BGP route reflection (and ideally
also RFC4684).

Different options can be considered:

*  A router from for instance, Alcatel-Lucent, Cisco or Juniper can be
   used; some of these vendors also provide their OSes as virtual
   machines

*  BGP implementations in other opensource projects would possibly be
   suitable, but we did not explore these exhaustively:

   -  `GoBGP <http://osrg.github.io/gobgp/>`__ team has sucessfully
      deployed a setup with `GoBGP as a RR for bagpipe-bgp PE
      implementations, with
      E-VPN <https://github.com/osrg/gobgp/blob/master/docs/sources/evpn.md>`__

   -  we have sucessfully used OpenBSD BGPd as an IP VPN RR for
      bagpipe-bgp

   -  Quagga is supposed to support IP VPNs (untested AFAIK)

   -  there has been some work to allow the use of OpenContrail's BGP
      implementation as a Route Reflector; although this is currently
      unfinished, we have done rough hacks to confirm the feasibility
      and the interoperability

Configuration
-------------

The bagpipe-bgp daemon config file default location is:
``/etc/bagpipe-bgp/bgp.conf``.

The ``install.sh`` script will install a template as an example
configuration.

It needs to be customized, at least for the following:

*  ``local\_address``: the local address to use for BGP sessions and traffic
   encapsulation
*  ``peers``: the list of BGP peers, it depends on the BGP setup that you
   have chosen (see above `BGP Route Reflection <#bgprr>`__)
*  dataplane configuration, if you really want packets to get through
   (see `Dataplane configuration <#dpconfig>`__)

Example with two servers and relying on bagpipe fake route reflector:

*  On server A (local\_address=10.0.0.1):

   -  run bagpipe-fakerr

   -  run bagpipe-bgp with peers=127.0.0.1 (server A will thus connect to the locally running fake route-reflector)

*  On server B (local\_address=10.0.0.2):

   -  run bagpipe-bgp with peers=10.0.0.1

Dataplane driver configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Note well that the dataplane drivers proposed in the sample config file
are *dummy* drivers that will **not** actually drive any dataplane
state. To have traffic really forwarded into IP VPNs or E-VPNs, you need
to select real dataplane drivers.

For instance, you can use the ``ovs`` driver for IP VPN, and the ``linux``
driver for E-VPN.

**Note well** that there are specific constraints or dependencies applying to
dataplane drivers for IP VPNs:

*  the ``ovs`` driver can be used on most recent Linux kernels,
   but requires an OpenVSwitch with suitable MPLS code (OVS 2.4 to 2.6 was
   tested); this driver can do bare-MPLS or MPLS-over-GRE (but see
   `Caveats <#caveats>`__ for MPLS-over-GRE); for bare MPLS, this driver
   requires the OVS bridge to be associated with an IP address, and that
   VRF interfaces be plugged into OVS prior to calling BaGPipe BGP API
   to attach them (details in
   `mpls\_ovs\_dataplane.py <bagpipe/bgp/vpn/ipvpn/mpls_ovs_dataplane.py#L578>`__)

* the ``linux`` driver relies on the native MPLS stack of the Linux kernel,
  it currenly requires a kernel 4.4+ and uses the pyroute2 module that allows
  defining all states via Netlink rather than by executing 'ip' commands
  (details in [mpls\_linux\_dataplane.py](bagpipe/bgp/vpn/ipvpn/mpls_linux_dataplane.py#L354))

For E-VPN, the ``vxlan`` driver is supported without any particular additional
configuration being required, and simply requires a Linux kernel >=3.10
(`linux\_vxlan.py <bagpipe/bgp/vpn/evpn/linux_vxlan.py#L269>`__).
<commit_msg>fix rst formating nit in README.rst<commit_after>BaGPipe BGP
===========

.. image:: https://badges.gitter.im/Join%20Chat.svg
    :target: https://gitter.im/Orange-OpenSource/bagpipe-bgp
    :alt: Join Glitter Chat

BaGPipe BGP is a lightweight implementation of BGP VPNs (IP VPNs and
E-VPNs), targeting deployments on servers hosting VMs, in particular for
Openstack/KVM platforms.

The goal is *not* to fully implement BGP specifications, but only the
subset of specifications required to implement IP VPN VRFs and E-VPN
EVIs (`RFC4364 <http://tools.ietf.org/html/rfc4364>`__ a.k.a RFC2547bis,
`RFC7432 <http://tools.ietf.org/html/rfc7432>`__/`draft-ietf-bess-evpn-overlay <http://tools.ietf.org/html/draft-ietf-bess-evpn-overlay>`__,
and `RFC4684 <http://tools.ietf.org/html/RFC4684>`__).

BaGPipe BGP is designed to use encapsulations over IP (such as
MPLS-over-GRE or VXLAN), and thus does not require the use of LDP. Bare
MPLS over Ethernet is also supported and can be used if servers/routers
have direct Ethernet connectivity.

Typical Use
-----------

BaGPipe-BGP has been designed to provide VPN (IP VPN or E-VPN)
connectivity to VMs running on a local server.

The target is to provide VPN connectivity to VMs deployed by Openstack.
A typical target architecture is to have BaGPipe-BGP be driven by
Openstack Neutron components:

*  the `bagpipe driver for the BGP VPN interconnection service
   plugin <https://github.com/openstack/networking-bgpvpn>`__
*  the `bagpipe ML2 mechanism
   driver <https://github.com/openstack/networking-bagpipe>`__ using E-VPN

BaGPipe-BGP can also be used standalone (e.g. for testing purposes),
with for instance VMs tap interfaces or veth interfaces to network
namespaces (see `below <#netns-example>`__).

Installation
------------

Installation can be done with ``python setup.py install``.

Running ``install.sh`` will take care of this and will *also* install
startup scripts in ``/etc/init.d`` and sample config files in
``/etc/bagpipe-bgp``.

BGP and Route Reflection
------------------------

If you only want to test how to interconnect one server running
bagpipe-bgp and an IP/MPLS router, you don't need to setup a BGP Route
Reflector. But to use BaGPipe BGP on more than one server, the current
code currently requires setting up a BGP Route Reflector (see
`Caveats <#caveats>`__).

The term "BGP Route Reflector" refers to a BGP implementation that
redistribute routes between iBGP peers
`RFC4456 <http://tools.ietf.org/html/RFC4456>`__.

When using bagpipe-bgp on more than one server, we thus need each
instance of BaGPipe BGP to be configured to peer with at least one route
reflector (see `Configuration <#config>`__).

We provide a tool that can be used to emulate a route reflector to
interconnect **2** BaGPipe BGP implementations, typically for test
purposes (see `Fake RR <#fakerr>`__).

For more than 2 servers running BaGPipe BGP, you will need a real BGP
implementation supporting RFC4364 and BGP route reflection (and ideally
also RFC4684).

Different options can be considered:

*  A router from for instance, Alcatel-Lucent, Cisco or Juniper can be
   used; some of these vendors also provide their OSes as virtual
   machines

*  BGP implementations in other opensource projects would possibly be
   suitable, but we did not explore these exhaustively:

   -  `GoBGP <http://osrg.github.io/gobgp/>`__ team has sucessfully
      deployed a setup with `GoBGP as a RR for bagpipe-bgp PE
      implementations, with
      E-VPN <https://github.com/osrg/gobgp/blob/master/docs/sources/evpn.md>`__

   -  we have sucessfully used OpenBSD BGPd as an IP VPN RR for
      bagpipe-bgp

   -  Quagga is supposed to support IP VPNs (untested AFAIK)

   -  there has been some work to allow the use of OpenContrail's BGP
      implementation as a Route Reflector; although this is currently
      unfinished, we have done rough hacks to confirm the feasibility
      and the interoperability

Configuration
-------------

The bagpipe-bgp daemon config file default location is:
``/etc/bagpipe-bgp/bgp.conf``.

The ``install.sh`` script will install a template as an example
configuration.

It needs to be customized, at least for the following:

*  ``local\_address``: the local address to use for BGP sessions and traffic
   encapsulation
*  ``peers``: the list of BGP peers, it depends on the BGP setup that you
   have chosen (see above `BGP Route Reflection <#bgprr>`__)
*  dataplane configuration, if you really want packets to get through
   (see `Dataplane configuration <#dpconfig>`__)

Example with two servers and relying on bagpipe fake route reflector:

*  On server A (local\_address=10.0.0.1):

   -  run bagpipe-fakerr

   -  run bagpipe-bgp with peers=127.0.0.1 (server A will thus connect to the locally running fake route-reflector)

*  On server B (local\_address=10.0.0.2):

   -  run bagpipe-bgp with peers=10.0.0.1

Dataplane driver configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Note well that the dataplane drivers proposed in the sample config file
are *dummy* drivers that will **not** actually drive any dataplane
state. To have traffic really forwarded into IP VPNs or E-VPNs, you need
to select real dataplane drivers.

For instance, you can use the ``ovs`` driver for IP VPN, and the ``linux``
driver for E-VPN.

**Note well** that there are specific constraints or dependencies applying to
dataplane drivers for IP VPNs:

*  the ``ovs`` driver can be used on most recent Linux kernels,
   but requires an OpenVSwitch with suitable MPLS code (OVS 2.4 to 2.6 was
   tested); this driver can do bare-MPLS or MPLS-over-GRE (but see
   `Caveats <#caveats>`__ for MPLS-over-GRE); for bare MPLS, this driver
   requires the OVS bridge to be associated with an IP address, and that
   VRF interfaces be plugged into OVS prior to calling BaGPipe BGP API
   to attach them (details in
   `mpls\_ovs\_dataplane.py <bagpipe/bgp/vpn/ipvpn/mpls_ovs_dataplane.py#L578>`__)

* the ``linux`` driver relies on the native MPLS stack of the Linux kernel,
  it currenly requires a kernel 4.4+ and uses the pyroute2 module that allows
  defining all states via Netlink rather than by executing 'ip' commands
  (details in `mpls\_linux\_dataplane.py <bagpipe/bgp/vpn/ipvpn/mpls_linux_dataplane.py#L354>`__)

For E-VPN, the ``vxlan`` driver is supported without any particular additional
configuration being required, and simply requires a Linux kernel >=3.10
(`linux\_vxlan.py <bagpipe/bgp/vpn/evpn/linux_vxlan.py#L269>`__).

{'fraction_non_alphanumeric': 0.09125973925788783, 'fraction_numerical': 0.013731389338887604, 'mean_word_length': 3.944317315026697, 'pattern_counts': {'":': 0, '<': 40, '<?xml version=': 0, '>': 42, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6215854', 'n_tokens_mistral': 4214, 'n_tokens_neox': 3931, 'n_words': 1680}