From ea84c20c30ec7b305c3b13df609c6f51bd2cda70 Mon Sep 17 00:00:00 2001 From: Johannes Moos Date: Sat, 13 Nov 2021 13:01:49 +0100 Subject: [PATCH] Update README.md --- README.md | 62 ++++++++++++++++++++----------------------------------- 1 file changed, 22 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 9a7fb80..02a1a2c 100644 --- a/README.md +++ b/README.md @@ -3,13 +3,13 @@ birdwatcher is a small HTTP server meant to provide an API defined by Barry O'Donovan's [birds-eye](https://github.com/inex/birds-eye-design/) to -[the BIRD routing daemon](http://bird.network.cz/). +[the BIRD internet routing daemon](http://bird.network.cz/). ## Why The [INEX implementation](https://github.com/inex/birdseye) of birdseye runs PHP, which is not always desirable (and performant) -in a routeserver setting. By using Go, we are able to work with +in a route server setting. By using Go, we are able to work with regular binaries, which means deployment and maintenance might be more convenient. @@ -24,7 +24,7 @@ Please make sure your go version is `>= 1.9`. Running `go install github.com/alice-lg/birdwatcher@latest` will give you a binary. You might need to cross-compile it for your -bird-running servive (`GOARCH` and `GOOS` are your friends). +bird-running service (`GOARCH` and `GOOS` are your friends). We provide a Makefile for more advanced compilation/configuration. Running `make linux` will create a Linux executable (by default for @@ -34,13 +34,14 @@ to the Makefile). #### 2.0 Breaking Change -The per peer table configuration is no longer done in the birdwatcher, -but directly in alice. +The BIRD configuration setup (single/multi table, pipe/table prefixes) is no longer +configured in birdwatcher but directly in Alice-LG. Please have a look at the +[source section of the Alice-LG config example](https://github.com/alice-lg/alice-lg/blob/master/etc/alice-lg/alice.example.conf). ### BIRD configuration -Birdwatcher parses the output of birdc and expects (for now) +Birdwatcher parses the output of `birdc[6]` and expects (for now) the time format to be `iso long`. You need to configure timeformat base iso long; @@ -51,8 +52,8 @@ the time format to be `iso long`. You need to configure in your `/etc/bird[6].conf` for birdwatcher to work. #### BIRD keep filtered routes -To also see the filtered routes in BIRD you need to make sure that you -have enabled the 'import keep filtered on' option for your BGP peers. +To also see filtered routes in configured BGP protocol instances, you need to make +sure that you have enabled the `import keep filtered on` option for affected bgp protocols. protocol bgp 'peerX' { ... @@ -60,39 +61,21 @@ have enabled the 'import keep filtered on' option for your BGP peers. ... } -Now you should be able to do a 'show route filtered' in BIRD. +Now you should be able to do a `show route filtered protocol peerX` in BIRD. -Do note that 'import keep filtered on' does NOT work for BIRD's pipe protocol -which is used when you have per peer tables, often used with Route Servers. If -your BIRD configuration has its import filters set on the BIRD pipe protocols -themselves then you will not be able to show the filtered routes. -However, you could move the import filters from the pipes to the BGP protocols -directly. For example: +If you use a multi table setup you are also using the pipe protocol the connect the tables. +No special BIRD configuration is required to be able to query pipe filtered routes. - table master; - table table_peer_X; +birdwatcher provides [various endpoints (see "available modules" section)](https://github.com/alice-lg/birdwatcher/blob/master/etc/birdwatcher/birdwatcher.conf) +to query routes filtered in bgp protocol as well as pipe protocol instances. - protocol pipe pipe_peer_X { - table master; - peer table table_peer_X; - mode transparent; - import all; - export where exportMagic(); - } - - protocol bgp 'peerX' { - ... - table table_peer_X; - import where importFilter(); - import keep filtered on; - export all; - ... - } +For use with [Alice-LG](https://github.com/alice-lg/alice-lg), make sure to set the appropriate BIRD config setup +in your [Alice-LG configuration](https://github.com/alice-lg/alice-lg/blob/master/etc/alice-lg/alice.example.conf). #### BIRD tagging filtered routes -If you want to make use of the filtered route reasons in the Birdseye then you need +If you want to make use of the filtered route reasons in [Alice-LG](https://github.com/alice-lg/alice-lg), you need to make sure that you are using BIRD 1.6.3 or up as you will need Large BGP Communities -(http://largebgpcommunities.net/). +(http://largebgpcommunities.net/) support. You need to add a Large BGP Community just before you filter a route, for example: @@ -126,7 +109,7 @@ You need to add a Large BGP Community just before you filter a route, for exampl ### Using Docker -You can run the birdwatcher for bird2 with docker: +You can run the birdwatcher for BIRD2 with docker: docker pull alicelg/birdwatcher:latest @@ -164,16 +147,15 @@ If you do not know how to configure it, please consider opening ## How -In the background `birdwatcher` runs the `birdc` client, sends +In the background `birdwatcher` runs the `birdc[6]` client, sends commands and parses the result. It also leverages simple caching -techniques to help reduce the load on the bird service. +techniques to help reduce the load on the BIRD service. ## Who Initially developed by Daniel and MC from [Netnod](https://www.netnod.se/) in two days at the RIPE 73 IXP Tools Hackathon in Madrid, Spain. -Running bird and parsing the results was added by [Veit Heller](https://github.com/hellerve/) on behalf of [ecix](http://ecix.net/). +Running BIRD and parsing the results was added by [Veit Heller](https://github.com/hellerve/) on behalf of [ecix](http://ecix.net/). With major contributions from: Patrick Seeburger and Benedikt Rudolph on behalf of [DE-CIX](https://de-cix.net). -