JSON Message Format

bgpipe can represent BGP messages in a structured JSON format for easy processing and filtering. This page documents the format, which is implemented by the bgpfix library. For example, the JSON translation feature can be useful for external processors - e.g. Python scripts via the exec or websocket stages - or for BGP message inspection or archiving.

Overview

Each BGP message is represented as a JSON array with the following structure:

[dir, seq, time, len, type, data, meta]

Where:

Index	Name	Type	Description
`[0]`	`dir`	string	direction: `L` (left) or `R` (right)
`[1]`	`seq`	int	sequence number (monotonic counter)
`[2]`	`time`	string	timestamp in `YYYY-MM-DDTHH:MM:SS.mmm` format
`[3]`	`len`	int	length of the BGP message
`[4]`	`type`	string/int	type: `OPEN`, `UPDATE`, `KEEPALIVE`, etc.
`[5]`	`data`	object/string	type-specific object or raw hex string (optional)
`[6]`	`meta`	object	bgpipe metadata (optional)

Example KEEPALIVE Message

["R", 2, "2025-07-11T08:47:22.659", 0, "KEEPALIVE"]

OPEN Messages

For OPEN messages, the data field contains a JSON object with the BGP session parameters and capabilities:

{
  "bgp": 4,
  "asn": 65055,
  "id": "192.0.2.1",
  "hold": 90,
  "caps": { ... } // or "params": "0x..." if no caps
}

Where:

Field	Type	Description
`bgp`	int	BGP protocol version (always 4)
`asn`	int	Autonomous System Number (2-byte)
`id`	string	BGP Router ID in dotted-decimal IPv4 format
`hold`	int	Hold time in seconds
`caps`	object	BGP capabilities (see below)
`params`	string	Raw optional parameters as hex string (only if no caps)

The caps object contains BGP capabilities:

{
  "MP": ["IPV4/UNICAST"],
  "ROUTE_REFRESH": true,
  "EXTENDED_MESSAGE": true,
  "AS4": 64515
}

Common capabilities (see bgpfix source):

MP: Array of supported AFI/SAFI combinations (e.g., IPV4/UNICAST, IPV6/FLOWSPEC)
ROUTE_REFRESH: Boolean, supports Route Refresh (RFC 2918)
EXTENDED_MESSAGE: Boolean, supports messages larger than 4096 bytes (RFC 8654)
AS4: Number, 4-byte ASN value (RFC 6793)

Complete example:

[
  "L",
  1,
  "2025-07-11T08:47:22.659",
  "OPEN",
  {
    "bgp": 4,
    "asn": 65055,
    "id": "85.232.240.180",
    "hold": 7200,
    "caps": {
      "MP": ["IPV4/FLOWSPEC"],
      "ROUTE_REFRESH": true
    }
  }
]

UPDATE Messages

For UPDATE messages, element data field contains a JSON object with reachable/withdrawn IPv4 prefixes and the path attributes:

{
  "reach": [ ... ],
  "unreach": [ ... ],
  "attrs": { ... }
}

Where:

Field	Type	Description
`reach`	array	Array of reachable IPv4 unicast prefixes (announced routes)
`unreach`	array	Array of unreachable IPv4 unicast prefixes (withdrawn routes)
`attrs`	object	BGP path attributes (see below)

Note: For MP-BGP (multi-protocol) routes (IPv6, Flowspec, etc.), prefixes are embedded within the MP_REACH or MP_UNREACH attributes.

Path Attributes

The attrs object contains BGP path attributes. Each attribute has:

Key: Attribute name (e.g., ORIGIN, ASPATH, COMMUNITY)
Value: Object with flags and value fields

"ORIGIN": {
  "flags": "T",
  "value": "IGP"
}

Attribute Flags

Flags are a string combining these characters:

O: Optional
T: Transitive
P: Partial
X: Extended length

Well-known attributes (ORIGIN, ASPATH, NEXTHOP) use T only. Optional attributes use combinations like OT.

Common Path Attributes

ORIGIN

Origin of the route:

"ORIGIN": {
  "flags": "T",
  "value": "IGP"  // or EGP or INCOMPLETE
}

ASPATH

AS path as an array. AS sequences are flat arrays, AS sets are nested arrays:

"ASPATH": {
  "flags": "T",
  "value": [64515, 20473, 15169]  // AS_SEQUENCE
}

With AS_SET:

"ASPATH": {
  "flags": "T",
  "value": [64515, [20473, 15169]]  // last is AS_SET
}

NEXTHOP

IPv4 next-hop address:

"NEXTHOP": {
  "flags": "T",
  "value": "192.0.2.1"
}

MED (Multi-Exit Discriminator)

"MED": {
  "flags": "O",
  "value": 100
}

LOCALPREF (Local Preference)

"LOCALPREF": {
  "flags": "T",
  "value": 200
}

COMMUNITY

Standard BGP communities as ASN:value strings:

"COMMUNITY": {
  "flags": "OT",
  "value": ["65000:100", "65000:200"]
}

LARGE_COMMUNITY

Large BGP communities (RFC 8092):

"LARGE_COMMUNITY": {
  "flags": "OT",
  "value": ["65000:100:1", "65000:200:2"]
}

EXT_COMMUNITY (Extended Communities)

Extended communities with type-specific encoding:

"EXT_COMMUNITY": {
  "flags": "OT",
  "value": [
    {"type": "RT", "asn": 65000, "val": 100},
    {"type": "RT", "ip": "192.0.2.1", "val": 100}
  ]
}

Common types: RT (Route Target), RO (Route Origin), REDIR_IP4 (Flowspec redirect), RATE (Flowspec rate-limit).

MP-BGP Attributes

MP_REACH

Multi-protocol reachable NLRI (used for IPv6, Flowspec, etc.):

"MP_REACH": {
  "flags": "OX",
  "value": {
    "af": "IPV6/UNICAST",
    "nexthop": "2001:db8::1",
    "prefixes": ["2001:db8:1::/48", "2001:db8:2::/48"]
  }
}

For Flowspec, see the Flowspec section below.

MP_UNREACH

Multi-protocol unreachable NLRI (withdrawals):

"MP_UNREACH": {
  "flags": "OX",
  "value": {
    "af": "IPV6/UNICAST",
    "prefixes": ["2001:db8:3::/48"]
  }
}

Complete UPDATE Example

[
  "R",
  243,
  "2025-07-11T11:23:50.860",
  1459,
  "UPDATE",
  {
    "reach": ["8.8.8.0/24", "8.8.4.0/24"],
    "attrs": {
      "ORIGIN": {
        "flags": "T",
        "value": "IGP"
      },
      "ASPATH": {
        "flags": "T",
        "value": [64515, 15169]
      },
      "NEXTHOP": {
        "flags": "T",
        "value": "192.0.2.1"
      },
      "COMMUNITY": {
        "flags": "OT",
        "value": ["64515:100"]
      }
    }
  },
  {}
]

Flowspec Messages

Flowspec (Flow Specification) messages are a special type of UPDATE that carries traffic filtering rules instead of routing prefixes. They use the MP_REACH or MP_UNREACH attributes with AFI/SAFI set to IPV4/FLOWSPEC or IPV6/FLOWSPEC.

Flowspec in MP_REACH

"MP_REACH": {
  "flags": "OX",
  "value": {
    "af": "IPV4/FLOWSPEC",
    "nexthop": "0.0.0.0",
    "rules": [ ... ]
  }
}

Flowspec Rules

Each Flowspec rule is a JSON object with components (match conditions):

{
  "DST": "192.0.2.0/24",
  "SRC": "198.51.100.0/24",
  "PROTO": [{"op": "==", "val": 6}],
  "PORT_DST": [{"op": "==", "val": 80}]
}

Flowspec Components

Component	Type	Description
`DST`	prefix	Destination prefix
`SRC`	prefix	Source prefix
`PROTO`	operators	IP protocol (e.g., 6=TCP, 17=UDP)
`PORT`	operators	Source or destination port
`PORT_DST`	operators	Destination port
`PORT_SRC`	operators	Source port
`ICMP_TYPE`	operators	ICMP type
`ICMP_CODE`	operators	ICMP code
`TCP_FLAGS`	bitmask ops	TCP flags (bitmask matching)
`PKTLEN`	operators	Packet length
`DSCP`	operators	DSCP value
`FRAG`	bitmask ops	Fragmentation flags (bitmask matching)
`LABEL`	operators	IPv6 flow label (IPv6 only)

Numeric Operators

For components like PROTO, PORT_DST, etc., the value is an array of operator objects:

[
  {"op": "==", "val": 80},
  {"op": ">=", "val": 1024, "and": true}
]

Operator types:

==: Equal
>: Greater than
>=: Greater than or equal
<: Less than
<=: Less than or equal
!=: Not equal
true: Always match
false: Never match

Optional fields:

and: true: Logical AND with next condition (default is OR)

Bitmask Operators

For TCP_FLAGS and FRAG components:

[
  {"op": "ALL", "val": "0x12", "len": 1}
]

Bitmask operations:

ANY: Match if any bit is set
ALL: Match if all bits are set
NONE: Match if no bits are set
NOT-ALL: Match if not all bits are set

Fields:

val: Hex string (e.g., 0x12) representing the bitmask
len: Length in bytes (1, 2, 4, or 8)

IPv6 Prefix with Offset

For IPv6 Flowspec, prefixes can specify an offset:

"DST": "2001:db8::/32-64"

Format: address/offset-length where offset is the bit position to start matching from.

Flowspec Actions (Extended Communities)

Flowspec rules typically have associated actions in extended communities:

"EXT_COMMUNITY": {
  "flags": "OT",
  "value": [
    {"type": "REDIR_IP4", "ip": "192.0.2.1", "val": 100},
    {"type": "RATE", "rate": 0}
  ]
}

Common Flowspec actions:

REDIR_IP4 / REDIR_IP6: Redirect traffic to VRF
RATE: Rate limit in bytes/second (0 = discard)
MARK: DSCP marking value
RT: Route Target (for VRF import/export)

Complete Flowspec Example

This example blocks TCP traffic to port 80 from a specific prefix:

[
  "R",
  15,
  "2025-07-11T10:50:00.000",
  128,
  "UPDATE",
  {
    "attrs": {
      "ORIGIN": {
        "flags": "T",
        "value": "IGP"
      },
      "ASPATH": {
        "flags": "T",
        "value": [65055]
      },
      "MP_REACH": {
        "flags": "OX",
        "value": {
          "af": "IPV4/FLOWSPEC",
          "nexthop": "0.0.0.0",
          "rules": [
            {
              "DST": "192.0.2.0/24",
              "PROTO": [{"op": "==", "val": 6}],
              "PORT_DST": [{"op": "==", "val": 80}]
            }
          ]
        }
      },
      "EXT_COMMUNITY": {
        "flags": "OT",
        "value": [
          {"type": "RATE", "rate": 0}
        ]
      }
    }
  },
  {}
]

Implementation Notes

Hex Encoding: When the upper layer is not parsed (e.g., unsupported attribute), the JSON value is a hex string like 0x1234abcd.
Time Format: Timestamps use YYYY-MM-DDTHH:MM:SS.mmm format (millisecond precision).
AFI/SAFI Format: Address family identifiers use AFI/SAFI format (e.g., IPV4/UNICAST, IPV6/FLOWSPEC).
Prefixes: IP prefixes use standard CIDR notation (e.g., 192.0.2.0/24, 2001:db8::/32).
Bidirectional: The JSON format fully supports both encoding (JSON to BGP wire) and decoding (BGP wire to JSON).

JSON Message Format

Overview

OPEN Messages

UPDATE Messages

Path Attributes

Attribute Flags

Common Path Attributes

ORIGIN

ASPATH

NEXTHOP

MED (Multi-Exit Discriminator)

LOCALPREF (Local Preference)

COMMUNITY

LARGE_COMMUNITY

EXT_COMMUNITY (Extended Communities)

MP-BGP Attributes

MP_REACH

MP_UNREACH

Complete UPDATE Example

Flowspec Messages

Flowspec in MP_REACH

Flowspec Rules

Flowspec Components

Numeric Operators

Bitmask Operators

IPv6 Prefix with Offset

Flowspec Actions (Extended Communities)

Complete Flowspec Example

Implementation Notes

See Also