Using ARouteServer as a library

External programs can take advantage of ARouteServer’s features to automatically build route server configurations by using the following builder classes:

• BIRDConfigBuilder

• OpenBGPDConfigBuilder

How to use it

The __init__ method takes care of initializing the builder object; this method also gathers any external information needed by the input route server configuration.

ConfigBuilder.__init__(template_dir=None, template_name=None, cache_dir=None, cache_expiry={'arin_whois_db_dump': 43200, 'general': 43200, 'irr_as_sets': 43200, 'pdb_info': 86400, 'registrobr_whois_db_dump': 43200, 'ripe_rpki_roas': 3600}, bgpq3_path='bgpq4', bgpq3_host=['rr.ntt.net', 'rr1.ntt.net'], bgpq3_sources='RIPE,APNIC,AFRINIC,ARIN,NTTCOM,ALTDB,BBOI,BELL,JPIRR,LEVEL3,RADB,TC', bgpq3_timeout=120, rtt_getter_path=None, threads=4, ip_ver=None, perform_graceful_shutdown=False, ignore_errors=[], live_tests=False, local_files=[], local_files_dir=None, target_version=None, cfg_general=None, cfg_bogons=None, cfg_clients=None, **kwargs)

Initialize the configuration builder.

Here, external data sources are also queried to enrich the configuration with additional data (PeeringDB records, ASNs and prefixes from IRRDBs, …).

Raises:

ARouteServerError or derived exceptions – (from pierky.arouteserver.errors). Exceptions raised here can have no arguments and their string representation can be empty: in these cases, it means that one or more errors have been logged using the logging module.

Parameters:

• template_dir (str) –

  the directory that contains the templates that must be used to render the output configuration.

  Example: /home/user/arouteserver/templates/bird

  Same of:

  • –templates-dir CLI argument.

  • templates_dir program’s configuration file option.

• template_name (str) –

  the name of the file that must be used to render the output configuration.

  Example: main.j2

  Same of:

  • –template-file-name CLI argument.

  • template_name program’s configuration file option.

• cfg_general (str) –

• cfg_clients (str) –

• cfg_bogons (str) –

  paths to the YAML files containing the general route server policy, the clients list and the list of bogon prefixes.

  Example: cfg_general="/home/user/arouteserver/general.yml"

  Same of:

  • –general, –clients, –bogons CLI arguments.

  • cfg_general, cfg_clients, cfg_bogons program’s configuration file options.

• cache_dir (str) –

  the directory that will be used to store results from external data sources queries (PeeringDB info, IRRDBs).

  Same of:

  • –cache-dir CLI argument.

  • cache_dir program’s configuration file option.

• cache_expiry (int or dict) –

  how long cached data must be considered valid, in seconds. Each “cacheable object” (PeeringDB info, IRR datasets, …) can have its own expiry time. If an int is given here, all the expiry times will have the same duration, otherwise cacheable objects will pick their specific value or use the ‘general’ one if no more specific value is given.

  Same of:

  • cache_expiry program’s configuration file option.

• ip_ver (int) –

  if None, the output configuration will be targeted for both IPv4 and IPv6; otherwise, set this to 4 or to 6 to obtain AFI-specific output configuration.

  Same of:

  • –ip-ver CLI argument.

• perform_graceful_shutdown (bool) –

  when True, the output config includes an outbound policy which is applied to BGP sessions toward the clients and which adds the GRACEFUL_SHUTDOWN BGP community (65535:0) to all the routes that the route server announces to them.

  Same of:

  • –perform-graceful-shutdown CLI argument.

• target_version (str) –

  the BGP daemon target version for which the output configuration must be generated.

  This is used to detect and/or solve any compatibility issue with some features that are available only using a specific version of the target BGP daemon.

  The list of available versions is taken from the derived BGP daemon specific classes’ AVAILABLE_VERSION attribute.

  The default value is taken from the derived BGP daemon specific classes’ DEFAULT_VERSION attribute.

  Example: on OpenBGPD, to avoid errors when building configs that use large BGP communities (available only on OpenBGPD/OpenBSD > 6.1) use target_version="6.1"

  Same of:

  • –target-version CLI argument.

• ignore_errors (list) –

  a list of issue IDs (strings) that must be ignored when building the configuration.

  Depending on the target BGP daemon and its version, some features may be unavailable; ARouteServer produces errors when one or more of these features are enabled in the route server configuration YAML file. These errors are marked with an ‘issue ID’ that can be reported in this list to instruct ARouteServer to ignore it and to continue the building process.

  Use ignore_errors=["*"] to ignore any issue.

  Example: ignore_errors=["add_path"] to ignore the issue due to the lack of support for ADD_PATH in OpenBGPD.

  Same of:

  • –ignore-issues CLI argument.

• local_files (list) –

  the list of local files IDs for which the relative inclusion point must be enabled on the output configuration. Details: https://arouteserver.readthedocs.io/en/latest/CONFIG.html#site-specific-custom-configuration-files

  The list of available IDs is taken from the derived BGP daemon specific classes’ LOCAL_FILES_IDS attribute.

  Example: local_files=["header4", "footer4"]

  Same of:

  • –use-local-files CLI argument.

• local_files_dir (str) –

  the base directory of the local files that will be included in the output configuration.

  The default value is taken from the derived BGP daemon specific classes’ LOCAL_FILES_BASE_DIR attribute.

  Example: /etc/bird

  Same of:

  • –local-files-dir CLI argument.

• bgpq3_path (str) –

  path to the ‘bgpq3’ or ‘bgpq4’ external program; this will be used to expand AS macros and to obtain the list of authorized origin ASNs and prefixes from IRRDBs.

  Same of:

  • bgpq3_path program’s configuration file option.

• bgpq3_host (str) –

  the host(s) that will be queried by bgpq3/bgpq4; this will be used to set the -h argument of the program. Multiple hosts can be passed using a comma-delimited string, in which case they will be used sequentially in case of failures of the IRR queries or timeouts.

  Same of:

  • bgpq3_host program’s configuration file option.

• bgpq3_sources (str) –

  a comma separated list of sources that will be used by the bgpq3/bgpq4 program; this will be used to set the -S argument of the program.

  Same of:

  • bgpq3_sources program’s configuration file option.

• bgpq3_timeout (int) –

  timeout for the bgpq4/bgpq3 queries (in seconds).

  Same of:

  • bgpq3_timeout program’s configuration file option.

• rtt_getter_path (str) –

  path to the program that is executed to determine the RTT of a peer. Syntax and details can be found at the following URL: https://arouteserver.readthedocs.io/en/latest/RTT_GETTER.html

  Same of:

  • rtt_getter_path program’s configuration file option.

• threads (int) –

  number of concurrent threads used to gather additional data from external sources (bgpq3/bgpq4, PeeringDB, …)

  Same of:

  • threads program’s configuration file option.

• kwargs – additional arguments used by BGP daemon specific builder classes.

• live_tests (bool) – only used on live tests.

The render_template method generates the output configuration.

ConfigBuilder.render_template(output_file=None)

Render the output configuration.

Raises:

ARouteServerError or derived exceptions – (from pierky.arouteserver.errors). Exceptions raised here can have no arguments and their string representation can be empty: in these cases, it means that one or more errors have been logged using the logging module.

Parameters:

output_file (file) – the output file where the configuration must be written.

Example:

import sys
from pierky.arouteserver.builder import BIRDConfigBuilder
builder = BIRDConfigBuilder(
        template_dir="~/arouteserver/templates/bird",
        template_name="main.j2",
        cfg_general="~/arouteserver/config.d/general.yml",
        cfg_clients="~/arouteserver/config.d/clients.yml",
        cfg_bogons="~/arouteserver/config.d/bogons.yml",
        cache_dir="~/arouteserver/var",
        ip_ver=4
)
builder.render_template(sys.stdout)

BGP daemon specific builder classes

class pierky.arouteserver.builder.BIRDConfigBuilder(template_dir=None, template_name=None, cache_dir=None, cache_expiry={'arin_whois_db_dump': 43200, 'general': 43200, 'irr_as_sets': 43200, 'pdb_info': 86400, 'registrobr_whois_db_dump': 43200, 'ripe_rpki_roas': 3600}, bgpq3_path='bgpq4', bgpq3_host=['rr.ntt.net', 'rr1.ntt.net'], bgpq3_sources='RIPE,APNIC,AFRINIC,ARIN,NTTCOM,ALTDB,BBOI,BELL,JPIRR,LEVEL3,RADB,TC', bgpq3_timeout=120, rtt_getter_path=None, threads=4, ip_ver=None, perform_graceful_shutdown=False, ignore_errors=[], live_tests=False, local_files=[], local_files_dir=None, target_version=None, cfg_general=None, cfg_bogons=None, cfg_clients=None, **kwargs)

BIRD configuration builder.

The kwargs parameter of the __init__ method can be used to pass the following additional arguments.

Parameters:

hooks (list) – list of hook IDs for which to enable hooks in the output configuration. Details: https://arouteserver.readthedocs.io/en/latest/CONFIG.html#bird-hooks

AVAILABLE_VERSION = ['1.6.3', '1.6.4', '1.6.6', '1.6.7', '1.6.8', '2.0.7', '2.0.7+b962967e', '2.0.8', '2.0.9', '2.0.10', '2.0.11', '2.13', '2.14', '2.15', '3.0']

DEFAULT_VERSION = '2.15'

HOOKS = ['pre_receive_from_client', 'post_receive_from_client', 'pre_announce_to_client', 'post_announce_to_client', 'route_can_be_announced_to', 'announce_rpki_invalid_to_client', 'scrub_communities_in', 'scrub_communities_out', 'apply_blackhole_filtering_policy']

LOCAL_FILES_BASE_DIR = '/etc/bird'

LOCAL_FILES_IDS = ['logging', 'header', 'header4', 'header6', 'footer', 'footer4', 'footer6', 'client', 'client4', 'client6']

class pierky.arouteserver.builder.OpenBGPDConfigBuilder(template_dir=None, template_name=None, cache_dir=None, cache_expiry={'arin_whois_db_dump': 43200, 'general': 43200, 'irr_as_sets': 43200, 'pdb_info': 86400, 'registrobr_whois_db_dump': 43200, 'ripe_rpki_roas': 3600}, bgpq3_path='bgpq4', bgpq3_host=['rr.ntt.net', 'rr1.ntt.net'], bgpq3_sources='RIPE,APNIC,AFRINIC,ARIN,NTTCOM,ALTDB,BBOI,BELL,JPIRR,LEVEL3,RADB,TC', bgpq3_timeout=120, rtt_getter_path=None, threads=4, ip_ver=None, perform_graceful_shutdown=False, ignore_errors=[], live_tests=False, local_files=[], local_files_dir=None, target_version=None, cfg_general=None, cfg_bogons=None, cfg_clients=None, **kwargs)

OpenBGPD configuration builder.

AVAILABLE_VERSION = ['7.0', '7.1', '7.2', '7.3', '7.4', '7.5', '7.6', '7.7', '7.8', '8.0', '8.3', '8.4']

DEFAULT_VERSION = '8.4'

LOCAL_FILES_BASE_DIR = '/etc/bgpd'

LOCAL_FILES_IDS = ['logging', 'header', 'pre-irrdb', 'post-irrdb', 'pre-clients', 'post-clients', 'client', 'pre-filters', 'post-filters', 'footer']