# BGP speaker library API Reference

## BGPSpeaker class

class `ryu.services.protocols.bgp.bgpspeaker.``BGPSpeaker`(as_number, router_id, bgp_server_port=179, refresh_stalepath_time=0, refresh_max_eor_time=0, best_path_change_handler=None, peer_down_handler=None, peer_up_handler=None, ssh_console=False, label_range=(100, 100000))
  `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 RF_VPN_V4 or RF_VPN_V6.

    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 RF_VPN_V4 or RF_VPN_V6.

    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.

  `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, enable_ipv4=True, enable_vpnv4=False, enable_vpnv6=False, enable_enhanced_refresh=False, next_hop=None, password=None, multi_exit_disc=None, site_of_origins=None, is_route_server_client=False, is_next_hop_self=False, local_address=None, local_port=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 IP v4 is supported now.

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

    `enable_ipv4` enables IPv4 address family for this neighbor. The default is True.

    `enable_vpnv4` enables VPNv4 address family for this neighbor. The default is False.

    `enable_vpnv6` enables VPNv6 address family for this neighbor. The default is False.

    `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 authenticaiton is disabled.

    `multi_exit_disc` specifies multi exit discriminator (MED) value. The default is None and if not specified, MED value is not sent to the neighbor. It must be an integer.

    `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_next_hop_self` specifies whether the BGP speaker announces its own ip address to iBGP neighbor or not as path’s next_hop address.

    `connect_mode` specifies how to connect to this neighbor. CONNECT_MODE_ACTIVE tries to connect from us. CONNECT_MODE_PASSIVE just listens and wait for the connection. CONNECT_MODE_BOTH use both methods. The default is CONNECT_MODE_BOTH

    `local_address` specifies Loopback interface address for iBGP peering.

    `local_port` specifies source TCP port for iBGP peering.

  `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`(routetype, address, format='json')

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

    `routetype` 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.

  `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.

  `neighbor_update`(address, conf_type, conf_value)

    This method changes the neighbor configuration.

    `conf_type` specifies configuration type which you want to change. Currently ryu.services.protocols.bgp.bgpspeaker.NEIGHBOR_CONF_MED can be specified.

    `conf_value` specifies value for the configuration type.

  `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 advertized.

    `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 advertized prefix.

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

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

  `rib_get`(family='ipv4', 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.

  `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 route targets to be imported.

    `export_rts` specifies 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 RF_VPN_V4 or RF_VPN_V6.

  `vrf_del`(route_dist)

    This method deletes the existing vrf.

    `route_dist` specifies a route distinguisher value.

class `ryu.services.protocols.bgp.bgpspeaker.``EventPrefix`(remote_as, route_dist, prefix, nexthop, label, 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 prefix
  is_withdraw | True if this prefix has gone otherwise False

class `ryu.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 | PrefixFilter.POLICY.PERMIT or 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 `ryu.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 | ASPathFilter.POLICY_TOP and ASPathFilter.POLICY_END, ASPathFilter.POLICY_INCLUDE and ASPathFilter.POLICY_NOT_INCLUDE are available.

  Meaning of each policy is as follows;

  - 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 `ryu.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.