Live tests code documentation
- class pierky.arouteserver.tests.live_tests.base.LiveScenario(methodName='runTest')
An helper class to run tests for a given scenario.
This class must be derived by scenario-specific classes that must:
set the
MODULE_PATH
attribute to__file__
, in order to correctly locate files needed by the scenario.fill the
INSTANCES
list with a list ofBGPSpeakerInstance
(or derived) instances representing all the BGP speakers involved in the scenario.set the
SHORT_DESCR
with a short description of the scenario; it will be used to print tests description in the format “<SHORT_DESCR>: <test function docstring>”.fill the
DATA
dictionary with IP prefixes IDs that represent all the IP addresses used by the scenario; this is useful to decouple real IP addresses from what they represent or are used to and to have a single definition of the tests functions and scenario configuration that can be used for both IPv4 and IPv6 tests.Example:
DATA = { "rs_IPAddress": "192.0.2.2", "AS1_IPAddress": "192.0.2.11", "AS1_allowed_prefixes": "1.0.0.0/8", "AS1_good_prefix": "1.0.1.0/24", "AS101_prefixes": "101.0.0.0/8" }
optionally, if it’s needed by the scenario, the derived classes must also fill the
AS_SET
andR_SET
dictionaries with the expected content of any expanded AS-SETs used in IRRDB validation:AS_SET
’s items must be in the format<AS_SET_name>: <list_of_authorized_origin_ASNs>
.R_SET
’s items must be in the format<AS_SET_name>: <list_of_authorized_prefix_IDs>
(where prefix IDs are those reported in theDATA
dictionary).
Example:
AS_SET = { "AS-AS1": [1], "AS-AS1_CUSTOMERS": [101], "AS-AS2": [2], "AS-AS2_CUSTOMERS": [101] } R_SET = { "AS-AS1": [ "AS1_allowed_prefixes" ], "AS-AS1_CUSTOMERS": [ "AS101_prefixes" ] }
optionally, if it’s needed by the scenario, the derived classes can also set the
RTT
dictionary with the values of the RTTs of the clients. Keys can be IP addresses of clients or the prefix IDs used in theDATA
dictionary to represent them.Example:
RTT = { "192.0.2.11": 14, "2001:db8::11": 165, "AS1_IPAddress": 44 }
optionally, if it’s needed by the scenario, the derived classes can also set the
REJECT_CAUSE_COMMUNITY
attribute with the pattern followed by BGP communities used to tag routes that are considered to be rejected (see thefiltering.reject_policy
general configuration section and thereject_cause
community). The value of this attribute must be a regular expression that matches the standard, extended or large BGP communities used to tag invalid routes. For example, if the standard BGP community65520:dyn_val
is used, the value must be^65520:(\d+)$
. If this attribute is not None, routes that have LOCAL_PREF == 1 and thereject_cause
BGP community withdyn_val == 0
are considered as filtered. TheREJECTED_ROUTE_ANNOUNCED_BY_COMMUNITY
attribute can also be set to match the community used to track the announcing ASN of invalid routes.implement the
set_instance_variables
method, used to set local instance attributes for the instances used within the tests functions.Example:
def set_instance_variables(self): self.AS1 = self._get_instance_by_name("AS1") self.AS2 = self._get_instance_by_name("AS2") self.AS131073 = self._get_instance_by_name("AS131073") self.rs = self._get_instance_by_name("rs")
Set the
__test__
attribute of derived classes to False to avoid them to be used directly bypytest
to run tests; only the specific IPv4/IPv6 class (the one where theDATA
dictionary is set) must have__test__
== True.- classmethod build_other_cfg(tpl_name)
Builds configuration files for BGP speakers which are not the route server.
- Parameters:
tpl_name (str) – the name of the Jinja2 template file relative to the scenario directory.
- Returns:
the path of the local rendered file.
To render the template, one attribute is used and consumed by Jinja2:
data
, the scenario’sDATA
dictionary.
The resulting file is saved into the local
var
directory and its absolute path is returned.
- classmethod build_rs_cfg(tpl_dir_name, tpl_name, out_file_name, ip_ver, cfg_general=None, cfg_bogons='bogons.yml', cfg_clients='clients.yml', **kwargs)
Builds configuration file for the route server.
- Parameters:
tpl_dir_name (str) – the directory where Jinja2 templates are located, relative to the current scenario.
tpl_name (str) – the name of the template to be rendered.
out_file_name (str) – the name of the destination file.
ip_ver (int) – the IP version for which this route server will operate. Use None if the configuration is valid for both IPv4 and IPv6.
cfg_general (str), cfg_bogons (str), cfg_clients (str) – the name of the 3 main files containing route server’s options and policies, clients definition and bogons IP addresses. File names are relative to the scenario directory.
- Returns:
the path of the local rendered file.
The resulting file is saved into the local
var
directory and its absolute path is returned.
- log_contains(inst, msg, instances={}, opposite=False)
Test if the BGP speaker’s log contains the expected message.
This only works for BGP speaker instances that support message logging: currently only BIRD.
If no log entries are found, the
TestCase.fail()
method is called and the test fails. Ifopposite
isTrue
, the failure is reported if a log entry is found.- Parameters:
inst – the
BGPSpeakerInstance
instance where the expected message is searched on.msg (str) – the text that is expected to be found within BGP speaker’s log.
instances (dict) – a dictionary of pairs “<macro>: <BGPSpeakerInstance>” used to expand macros on the msg argument. Macros are expanded using the BGP speaker’s specific client ID or protocol name.
opposite (bool) – when set to True, the call fails if a match is found.
Example
Given self.rs the instance of the route server, and self.AS1 the instance of one of its clients, the following code expands the “{AS1}” macro using the BGP speaker specific name for the instance self.AS1 and then looks for it within the route server’s log:
self.log_contains(self.rs, "{AS1} bad ASN", {"AS1": self.AS1})
On BIRD, “{AS1}” will be expanded using the “protocol name” that BIRD uses to identify the BGP session with AS1.
- receive_route(inst, prefix, other_inst=None, as_path=None, next_hop=None, std_comms=None, lrg_comms=None, ext_comms=None, local_pref=None, as_set=None, otc=None, filtered=None, only_best=None, reject_reason=None)
Test if the BGP speaker receives the expected route(s).
If no routes matching the given criteria are found, the
TestCase.fail()
method is called and the test fails.- Parameters:
inst – the
BGPSpeakerInstance
instance where the routes are searched on.prefix (str) – the IPv4/IPv6 prefix of the routes to search for.
other_inst – if given, only routes received from this
BGPSpeakerInstance
instance are considered.as_path (str) – if given, only routes with this AS_PATH are considered.
next_hop – can be a string or a
BGPSpeakerInstance
instance; if given, only routes that have a NEXT_HOP address matching this one are considered.std_comms (list) – if given, only routes that carry these BGP communities are considered. Use an empty list ([]) to consider only routes with no BGP comms.
lrg_comms (list) – if given, only routes that carry these BGP communities are considered. Use an empty list ([]) to consider only routes with no BGP comms.
ext_comms (list) – if given, only routes that carry these BGP communities are considered. Use an empty list ([]) to consider only routes with no BGP comms.
local_pref (int) – if given, only routes with local-pref equal to this value are considered.
as_set (str) – if given, only routes with this AS_SET are considered.
otc (int) – if provided, only routes with the OTC attribute set to this value are considered. Use ‘0’ to match only routes NOT having the OTC value set.
filtered (bool) – if given, only routes that have been (not) filtered are considered.
only_best (bool) – if given, only best routes are considered.
reject_reason (int) –
valid only if filtered is True: if given the route must be reject with this reason code. It can be also a set of codes: in this case, the route must be rejected with one of those codes.
The list of valid codes is reported in docs/CONFIG.rst or at https://arouteserver.readthedocs.io/en/latest/CONFIG.html#reject-policy
- session_exists(inst_a, inst_b_or_ip)
Test if a BGP session between the two instances exists.
- Parameters:
inst_a – the
BGPSpeakerInstance
instance where the BGP session is looked for.inst_b_or_ip – the
BGPSpeakerInstance
instance or an IP address that inst_a is expected to peer with.
- session_is_up(inst_a, inst_b)
Test if a BGP session between the two instances is up.
If a BGP session between the two instances is not up, the
TestCase.fail()
method is called and the test fails.- Parameters:
inst_a – the
BGPSpeakerInstance
instance where the BGP session is looked for.inst_b – the
BGPSpeakerInstance
instance that inst_a is expected to peer with.
- test_999_log_contains_errors()
{}: log contains errors
- classmethod use_static_file(local_filename)
Prepare the local file in order to use it later.
- Parameters:
filename (str) – the name of the local file, relative to the scenario directory.
- Returns:
the path of the file to be used
- class pierky.arouteserver.tests.live_tests.base.LiveScenario_TagAndRejectRejectPolicy
Same as LiveScenario_TagRejectPolicy, but with ‘tag_and_reject’ reject policy.
- class pierky.arouteserver.tests.live_tests.base.LiveScenario_TagRejectPolicy
Helper class to run a scenario as if reject_policy is set to ‘tag’.
When a scenario inherits this class, its route server is configured as if the
reject_policy.policy
istag
, the65520:dyn_val
value is used for thereject_cause
BGP community and the65524:dyn_val
andrt:65524:dyn_val
values for therejected_route_announced_by
one. Additionally, using thereject_cause_map
, some reject codes are mapped to specific BGP communities in thers_as:1101:*
range.The
general.yml
file, or the file given in theorig_file
argument of_get_cfg_general
method, is cloned and reconfigured with the aforementioned settings.This class is mostly used for OpenBGPD tests since the underlaying mechanism allows to track the reason that brought to consider the route as rejected and to test filters out during test cases execution.
This class should be used in multiple inheritance:
Example
class SkeletonScenario_OpenBGPDIPv4(LiveScenario_TagRejectPolicy, SkeletonScenario):
- class pierky.arouteserver.tests.live_tests.instances.BGPSpeakerInstance(name, ip, mount=[], **kwargs)
This class abstracts a BGP speaker instance.
Currently, the
start
,stop
,is_running
andrun_cmd
methods inherited from BaseInstance are implemented by theDockerInstance
andKVMInstance
derived classes, while therestart
,reload_config
,get_bgp_session
,get_routes
andlog_contains
methods by the [Docker|KVM]Instance-derivedBIRDInstance
andOpenBGPDInstance
classes.- bgp_session_is_up(other_inst, force_update=False)
Check if a BGP session with
other_inst
is up.- Parameters:
other_inst – the
BGPSpeakerInstance
instance that the current instance is expected to have a running BGP session with.force_update (bool) – if True, the instance must bypass any caching mechanism used to keep the BGP sessions status.
- Returns:
True if the current instance has a running BGP session with
other_inst
; False otherwise.
- clear_cached_routes()
Clear any internal cache where routes may be stored.
- get_bgp_session(other_inst, force_update=False)
Get information about the BGP session with
other_inst
.- Parameters:
other_inst – the
BGPSpeakerInstance
instance that the current instance is expected to have a running BGP session with.force_update (bool) – if True, the instance must bypass any caching mechanism used to keep the BGP sessions status.
- Returns:
None if the BGP session is not found, otherwise a dictionary containing information about the BGP session:
”ip”: “neighbor IP address”,
”is_up”: [True|False]
- get_routes(prefix, include_filtered=False, only_best=False)
Get a list of all the known routes for
prefix
.- Parameters:
prefix (str) – the IP prefix that returned routes must match. If None, all the routes are returned.
include_filtered (bool) – include filtered routes / rejected prefixes in the result.
only_best (bool) – include only the best route toward
prefix
.
- Returns:
list of
Route
objects.
- log_contains(s)
Verifies if the BGP speaker’s logs contain the expected message.
- Parameters:
s (str) – the message that is expected to be found in the BGP speaker’s logs.
- Returns:
True or False if the message is found or not.
- log_contains_errors(allowed_errors=[], list_errors=False)
Returns True if the BGP speaker’s log contains warning/errors.
- Parameters:
allowed_errors (list) – list of strings representing errors that are allowed to be found within the BGP speaker’s log.
list_errors (bool) – when set to True, the functions returns a touple (errors_found, list_of_errors).
- Returns:
True of False if error messages or warnings are found within the BGP speaker’s logs. When
list_errors
is True, a touple (bool, str).- Return type:
When
list_errors
is False
- exception pierky.arouteserver.tests.live_tests.instances.InstanceError
- exception pierky.arouteserver.tests.live_tests.instances.InstanceNotRunning(name, *args, **kwargs)
- class pierky.arouteserver.tests.live_tests.instances.Route(prefix, **kwargs)
Details about a route.
- prefix
the IPv4/IPv6 prefix.
- Type:
str
- via
the IP address of the peer from which the route has been received.
- Type:
str
- as_path
the AS_PATH attribute of the route, in the “<asn> <asn> <asn>…” format (example: “1 2 345”).
- Type:
str
- next_hop
the NEXT_HOP attribute of the route.
- Type:
str
- filtered
True if the route has been rejected/filtered.
- Type:
bool
- std_comms
list of standard BGP communities (strings in the “x:y” format).
- Type:
list
- lrg_comms
list of large BGP communities (strings in the “x:y:z” format).
- Type:
list
- ext_comms
list of extended BGP communities (strings in the “[rt|ro]:x:y” format).
- Type:
list
- localpref
local-pref.
- Type:
int
- otc
the OTC (Only To Customer) attribute, if present.
- Type:
int
- reject_reasons
list of integers that identify the reasons for which the route is considered to be rejected.
- Type:
list
- class pierky.arouteserver.tests.live_tests.bird.BIRD2Instance(*args, **kwargs)
- class pierky.arouteserver.tests.live_tests.bird.BIRD3Instance(*args, **kwargs)
- class pierky.arouteserver.tests.live_tests.bird.BIRDInstance(*args, **kwargs)
This class implements BIRD-specific methods.
This class is derived from
DockerInstance
, that implements some Docker-specific methods to start/stop the instance and to run commands on it.- clear_cached_routes()
Clear any internal cache where routes may be stored.
- get_bgp_session(other_inst_or_ip, force_update=False)
Get information about the BGP session with
other_inst
.- Parameters:
other_inst – the
BGPSpeakerInstance
instance that the current instance is expected to have a running BGP session with.force_update (bool) – if True, the instance must bypass any caching mechanism used to keep the BGP sessions status.
- Returns:
None if the BGP session is not found, otherwise a dictionary containing information about the BGP session:
”ip”: “neighbor IP address”,
”is_up”: [True|False]
- get_routes(prefix, include_filtered=False, only_best=False)
Get a list of all the known routes for
prefix
.- Parameters:
prefix (str) – the IP prefix that returned routes must match. If None, all the routes are returned.
include_filtered (bool) – include filtered routes / rejected prefixes in the result.
only_best (bool) – include only the best route toward
prefix
.
- Returns:
list of
Route
objects.
- log_contains(s)
Verifies if the BGP speaker’s logs contain the expected message.
- Parameters:
s (str) – the message that is expected to be found in the BGP speaker’s logs.
- Returns:
True or False if the message is found or not.
- log_contains_errors(allowed_errors=[], list_errors=False)
Returns True if the BGP speaker’s log contains warning/errors.
- Parameters:
allowed_errors (list) – list of strings representing errors that are allowed to be found within the BGP speaker’s log.
list_errors (bool) – when set to True, the functions returns a touple (errors_found, list_of_errors).
- Returns:
True of False if error messages or warnings are found within the BGP speaker’s logs. When
list_errors
is True, a touple (bool, str).- Return type:
When
list_errors
is False
- reload_config()
Reload BIRD configuration.
It runs the “[birdcl/birdcl6] configure” command to reload BIRD’s configuration.
- restart()
Restart BIRD.
It runs the “[birdcl/birdcl6] configure” and “restart all” commands.
- class pierky.arouteserver.tests.live_tests.bird.BIRDInstanceIPv4(*args, **kwargs)
- class pierky.arouteserver.tests.live_tests.bird.BIRDInstanceIPv6(*args, **kwargs)