Skip to content

Commit 2ba3ed2

Browse files
davischwdavischw
committed
readme: changed readme file to refer to FRR dev guide for information
Signed-off-by: David Schweizer <dschweizer@opensourcerouting.org>
1 parent aeb86d7 commit 2ba3ed2

File tree

1 file changed

+16
-259
lines changed

1 file changed

+16
-259
lines changed

‎README.md‎

Lines changed: 16 additions & 259 deletions
Original file line numberDiff line numberDiff line change
@@ -1,265 +1,22 @@
1-
[![License](https://img.shields.io/pypi/l/exabgp.svg)](https://github.com/Exa-Networks/exabgp/blob/master/LICENCE.txt)
2-
[![PyPI](https://img.shields.io/pypi/v/exabgp.svg)](https://pypi.python.org/pypi/exabgp)
3-
[![PyPI Status](https://img.shields.io/pypi/status/exabgp.svg)](https://pypi.python.org/pypi/exabgp)
4-
[![PyPI Wheel](https://img.shields.io/pypi/wheel/exabgp.svg)](https://pypi.python.org/pypi/exabgp)
1+
## OpenSourceRouting.org fork of fixed ExaBGP for FRRouting topotests
52

6-
## Introduction
3+
This is a fork of ExaBGP 4.2.11 with a few fixes for compatibility with the
4+
FRRouting topology tests.
75

8-
[ExaBGP](https://github.com/Exa-Networks/exabgp) provides a convenient way to implement [Software Defined Networking](https://en.wikipedia.org/wiki/Software-defined_networking) by transforming [BGP messages](http://thomas.mangin.com/data/pdf/UKNOF%2015%20-%20Mangin%20-%20Naked%20BGP.pdf) into friendly plain [text or JSON](https://github.com/Exa-Networks/exabgp/wiki/Controlling-ExaBGP-:-API-for-received-messages), which can then be easily handled by simple scripts or your BSS/OSS.
6+
Please refer to the [FRRouting Developer's Guide](http://docs.frrouting.org/projects/dev-guide/en/latest/topotests.html) for information about FRRouting topology tests.
97

10-
It is routinely used to improve service resilience and provide protection against network or service failures. For example, thanks to the `healthcheck` backend included, anycasted DNS service failures can be detected and handled [gracefully](http://blog.iweb-hosting.co.uk/blog/2012/01/27/using-bgp-to-serve-high-availability-dns/). To help you get started, [Vincent Bernat](https://github.com/vincentbernat) put forward a full lab [explaining](https://vincent.bernat.ch/en/blog/2013-exabgp-highavailability) how to best use this feature.
11-
12-
Also, [alone](http://perso.nautile.fr/prez/fgabut-flowspec-frnog-final.pdf) or in conjunction with [FastNetMon](https://github.com/pavel-odintsov/fastnetmon) or [WanGuard](https://www.andrisoft.com/software/wanguard), it provides network operators a cost effective DDOS protection solution.
13-
14-
Thanks to modern routers' flow balancing, ExaBGP can also be used to save you money on [load balancers](https://vincent.bernat.ch/en/blog/2018-multi-tier-loadbalancer).
15-
16-
Other uses include keeping an eye on network changes done by [RIPE](https://labs.ripe.net/Members/wouter_miltenburg/researching-next-generation-ris-route-collectors) or by other networks with [GIXLG](https://github.com/dpiekacz/gixlg/wiki/GIXLG-wiki).
17-
18-
## Who is using ExaBGP ?
19-
20-
Some users have documented their use cases, such as [DailyMotion](https://medium.com/dailymotion/how-we-built-our-hybrid-kubernetes-platform-d121ea9cb0bc) or [Facebook](https://code.fb.com/data-infrastructure/dhcplb-server/).
21-
22-
These organisations have spoken of, or are using/have used ExaBGP:
23-
[AMS-IX](https://ripe64.ripe.net/presentations/49-Follow_Up_AMS-IX_route-server_test_Euro-IX_20th_RIPE64.pdf),
24-
[Alcatel Lucent](https://www.nanog.org/sites/default/files/wed.general.trafficdiversion.serodio.10.pdf),
25-
[BBC](http://www.bbc.co.uk/blogs/internet/entries/8c6c2414-df7a-4ad7-bd2e-dbeda3633),
26-
[Blablacar](http://previous.blablatech.com/blog/bgp-routing-to-containers),
27-
[Cisco Systems](http://www.ciscoknowledgenetwork.com/files/452_06-11-14-20140610_v3_BGP_Optimizing_the_SDN-v1-0.pdf?),
28-
[Cloudflare](https://www.slideshare.net/TomPaseka/flowspec-apf-2013),
29-
[Dailymotion](https://github.com/pyke369/exabgp-helpers),
30-
[Facebook](https://code.facebook.com/posts/1734.0.826831603/dhcplb-an-open-source-load-balancer/),
31-
[MaxCDN](https://blog.maxcdn.com/anycast-ip-routing-used-maxcdn/),
32-
[Microsoft](https://www.nanog.org/sites/default/files/wed.general.brainslug.lapukhov.20.pdf),
33-
[OpenDNS](https://blog.opendns.com/2013/01/10/high-availability-with-anycast-routing/),
34-
[Oracle](https://dyn.com/blog/how-oracle-dyn-leveraged-open-standards-and-chatbots-to-better-respond-to-attacks/#close),
35-
[PowerDNS](https://blog.powerdns.com/2016/02/23/an-important-update-on-new-powerdns-products/),
36-
[RIPE NCC](https://labs.ripe.net/Members/wouter_miltenburg/Researchpaper.pdf), ...
37-
38-
Therefore so should [`YOU`](https://en.wikipedia.org/wiki/Bandwagon_effect)! :grin:
39-
40-
## Installation
41-
42-
The program is packaged for Debian, Ubuntu, ArchLinux, Gentoo, Mint, FreeBSD, OSX and OmniOS (and probably more).
43-
44-
The latest version is available on [`pypi`](https://pypi.python.org/pypi), the Python Package Index
45-
46-
```sh
47-
> pip install exabgp
48-
49-
> exabgp --version
50-
> exabgp --help
51-
52-
> exabgp --run healthcheck --help
53-
> python -m exabgp healthcheck --help
54-
```
55-
56-
It is also possible to download the latest archive from github
57-
58-
```sh
59-
> curl -L https://github.com/Exa-Networks/exabgp/archive/4.2.11.tar.gz | tar zx
60-
61-
> cd exabgp-4.2.11
62-
> ./sbin/exabgp --version
63-
> ./sbin/exabgp --help
64-
65-
> ./sbin/exabgp --run healthcheck --help
66-
> env PYTHONPATH=./lib python -m exabgp healthcheck --help
67-
> ./bin/healthcheck --help
68-
```
69-
70-
or to use git master
71-
72-
```sh
73-
> git clone https://github.com/Exa-Networks/exabgp exabgp-git
74-
75-
> cd exabgp-git
76-
> ./sbin/exabgp --version
77-
> ./sbin/exabgp --help
78-
79-
> ./sbin/exabgp --run healthcheck --help
80-
> env PYTHONPATH=./lib python -m exabgp healthcheck --help
81-
> ./bin/healthcheck --help
82-
```
83-
84-
or change git to use any previous release (here 4.2.11)
85-
86-
```sh
87-
> git checkout 4.2.11
88-
> ./sbin/exabgp --version
89-
```
90-
91-
once you have the code, it is possible to create a self-contained executable which only requires an install python3 interpreter
92-
93-
```
94-
> cd exabgp-git
95-
> python3 -m zipapp -o /usr/local/sbin/exabgp -m exabgp.application:main -p "/usr/bin/env python3" lib
96-
> /usr/local/sbin/exabgp --version
97-
```
98-
99-
Multiple versions can be used simultaneously without conflict when ExaBGP is ran from extracted archives and/or local git repositories.
100-
101-
ExaBGP 3.4 and previous versions are python2 applications. ExaBGP 4.0 had support for both Python2 and 3. ExaBGP and later are targeting python3 only.
102-
103-
## Upgrade
104-
105-
ExaBGP is self-contained and easy to upgrade/downgrade by:
106-
107-
* replacing the downloaded release folder, for releases download
108-
* running `git pull` in the repository folder, for installtion using git master
109-
* running `pip install -U exabgp`, for pip installations
110-
* running `apt update; apt upgrade exabgp` for Debian/Ubuntu
111-
112-
*If you are migrating your application from ExaBGP 3.4 to 4.x please read this [wiki](https://github.com/Exa-Networks/exabgp/wiki/Migration-from-3.4-to-4.0) entry*.
113-
114-
The configuration file and API format may change from time to time, but every effort is made to make sure backward compatibility is kept. However users are encouraged to read the [release note/CHANGELOG](https://raw.github.com/Exa-Networks/exabgp/master/CHANGELOG) and check their setup after upgrade.
115-
116-
## Support
117-
118-
<!--
119-
[![Landscape Code Quality](https://landscape.io/github/Exa-Networks/exabgp/master/landscape.svg)](https://landscape.io/github/Exa-Networks/exabgp/)
120-
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/Exa-Networks/exabgp/badges/quality-score.png)](https://scrutinizer-ci.com/g/Exa-Networks/exabgp/)
121-
[![Coverage Status](https://img.shields.io/coveralls/Exa-Networks/exabgp.svg)](https://coveralls.io/r/Exa-Networks/exabgp)
122-
[![Throughput Graph](https://graphs.waffle.io/Exa-Networks/exabgp/throughput.svg)](https://waffle.io/Exa-Networks/exabgp/metrics/throughput)
123-
124-
[![Testing Status](https://travis-ci.org/Exa-Networks/exabgp.svg)](https://travis-ci.org/Exa-Networks/exabgp)
125-
[![Testing Status](https://img.shields.io/codeship/d6c1ddd0-16a3-0132-5f85-2e35c05e22b1.svg)]()
126-
[![Codacy Rating](https://www.codacy.com/project/badge/1f5fedb98bfd47bcb9ab868ea53ea210)](https://www.codacy.com/public/thomasmangin/exabgp_2)
127-
[![Coverage Status](https://img.shields.io/scrutinizer/coverage/g/exa-networks/exabgp.svg)](https://coveralls.io/r/Exa-Networks/exabgp)
128-
-->
129-
130-
ExaBGP is supported through Github's [issue tracker](https://github.com/Exa-Networks/exabgp/issues). So should you encounter any problems, please do not hesitate to [report it](https://github.com/Exa-Networks/exabgp/issues?labels=bug&page=1&state=open) so we can help you.
131-
132-
During "day time" (GMT/BST) feel free to contact us on [`Slack`](https://join.slack.com/t/exabgp/shared_invite/enQtNTM3MTU5NTg5NTcyLTMwNmZlMGMyNTQyNWY3Y2RjYmQxODgyYzY2MGFkZmYwODMxNDZkZjc4YmMyM2QzNzA1YWM0MmZjODhlYThjNTQ), we are phasing out our use of [`Gitter`](https://gitter.im/Exa-Networks/exabgp); we will try to respond if available. ExaBGP also has a channel on `Freenode` [`#exabgp`](irc://irc.freenode.net:6667/exabgp) but it is not monitored.
133-
134-
The best way to be kept informed about our progress/releases is to follow us on [Twitter](https://twitter.com/#!/search/exabgp). You can also use and subscribe to our low volume [mailing list](https://groups.google.com/group/exabgp-users).
135-
136-
## Documentation
137-
138-
The documentation is known to be imperfect. One could even say wanting, limited, insufficient and lacking, therefore any contribution (however small) toward its improvement is truly welcomed.
139-
140-
Other users did however do a fair bit of [`documentation`](https://github.com/Exa-Networks/exabgp/wiki/Related-articles), just not on the [`wiki`](https://github.com/Exa-Networks/exabgp/wiki). :cry:
141-
142-
To understand how ExaBGP should be configured, please have a look into the [`etc/exabgp`](https://github.com/Exa-Networks/exabgp/tree/master/etc/exabgp) folder of the repository where a great many examples are available.
143-
144-
`exabgp --help` is also a treasure trove of information.
145-
146-
## Related Projects
147-
148-
The following projects are related to ExaBGP
149-
150-
**BGP playgrounds**
151-
- [Large Communities](https://github.com/pierky/bgp-large-communities-playground) A docker-based lab to play with BGP Large Communities
152-
- [High availability](https://vincent.bernat.ch/en/blog/2013-exabgp-highavailability) provide redundant services
153-
- [VXLAN](https://vincent.bernat.ch/en/blog/2017-vxlan-bgp-evpn)
154-
- [L3 routing to the hypervisor](https://vincent.bernat.ch/en/blog/2018-l3-routing-hypervisor)
155-
- [BGP LLGR](https://vincent.bernat.ch/en/blog/2018-bgp-llgr) BGP long lived graceful restart
156-
- [ExaBGP Monitor](https://github.com/slowr/ExaBGP-Monitor) Connect ExaBGP with [socket.io](https://socket.io/)
157-
158-
159-
**Network Protection**
160-
- [WanGuard](https://www.andrisoft.com/software/wanguard) DDOS protection from Andrisoft
161-
- [FastNetMon](https://github.com/pavel-odintsov/fastnetmon) a DDOS protection solution
162-
- [exabgp edgerouter](https://github.com/infowolfe/exabgp-edgerouter) Spamhaus and Emerging Threats blocking with Ubiquiti EdgeRouters
163-
- [exabgp-voipbl](https://github.com/GeertHauwaerts/exabgp-voipbl) advertises local or/and voipbl.org blacklist using unicast or flow route.
164-
165-
**Network Monitoring**
166-
- [ARTEMIS](https://github.com/FORTH-ICS-INSPIRE/artemis) Real-Time Detection and Automatic Mitigation for BGP Prefix Hijacking.
167-
- [GIXLG](https://github.com/dpiekacz/gixlg) a looking glass with visualisation
168-
- [lookify](https://github.com/marc-barry/lookify) another looking glass
169-
- [invalidroutesreporter](https://github.com/pierky/invalidroutesreporter) report/log invalid routes received by route servers
170-
171-
**Route Announcement**
172-
- [ERCO](https://erco.xyz/) web interface
173-
- [ExaBGPmon](https://github.com/thepacketgeek/ExaBGPmon) web interface
174-
- [ExaBGPmon Vagrant](https://github.com/DDecoene/ExaBGPmon) Fork of ExaBGPmon with a vagrantfile and install script.
175-
- [BGPAPI](https://github.com/abh/bgpapi) an HTTP API
176-
- [BGP commander](https://github.com/crazed/bgpcommander) Integration with etcd
177-
- [exabgp-healthcheck](https://github.com/sysadminblog/exabgp-healthcheck) a perl based healthcheck program
178-
- [exabgpctl](https://github.com/ahmet2mir/exabgpctl) control exabgp and get information in json,yaml and flat format
179-
180-
**Installation**
181-
- [Ansible](https://github.com/sfromm/ansible-exabgp) Playbook
182-
- [Chef](https://github.com/hw-cookbooks/exabgp) Cookbook
183-
184-
**Interoperability**
185-
- [IOS2ExaBGP](https://github.com/lochiiconnectivity/ios2exa) converts Cisco IOS IPv4 BGP LOC Rib dumps to ExaBGP's format
186-
- [MRTparse](https://github.com/YoshiyukiYamauchi/mrtparse) convert MRT format to ExaBGP
187-
188-
**High availability**
189-
- [ExaZK](https://github.com/shtouff/exazk) a plugin to interface ExaBGP & ZooKeeper
190-
- [exazk](https://github.com/ton31337/exazk) a ruby solution to interface ExaBGP & ZooKeeper to achieve service HA
191-
- [exabgp-healthcheck](https://github.com/shthead/exabgp-healthcheck) A third party healthcheck program in Perl
192-
- [exa-template](https://github.com/ton31337/exa-template) service discovery by BGP communities. more information on this [blog](http://blog.donatas.net/blog/2017/03/02/exa-template/)
193-
194-
**Performance**
195-
- [bgperf](https://github.com/osrg/bgperf) Stress test solution for Bird and Quagga (can be used with other implementations)
196-
- [super smash brogp](https://github.com/spotify/super-smash-brogp) Stress test BGP
197-
- [kyro](https://github.com/kvogt/kyro) realtime network performance measurement and optimal routes injection - not really ExaBGP related, they have their own stack, but worth mentioning
198-
- [kakapo](https://github.com/hdb3/kakapo) a BGP flooding tool
199-
200-
**FIB**
201-
- [IOS-XR Solenoid](https://github.com/ios-xr/Solenoid) a FIB for ExaBGP
202-
203-
**Other BGP implementation**
204-
- [Full list](https://github.com/Exa-Networks/exabgp/wiki/Other-OSS-BGP-implementations) of known open source BGP implementation
205-
- [Bird](http://bird.network.cz/) very good C based BGP implementation with powerful route filtering language for network administrators
206-
- [GoBGP](https://github.com/osrg/gobgp) an implementation with various binding for programmers
207-
- [RYU](https://github.com/osrg/ryu) for SDN fans
208-
209-
## Features
210-
211-
RFC support includes ASN4, IPv6, MPLS, VPLS, Flow, Graceful Restart, Enhanced Route Refresh, Extended Next-Hop, "BGP-LS" and AIGP among others.
212-
More information can be found [here](https://github.com/Exa-Networks/exabgp/wiki/RFC-Information)
213-
214-
ExaBGP does **not** perform any FIB manipulation. If this is what you need, you may consider another open source BGP daemon such as [BIRD](http://bird.network.cz/) or [Quagga](http://www.quagga.net/).
215-
216-
[RFC compliance](https://github.com/Exa-Networks/exabgp/wiki/RFC-Information) details the latest developments.
217-
218-
## Development
219-
220-
### Debug environment variable
221-
222-
The following "unsupported" options are available to help with development:
223-
```
224-
exabgp.debug.configuration to trace with pdb configuration parsing errors
225-
exabgp.debug.pdb enable python debugger on runtime errors (be ready to use `killall python` to handle orphaned child processes)
226-
exabgp.debug.route similar to --decode but using the environment
227-
exabgp.debug.selfcheck does a self check on the configuration file (used by the QA code)
8+
### Installation
9+
This modified release of ExaBGP 4.2.11 can be directly installed on most
10+
GNU/Linux distributions from this repository with the
11+
[Package Installer for Python 3](https://github.com/pypa/pip) by running the
12+
following commands with superuser privileges:
22813
```
229-
230-
### Test suite
231-
232-
If you want to check any code changes, the repository comes with a `qa` folder, which includes many way to check code integrity.
233-
234-
ExaBGP comes with a set of functional tests, each test starts an IBGP deamon expecting a number of per recorded UDPATEs for the matching configuration file.
235-
236-
You can see all the existing tests running `./qa/bin/functional listing`. Each test is numbered and can be run independently (please note that 03 is not the same as 3).
237-
238-
```sh
239-
# ./qa/bin/functional run # (run all the test)
240-
# ./qa/bin/functional run 03 # (run test 03 as reported by listing)
14+
useradd -d /var/run/exabgp/ -s /bin/false exabgp
15+
python3 -m pip install git+https://github.com/opensourcerouting/exabgp@4.2.11-frr
24116
```
24217

243-
You can also manually run both the server and client for any given test:
244-
245-
```sh
246-
shell1# ./qa/bin/functional server 03
247-
shell2# ./qa/bin/functional client 03
248-
```
249-
250-
A test suite is also present to complement the functional testing.
251-
252-
```sh
253-
# env exabgp_log_enable=false nosetests --with-coverage ./qa/tests/*_test.py
254-
```
255-
256-
(nosetest requires nose `pip install nose` or `pip3 install nose`)
257-
258-
You can decode UPDATE messages using ExaBGP `--decode` argument.
259-
260-
```sh
261-
# env exabgp_tcp_bind='' ./sbin/exabgp ./etc/exabgp/api-open.conf --decode FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF:003C:02:0000001C4001010040020040030465016501800404000000C840050400000064000000002001010101
262-
```
263-
```json
264-
21:24:59 | 37750 | parser | update json { "exabgp": "4.0.1", "time": 1560371099.404008, "host" : "ptr-41.212.219.82.rev.exa.net.uk", "pid" : 37750, "ppid" : 10834, "counter": 1, "type": "update", "neighbor": { "address": { "local": "127.0.0.1", "peer": "127.0.0.1" }, "asn": { "local": 1, "peer": 1 } , "direction": "in", "message": { "update": { "attribute": { "origin": "igp", "med": 200, "local-preference": 100 }, "announce": { "ipv4 unicast": { "101.1.101.1": [ { "nlri": "1.1.1.1/32", "path-information": "0.0.0.0" } ] } } } } } }
265-
```
18+
### Modifications
19+
This version of ExaBGP differs from the original ExaBGP 4.2.11 by the
20+
application of fixes for these issues/pull requests:
21+
* update/traffic: fix IPv6 translation [PR #1003](https://github.com/Exa-Networks/exabgp/pull/1003)
22+
* BGP flowspec IPv6 redirect [Issue #1004](https://github.com/Exa-Networks/exabgp/issues/1004)

0 commit comments

Comments
 (0)