Stages¶
A stage is a processing step in a bgpipe pipeline. Each stage performs a specific
task: connecting to a BGP speaker, filtering messages, writing to a file, and so on.
Stages are composed left-to-right on the command line, separated by --.
Available Stages¶
| Stage | Description |
|---|---|
| aspa | Validate AS paths using RPKI ASPA |
| bmp | Collect or export a BMP feed over TCP |
| combine | Combine UPDATEs with the same attributes into one |
| connect | Connect to a BGP endpoint over TCP |
| drop | Drop messages matching a filter; keep the rest |
| exec | Pipe messages through an external process |
| grep | Keep messages matching a filter; drop the rest |
| head | Stop the pipeline after N messages |
| limit | Enforce prefix length and count limits |
| listen | Accept an incoming BGP connection over TCP |
| metrics | Count messages matching filters (Prometheus metrics) |
| pipe | Exchange messages through a named pipe (FIFO) |
| read | Read messages from a file or URL |
| ris-live | Stream BGP updates from RIPE RIS Live |
| rov | Validate route origins using RPKI ROV |
| rv-live | Stream BGP updates from RouteViews via Kafka |
| mrai | Hold announcements, send only the last one for each prefix |
| speaker | Run a simple BGP speaker |
| stdin | Read messages from standard input |
| stdout | Write messages to standard output |
| tag | Add or remove message tags |
| update | Modify UPDATE message attributes |
| websocket | Exchange messages over WebSocket |
| write | Write messages to a file |
Common Options¶
Every stage accepts the following options:
| Option | Description |
|---|---|
-L, --left |
Read messages flowing left (see Direction) |
-R, --right |
Read messages flowing right (see Direction) |
-A, --args |
Consume all remaining CLI arguments until -- |
-W, --wait events |
Wait for given event(s) before starting |
-S, --stop events |
Stop the stage after given event(s) |
--rate-limit N |
Delay messages to stay under N messages/sec |
--rate-sample N |
Randomly sample messages when over N messages/sec |
Stages that produce messages also accept:
| Option | Description |
|---|---|
-N, --new target |
Which stage to send new messages to (default next) |
In --wait and --stop, separate multiple events with commas. A stage name stands for its START event in --wait (eg. --wait listen), and for its STOP event in --stop. See Events for all event names.
Stages that support input or output filtering:
| Option | Description |
|---|---|
-I, --if filters |
Input filter: skip capturing messages that don't match all the filters |
-O, --of filters |
Output filter: drop produced messages that don't match all the filters |
Direction¶
Messages flow through the pipeline in two directions: right, from the first stage towards the last, and left, the other way.
A stage reads the messages flowing right, and writes new messages to the right. The ends of the pipeline (eg. a BGP peer, a file, or a live stream) are the exceptions:
- The first stage reads the messages flowing left, since nothing flows right into it.
- The last stage writes to the left, back into the pipeline.
Use -L, -R, or -LR to choose what a stage reads: the messages flowing
left, right, or both. A stage in the middle writes in the direction it reads;
the first and the last stage always write away from their end. With -LR, each
message keeps its own direction (eg. the dir field of
JSON). Stages that hold messages and write them later (eg.
combine, mrai) keep their direction too.
For example:
| Pipeline | Stage | Reads | Writes |
|---|---|---|---|
read in.mrt -- grep ... -- write out.json |
read | - | right |
| grep | right | - | |
| write | right | - | |
connect 192.0.2.1 -- update ... -- connect 198.51.100.1 |
first connect | left: to its peer | right: from its peer |
| update | right only (-LR for both) |
- | |
| last connect | right: to its peer | left: from its peer | |
read in.mrt -- exec ./filter.py |
exec | right | left: the script output |
ris-live -- combine |
combine | right | right |
With -o / --stdout, bgpipe prints the messages that reach either end of the
pipeline. Use -n / --explain to see what each stage reads and writes,
without running the pipeline.