Events¶
Events report what happens in a pipeline: the BGP session comes up, a stage connects, a prefix breaks a limit. They are not messages: they never flow through the pipeline. You use them on the command line to log what happened, to start or stop stages at the right moment, or to kill the session.
| Option | Where | Effect |
|---|---|---|
-e, --events events |
global | Log the events (default: PARSE,NOTIFY,ESTABLISHED,EOR; all for all) |
-k, --kill events |
global | Kill the session on any of the events (exit code 3) |
-W, --wait events |
any stage | Start the stage only after one of the events |
-S, --stop events |
any stage | Stop the stage after one of the events |
Separate multiple events with commas, eg. --events ESTABLISHED,limit/session.
Event Names¶
| You write | Means | Example |
|---|---|---|
NAME (any capital letter) |
the BGP session event NAME |
EOR = bgpfix/pipe.EOR |
stage (all lowercase) |
the lifecycle events of a stage, see below | --wait listen = listen/START |
stage/name |
the event name of a stage |
limit/session, listen/READY |
all or * |
all events | --events all |
A stage is named after its command (eg. listen,
limit). Mind the case: a
lowercase name with no slash is a stage, so --events established waits for a
stage called established. Write the BGP session events in capitals.
BGP Session Events¶
The pipeline emits these as messages reach its ends, in a given direction.
| Event | When |
|---|---|
START |
The pipeline has started |
STOP |
The pipeline is about to stop |
OPEN |
An OPEN reached the end of the pipeline |
ESTABLISHED |
The session is established: OPEN and KEEPALIVE made it both ways |
UPDATE |
An UPDATE reached the end of the pipeline (at most once per second) |
ALIVE |
A KEEPALIVE reached the end of the pipeline (at most once per second) |
EOR_AF |
End-of-RIB for one address family |
EOR |
End-of-RIB for all negotiated address families |
NOTIFY |
A NOTIFICATION reached the end of the pipeline |
PARSE |
A message could not be parsed |
Stage Lifecycle Events¶
Every stage emits these, eg. connect/READY.
| Event | When |
|---|---|
PREPARE |
The stage starts preparing (eg. connect dials its peer, listen waits for one) |
READY |
The stage is prepared (eg. the TCP connection is up) |
START |
The stage starts its work, once all stages started with it are ready |
STOP |
The stage has stopped |
A lowercase stage name stands for START in --wait, for STOP in --stop
and --kill, and for all four in --events.
Stage Events¶
| Event | Arguments | When | Stage |
|---|---|---|---|
limit/long |
prefix, origin AS | Prefix longer than --max-length |
limit |
limit/short |
prefix, origin AS | Prefix shorter than --min-length |
limit |
limit/session |
prefix, origin AS, count | Too many prefixes in the session (--session) |
limit |
limit/origin |
prefix, origin AS, count | Too many prefixes from one origin AS (--origin) |
limit |
limit/block |
prefix, origin AS, count | Too many prefixes in one IP block (--block) |
limit |
bmp/peer-up |
router, peer IP, peer AS | A monitored peer is up | bmp |
bmp/peer-down |
router, peer IP, peer AS | A monitored peer is down | bmp |
grep/name |
message | A message matches (--event-match name) or fails (--event-fail name) |
grep |
rov/name |
message | RPKI INVALID prefixes (--event name) |
rov |
aspa/name |
message | ASPA INVALID path (--event name) |
aspa |
grep, rov and aspa emit events only if you name
them, eg. rov --event dropped emits rov/dropped. Run bgpipe STAGE -h to see the
events of a stage.
Examples¶
Log the session coming up, and every prefix limit violation:
bgpipe --events ESTABLISHED,limit/session \
-- connect 192.0.2.1 \
-- limit --session 100000 \
-- connect 198.51.100.1
Kill the session when a peer announces too many prefixes:
bgpipe --kill limit/session \
-- listen :179 \
-- limit -LR --session 1000000 \
-- connect 198.51.100.1
Connect to the upstream router only after the downstream one connects:
Replay a file to a router after the session is up, then stop:
bgpipe \
-- speaker --active --asn 65000 --stop read/STOP \
-- read --wait ESTABLISHED updates.mrt \
-- connect 192.0.2.1
Logged events look like this:
INF event bgpfix/pipe.ESTABLISHED evseq=12 vals=[1700000000]
INF event limit/long evseq=90 stage="[2] limit" vals=["138.186.235.5/32",53062]