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 neighborattribute_maps
specifies attribute_map list that are used before paths are advertised. All the items in the list must be an instance of AttributeMap classroute_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, seeos_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
traffic_action
redirect
traffic_marking
vlan_action
tpid_action
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 neighborfilters
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-classIf 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
subclassis_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.PERMITPrefixFilter.POLICY_DENYge
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_TOPASPathFilter.POLICY_ENDASPathFilter.POLICY_INCLUDEASPathFilter.POLICY_NOT_INCLUDEMeaning 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.
-