BGP speaker library API Reference

BGPSpeaker class

class os_ken.services.protocols.bgp.bgpspeaker.BGPSpeaker(as_number, router_id, bgp_server_hosts=('0.0.0.0', '::'), bgp_server_port=179, refresh_stalepath_time=0, refresh_max_eor_time=0, best_path_change_handler=None, adj_rib_in_change_handler=None, peer_down_handler=None, peer_up_handler=None, ssh_console=False, ssh_port=None, ssh_host=None, ssh_host_key=None, label_range=(100, 100000), allow_local_as_in_count=0, cluster_id=None, local_pref=100)

Class to provide the APIs of OSKen BGP Speaker.

as_number specifies an Autonomous Number. It must be an integer between 1 and 65535.

router_id specifies BGP router identifier. It must be the string representation of an IPv4 address (e.g. 10.0.0.1).

bgp_server_host specifies a list of TCP listen host addresses.

bgp_server_port specifies TCP listen port number. 179 is used if not specified.

refresh_stalepath_time causes the BGP speaker to remove stale routes from the BGP table after the timer expires, even if the speaker does not receive a Router-Refresh End-of-RIB message. This feature is disabled (not implemented yet).

refresh_max_eor_time causes the BGP speaker to generate a Route-Refresh End-of-RIB message if it was not able to generate one due to route flapping. This feature is disabled (not implemented yet).

best_path_change_handler, if specified, is called when any best remote path is changed due to an update message or remote peer down. The handler is supposed to take one argument, the instance of an EventPrefix class instance.

adj_rib_in_change_handler, if specified, is called when any adj-RIB-in path is changed due to an update message or remote peer down. The given handler should take three argument, the instance of an EventPrefix class instance, str type peer's IP address and int type peer's AS number.

peer_down_handler, if specified, is called when BGP peering session goes down.

peer_up_handler, if specified, is called when BGP peering session goes up.

ssh_console specifies whether or not SSH CLI need to be started.

ssh_port specifies the port number for SSH CLI server. The default is bgp.operator.ssh.DEFAULT_SSH_PORT.

ssh_host specifies the IP address for SSH CLI server. The default is bgp.operator.ssh.DEFAULT_SSH_HOST.

ssh_host_key specifies the path to the host key added to the keys list used by SSH CLI server. The default is bgp.operator.ssh.DEFAULT_SSH_HOST_KEY.

label_range specifies the range of MPLS labels generated automatically.

allow_local_as_in_count maximum number of local AS number occurrences in AS_PATH. This option is useful for e.g. auto RD/RT configurations in leaf/spine architecture with shared AS numbers. The default is 0 and means "local AS number is not allowed in AS_PATH". To allow local AS, 3 is recommended (Cisco's default).

cluster_id specifies the cluster identifier for Route Reflector. It must be the string representation of an IPv4 address. If omitted, "router_id" is used for this field.

local_pref specifies the default local preference. It must be an integer.

attribute_map_get(address, route_dist=None, route_family='ipv4')

This method gets in-bound filters of the specified neighbor.

address specifies the IP address of the neighbor.

route_dist specifies route distinguisher that has attribute_maps.

route_family specifies route family of the VRF. This parameter must be one of the following.

  • RF_VPN_V4 (default) = 'ipv4'

  • RF_VPN_V6 = 'ipv6'

Returns a list object containing an instance of AttributeMap

attribute_map_set(address, attribute_maps, route_dist=None, route_family='ipv4')

This method sets attribute mapping to a neighbor. attribute mapping can be used when you want to apply attribute to BGPUpdate under specific conditions.

address specifies the IP address of the neighbor

attribute_maps specifies attribute_map list that are used before paths are advertised. All the items in the list must be an instance of AttributeMap class

route_dist specifies route dist in which attribute_maps are added.

route_family specifies route family of the VRF. This parameter must be one of the following.

  • RF_VPN_V4 (default) = 'ipv4'

  • RF_VPN_V6 = 'ipv6'

We can set AttributeMap to a neighbor as follows:

pref_filter = PrefixFilter('192.168.103.0/30',
                           PrefixFilter.POLICY_PERMIT)

attribute_map = AttributeMap([pref_filter],
                             AttributeMap.ATTR_LOCAL_PREF, 250)

speaker.attribute_map_set('192.168.50.102', [attribute_map])
bmp_server_add(address, port)

This method registers a new BMP (BGP monitoring Protocol) server. The BGP speaker starts to send BMP messages to the server. Currently, only one BMP server can be registered.

address specifies the IP address of a BMP server.

port specifies the listen port number of a BMP server.

bmp_server_del(address, port)

This method unregister the registered BMP server.

address specifies the IP address of a BMP server.

port specifies the listen port number of a BMP server.

evpn_prefix_add(route_type, route_dist, esi=0, ethernet_tag_id=None, mac_addr=None, ip_addr=None, ip_prefix=None, gw_ip_addr=None, vni=None, next_hop=None, tunnel_type=None, pmsi_tunnel_type=None, redundancy_mode=None)

This method adds a new EVPN route to be advertised.

route_type specifies one of the EVPN route type name. This parameter must be one of the following.

  • EVPN_ETH_AUTO_DISCOVERY = 'eth_ad'

  • EVPN_MAC_IP_ADV_ROUTE = 'mac_ip_adv'

  • EVPN_MULTICAST_ETAG_ROUTE = 'multicast_etag'

  • EVPN_ETH_SEGMENT = 'eth_seg'

  • EVPN_IP_PREFIX_ROUTE = 'ip_prefix'

route_dist specifies a route distinguisher value.

esi is an value to specify the Ethernet Segment Identifier. 0 is the default and denotes a single-homed site. If you want to advertise esi other than 0, it must be set as dictionary type. If esi is dictionary type, 'type' key must be set and specifies ESI type. For the supported ESI type, see os_ken.lib.packet.bgp.EvpnEsi. The remaining arguments are the same as that for the corresponding class.

ethernet_tag_id specifies the Ethernet Tag ID.

mac_addr specifies a MAC address to advertise.

ip_addr specifies an IPv4 or IPv6 address to advertise.

ip_prefix specifies an IPv4 or IPv6 prefix to advertise.

gw_ip_addr specifies an IPv4 or IPv6 address of gateway to advertise.

vni specifies an Virtual Network Identifier for VXLAN or Virtual Subnet Identifier for NVGRE. If tunnel_type is not TUNNEL_TYPE_VXLAN or TUNNEL_TYPE_NVGRE, this field is ignored.

next_hop specifies the next hop address for this prefix.

tunnel_type specifies the data plane encapsulation type to advertise. By the default, this attribute is not advertised. The supported encapsulation types are following.

  • TUNNEL_TYPE_VXLAN = 'vxlan'

  • TUNNEL_TYPE_NVGRE = 'nvgre

pmsi_tunnel_type specifies the type of the PMSI tunnel attribute used to encode the multicast tunnel identifier. This attribute is advertised only if route_type is EVPN_MULTICAST_ETAG_ROUTE and not advertised by the default. This attribute can also carry vni if tunnel_type is specified. The supported PMSI tunnel types are following.

  • PMSI_TYPE_NO_TUNNEL_INFO = 0

  • PMSI_TYPE_INGRESS_REP = 6

redundancy_mode specifies a redundancy mode type. This attribute is advertised only if route_type is EVPN_ETH_AUTO_DISCOVERY and not advertised by the default. The supported redundancy mode types are following.

  • REDUNDANCY_MODE_ALL_ACTIVE = 'all_active'

  • REDUNDANCY_MODE_SINGLE_ACTIVE = 'single_active'

evpn_prefix_del(route_type, route_dist, esi=0, ethernet_tag_id=None, mac_addr=None, ip_addr=None, ip_prefix=None)

This method deletes an advertised EVPN route.

route_type specifies one of the EVPN route type name.

route_dist specifies a route distinguisher value.

esi is an value to specify the Ethernet Segment Identifier.

ethernet_tag_id specifies the Ethernet Tag ID.

mac_addr specifies a MAC address to advertise.

ip_addr specifies an IPv4 or IPv6 address to advertise.

ip_prefix specifies an IPv4 or IPv6 prefix to advertise.

flowspec_prefix_add(flowspec_family, rules, route_dist=None, actions=None)

This method adds a new Flow Specification prefix to be advertised.

flowspec_family specifies one of the flowspec family name. This parameter must be one of the following.

  • FLOWSPEC_FAMILY_IPV4 = 'ipv4fs'

  • FLOWSPEC_FAMILY_IPV6 = 'ipv6fs'

  • FLOWSPEC_FAMILY_VPNV4 = 'vpnv4fs'

  • FLOWSPEC_FAMILY_VPNV6 = 'vpnv6fs'

  • FLOWSPEC_FAMILY_L2VPN = 'l2vpnfs'

rules specifies NLRIs of Flow Specification as a dictionary type value. For the supported NLRI types and arguments, see from_user() method of the following classes.

route_dist specifies a route distinguisher value. This parameter is required only if flowspec_family is one of the following address family.

  • FLOWSPEC_FAMILY_VPNV4 = 'vpnv4fs'

  • FLOWSPEC_FAMILY_VPNV6 = 'vpnv6fs'

  • FLOWSPEC_FAMILY_L2VPN = 'l2vpnfs'

actions specifies Traffic Filtering Actions of Flow Specification as a dictionary type value. The keys are "ACTION_NAME" for each action class and values are used for the arguments to that class. For the supported "ACTION_NAME" and arguments, see the following table.

ACTION_NAME

Action Class

traffic_rate

os_ken.lib.packet.bgp.BGPFlowSpecTrafficRateCommunity

traffic_action

os_ken.lib.packet.bgp.BGPFlowSpecTrafficActionCommunity

redirect

os_ken.lib.packet.bgp.BGPFlowSpecRedirectCommunity

traffic_marking

os_ken.lib.packet.bgp.BGPFlowSpecTrafficMarkingCommunity

vlan_action

os_ken.lib.packet.bgp.BGPFlowSpecVlanActionCommunity

tpid_action

os_ken.lib.packet.bgp.BGPFlowSpecTPIDActionCommunity

Example(IPv4):

>>> speaker = BGPSpeaker(as_number=65001, router_id='172.17.0.1')
>>> speaker.neighbor_add(address='172.17.0.2',
...                      remote_as=65002,
...                      enable_ipv4fs=True)
>>> speaker.flowspec_prefix_add(
...     flowspec_family=FLOWSPEC_FAMILY_IPV4,
...     rules={
...         'dst_prefix': '10.60.1.0/24'
...     },
...     actions={
...         'traffic_marking': {
...             'dscp': 24
...         }
...     }
... )

Example(VPNv4):

>>> speaker = BGPSpeaker(as_number=65001, router_id='172.17.0.1')
>>> speaker.neighbor_add(address='172.17.0.2',
...                      remote_as=65002,
...                      enable_vpnv4fs=True)
>>> speaker.vrf_add(route_dist='65001:100',
...                 import_rts=['65001:100'],
...                 export_rts=['65001:100'],
...                 route_family=RF_VPNV4_FLOWSPEC)
>>> speaker.flowspec_prefix_add(
...     flowspec_family=FLOWSPEC_FAMILY_VPNV4,
...     route_dist='65000:100',
...     rules={
...         'dst_prefix': '10.60.1.0/24'
...     },
...     actions={
...         'traffic_marking': {
...             'dscp': 24
...         }
...     }
... )
flowspec_prefix_del(flowspec_family, rules, route_dist=None)

This method deletes an advertised Flow Specification route.

flowspec_family specifies one of the flowspec family name.

rules specifies NLRIs of Flow Specification as a dictionary type value.

route_dist specifies a route distinguisher value.

in_filter_get(address)

This method gets in-bound filters of the specified neighbor.

address specifies the IP address of the neighbor.

Returns a list object containing an instance of Filter sub-class

in_filter_set(address, filters)

This method sets in-bound filters to a neighbor.

address specifies the IP address of the neighbor

filters specifies filter list applied before advertised paths are imported to the global rib. All the items in the list must be an instance of Filter sub-class.

neighbor_add(address, remote_as, remote_port=179, enable_ipv4=True, enable_ipv6=False, enable_vpnv4=False, enable_vpnv6=False, enable_evpn=False, enable_ipv4fs=False, enable_ipv6fs=False, enable_vpnv4fs=False, enable_vpnv6fs=False, enable_l2vpnfs=False, enable_enhanced_refresh=False, enable_four_octet_as_number=True, next_hop=None, password=None, multi_exit_disc=None, site_of_origins=None, is_route_server_client=False, is_route_reflector_client=False, is_next_hop_self=False, local_address=None, local_port=None, local_as=None, connect_mode='both')

This method registers a new neighbor. The BGP speaker tries to establish a bgp session with the peer (accepts a connection from the peer and also tries to connect to it).

address specifies the IP address of the peer. It must be the string representation of an IP address. Only IPv4 is supported now.

remote_as specifies the AS number of the peer. It must be an integer between 1 and 65535.

remote_port specifies the TCP port number of the peer.

enable_ipv4 enables IPv4 address family for this neighbor.

enable_ipv6 enables IPv6 address family for this neighbor.

enable_vpnv4 enables VPNv4 address family for this neighbor.

enable_vpnv6 enables VPNv6 address family for this neighbor.

enable_evpn enables Ethernet VPN address family for this neighbor.

enable_ipv4fs enables IPv4 Flow Specification address family for this neighbor.

enable_ipv6fs enables IPv6 Flow Specification address family for this neighbor.

enable_vpnv4fs enables VPNv4 Flow Specification address family for this neighbor.

enable_vpnv6fs enables VPNv6 Flow Specification address family for this neighbor.

enable_l2vpnfs enables L2VPN Flow Specification address family for this neighbor.

enable_enhanced_refresh enables Enhanced Route Refresh for this neighbor.

enable_four_octet_as_number enables Four-Octet AS Number capability for this neighbor.

next_hop specifies the next hop IP address. If not specified, host's ip address to access to a peer is used.

password is used for the MD5 authentication if it's specified. By default, the MD5 authentication is disabled.

multi_exit_disc specifies multi exit discriminator (MED) value as an int type value. If omitted, MED is not sent to the neighbor.

site_of_origins specifies site_of_origin values. This parameter must be a list of string.

is_route_server_client specifies whether this neighbor is a router server's client or not.

is_route_reflector_client specifies whether this neighbor is a router reflector's client or not.

is_next_hop_self specifies whether the BGP speaker announces its own ip address to iBGP neighbor or not as path's next_hop address.

local_address specifies Loopback interface address for iBGP peering.

local_port specifies source TCP port for iBGP peering.

local_as specifies local AS number per-peer. If omitted, the AS number of BGPSpeaker instance is used.

connect_mode specifies how to connect to this neighbor. This parameter must be one of the following.

  • CONNECT_MODE_ACTIVE = 'active'

  • CONNECT_MODE_PASSIVE = 'passive'

  • CONNECT_MODE_BOTH (default) = 'both'

neighbor_del(address)

This method unregister the registered neighbor. If a session with the peer exists, the session will be closed.

address specifies the IP address of the peer. It must be the string representation of an IP address.

neighbor_get(route_type, address, format='json')

This method returns the BGP adj-RIB-in/adj-RIB-out information in a json format.

route_type This parameter is necessary for only received-routes and sent-routes.

  • received-routes : paths received and not withdrawn by given peer

  • sent-routes : paths sent and not withdrawn to given peer

address specifies the IP address of the peer. It must be the string representation of an IP address.

format specifies the format of the response. This parameter must be one of the following.

  • 'json' (default)

  • 'cli'

neighbor_reset(address)

This method reset the registered neighbor.

address specifies the IP address of the peer. It must be the string representation of an IP address.

neighbor_state_get(address=None, format='json')

This method returns the state of peer(s) in a json format.

address specifies the address of a peer. If not given, the state of all the peers return.

format specifies the format of the response. This parameter must be one of the following.

  • 'json' (default)

  • 'cli'

neighbor_update(address, conf_type, conf_value)

This method changes the neighbor configuration.

address specifies the IP address of the peer.

conf_type specifies configuration type which you want to change. Currently os_ken.services.protocols.bgp.bgpspeaker.MULTI_EXIT_DISC can be specified.

conf_value specifies value for the configuration type.

neighbors_get(format='json')

This method returns a list of the BGP neighbors.

format specifies the format of the response. This parameter must be one of the following.

  • 'json' (default)

  • 'cli'

out_filter_get(address)

This method gets out-filter setting from the specified neighbor.

address specifies the IP address of the peer.

Returns a list object containing an instance of Filter sub-class

out_filter_set(address, filters)

This method sets out-filter to neighbor.

address specifies the IP address of the peer.

filters specifies a filter list to filter the path advertisement. The contents must be an instance of Filter sub-class

If you want to define out-filter that send only a particular prefix to neighbor, filters can be created as follows:

p = PrefixFilter('10.5.111.0/24',
                 policy=PrefixFilter.POLICY_PERMIT)

all = PrefixFilter('0.0.0.0/0',
                   policy=PrefixFilter.POLICY_DENY)

pList = [p, all]

self.bgpspeaker.out_filter_set(neighbor_address, pList)

Note

out-filter evaluates paths in the order of Filter in the pList.

prefix_add(prefix, next_hop=None, route_dist=None)

This method adds a new prefix to be advertised.

prefix must be the string representation of an IP network (e.g., 10.1.1.0/24).

next_hop specifies the next hop address for this prefix. This parameter is necessary for only VPNv4 and VPNv6 address families.

route_dist specifies a route distinguisher value. This parameter is necessary for only VPNv4 and VPNv6 address families.

prefix_del(prefix, route_dist=None)

This method deletes a advertised prefix.

prefix must be the string representation of an IP network.

route_dist specifies a route distinguisher value.

rib_get(family='all', format='json')

This method returns the BGP routing information in a json format. This will be improved soon.

family specifies the address family of the RIB (e.g. 'ipv4').

format specifies the format of the response. This parameter must be one of the following.

  • 'json' (default)

  • 'cli'

shutdown()

Shutdown BGP speaker

vrf_add(route_dist, import_rts, export_rts, site_of_origins=None, route_family='ipv4', multi_exit_disc=None)

This method adds a new vrf used for VPN.

route_dist specifies a route distinguisher value.

import_rts specifies a list of route targets to be imported.

export_rts specifies a list of route targets to be exported.

site_of_origins specifies site_of_origin values. This parameter must be a list of string.

route_family specifies route family of the VRF. This parameter must be one of the following.

  • RF_VPN_V4 (default) = 'ipv4'

  • RF_VPN_V6 = 'ipv6'

  • RF_L2_EVPN = 'evpn'

  • RF_VPNV4_FLOWSPEC = 'ipv4fs'

  • RF_VPNV6_FLOWSPEC = 'ipv6fs'

  • RF_L2VPN_FLOWSPEC = 'l2vpnfs'

multi_exit_disc specifies multi exit discriminator (MED) value. It must be an integer.

vrf_del(route_dist)

This method deletes the existing vrf.

route_dist specifies a route distinguisher value.

vrfs_get(subcommand='routes', route_dist=None, route_family='all', format='json')

This method returns the existing vrfs.

subcommand specifies one of the following.

  • 'routes': shows routes present for vrf

  • 'summary': shows configuration and summary of vrf

route_dist specifies a route distinguisher value. If route_family is not 'all', this value must be specified.

route_family specifies route family of the VRF. This parameter must be one of the following.

  • RF_VPN_V4 = 'ipv4'

  • RF_VPN_V6 = 'ipv6'

  • RF_L2_EVPN = 'evpn'

  • 'all' (default)

format specifies the format of the response. This parameter must be one of the following.

  • 'json' (default)

  • 'cli'

class os_ken.services.protocols.bgp.bgpspeaker.EventPrefix(path, is_withdraw)

Used to pass an update on any best remote path to best_path_change_handler.

Attribute

Description

remote_as

The AS number of a peer that caused this change

route_dist

None in the case of IPv4 or IPv6 family

prefix

A prefix was changed

nexthop

The nexthop of the changed prefix

label

MPLS label for VPNv4, VPNv6 or EVPN prefix

path

An instance of info_base.base.Path subclass

is_withdraw

True if this prefix has gone otherwise False
class os_ken.services.protocols.bgp.info_base.base.PrefixFilter(prefix, policy, ge=None, le=None)

Used to specify a prefix for filter.

We can create PrefixFilter object as follows:

prefix_filter = PrefixFilter('10.5.111.0/24',
                             policy=PrefixFilter.POLICY_PERMIT)

Attribute

Description

prefix

A prefix used for this filter

policy

One of the following values.

PrefixFilter.POLICY.PERMIT
PrefixFilter.POLICY_DENY

ge

Prefix length that will be applied to this filter. ge means greater than or equal.

le

Prefix length that will be applied to this filter. le means less than or equal.

For example, when PrefixFilter object is created as follows:

p = PrefixFilter('10.5.111.0/24',
                 policy=PrefixFilter.POLICY_DENY,
                 ge=26, le=28)

Prefixes which match 10.5.111.0/24 and its length matches from 26 to 28 will be filtered. When this filter is used as an out-filter, it will stop sending the path to neighbor because of POLICY_DENY. When this filter is used as in-filter, it will stop importing the path to the global rib because of POLICY_DENY. If you specify POLICY_PERMIT, the path is sent to neighbor or imported to the global rib.

If you don't want to send prefixes 10.5.111.64/26 and 10.5.111.32/27 and 10.5.111.16/28, and allow to send other 10.5.111.0's prefixes, you can do it by specifying as follows:

p = PrefixFilter('10.5.111.0/24',
                 policy=PrefixFilter.POLICY_DENY,
                 ge=26, le=28).
clone()

This method clones PrefixFilter object.

Returns PrefixFilter object that has the same values with the original one.

evaluate(path)

This method evaluates the prefix.

Returns this object's policy and the result of matching. If the specified prefix matches this object's prefix and ge and le condition, this method returns True as the matching result.

path specifies the path that has prefix.

class os_ken.services.protocols.bgp.info_base.base.ASPathFilter(as_number, policy)

Used to specify a prefix for AS_PATH attribute.

We can create ASPathFilter object as follows:

as_path_filter = ASPathFilter(65000,policy=ASPathFilter.TOP)

Attribute

Description

as_number

A AS number used for this filter

policy

One of the following values.

ASPathFilter.POLICY_TOP
ASPathFilter.POLICY_END
ASPathFilter.POLICY_INCLUDE
ASPathFilter.POLICY_NOT_INCLUDE

Meaning of each policy is as follows:

Policy

Description

POLICY_TOP

Filter checks if the specified AS number is at the top of AS_PATH attribute.

POLICY_END

Filter checks is the specified AS number is at the last of AS_PATH attribute.

POLICY_INCLUDE

Filter checks if specified AS number exists in AS_PATH attribute.

POLICY_NOT_INCLUDE

Opposite to POLICY_INCLUDE.
clone()

This method clones ASPathFilter object.

Returns ASPathFilter object that has the same values with the original one.

evaluate(path)

This method evaluates as_path list.

Returns this object's policy and the result of matching. If the specified AS number matches this object's AS number according to the policy, this method returns True as the matching result.

path specifies the path.

class os_ken.services.protocols.bgp.info_base.base.AttributeMap(filters, attr_type, attr_value)

This class is used to specify an attribute to add if the path matches filters. We can create AttributeMap object as follows:

pref_filter = PrefixFilter('192.168.103.0/30',
                           PrefixFilter.POLICY_PERMIT)

attribute_map = AttributeMap([pref_filter],
                             AttributeMap.ATTR_LOCAL_PREF, 250)

speaker.attribute_map_set('192.168.50.102', [attribute_map])

AttributeMap.ATTR_LOCAL_PREF means that 250 is set as a local preference value if nlri in the path matches pref_filter.

ASPathFilter is also available as a filter. ASPathFilter checks if AS_PATH attribute in the path matches AS number in the filter.

Attribute

Description

filters

A list of filter. Each object should be a Filter class or its sub-class

attr_type

A type of attribute to map on filters. Currently AttributeMap.ATTR_LOCAL_PREF is available.

attr_value

A attribute value
clone()

This method clones AttributeMap object.

Returns AttributeMap object that has the same values with the original one.

evaluate(path)

This method evaluates attributes of the path.

Returns the cause and result of matching. Both cause and result are returned from filters that this object contains.

path specifies the path.