Route server configuration - options and features

This is the reStructuredText representation of the content of the general.yml configuration file.

Here you can find all the options and settings that can be configured on a route server by using this tool, along with the comments needed to understand how to properly edit that file.

The YAML version of the general.yml configuration file can be found on GitHub.

General options: cfg

  • rs_as: The route server AS number.

    Example:

    rs_as: 999
    
  • router_id: The route server’s router ID.

    This can be set using a single router ID or a list of multiple router IDs. If multiple values are provided, then a single execution of ARouteServer will generate multiple configurations, one for each router ID, all having the same characteristics, but just a different value for the “router ID” setting of the target BGP daemon.

    More details on the Configuration page on ReadTheDocs: https://arouteserver.readthedocs.io/en/latest/CONFIG.html

    Example of how to configure multiple values: router_id: [“192.0.2.2”, “192.0.2.3”]

    Example:

    router_id: "192.0.2.2"
    
  • prepend_rs_as: Prepend the route server’s AS number to the AS_PATH of routes that it announces to clients. https://tools.ietf.org/html/rfc7947#section-2.2.2.1

    Can be overwritten on a client-by-client basis.

    Default: False

    Example:

    prepend_rs_as: False
    
  • path_hiding: Path-hiding mitigation technique: if True, enable path hiding mitigation. (https://tools.ietf.org/html/rfc7947#section-2.3.1)

    BIRD: the “secondary” option is used. “Usually, if an export filter rejects a selected route, no other route is propagated for that network. This option allows to try the next route in order until one that is accepted is found or all routes for that network are rejected.” (http://bird.network.cz/?get_doc&f=bird-6.html#bgp-secondary)

    OpenBGPD: ‘rde evaluate all’ is used. (https://man.openbsd.org/bgpd.conf#rde)

    Default: True

    Example:

    path_hiding: True
    
  • passive: Configure passive sessions.

    Can be overwritten on a client-by-client basis.

    Default: True

    Example:

    passive: True
    
  • multihop: Configure sessions as multihop. To be set with the maximum TTL permitted.

    BIRD: this option can be used only when path_hiding is False for the whole configuration.

    Can be overwritten on a client-by-client basis.

    Default: not set.

    Example:

    multihop: 0
    
  • gtsm: Use GTSM (Generalized TTL Security Mechanism). https://tools.ietf.org/html/rfc5082

    Can be overwritten on a client-by-client basis.

    Default: False

    Example:

    gtsm: False
    
  • add_path: Use ADD-PATH (RFC7911). The route server will be configured as “able to send multiple paths to its peer”.

    OpenBGPD: supported only from version 7.5.

    Can be overwritten on a client-by-client basis.

    Default: False

    Example:

    add_path: False
    
  • rfc8950: Support IPv6 next-hop for IPv4 NLRI (RFC8950). Will only be enabled for IPv6 BGP sessions. https://tools.ietf.org/html/rfc8950

    BIRD: enables extended next-hop (available since 2.0)

    OpenBGPD: not yet supported

    Can be overwritten on a client-by-client basis.

    Default: False

    Example:

    rfc8950: False
    

Filtering: filtering

NEXT_HOP: next_hop

NEXT_HOP checks

  • policy: The policy option can be set using the following values:

    • strict: “check that the BGP NEXT_HOP attribute for BGP routes received from a route server client matches the interface address of the client.”

    • same-as: permit next-hop rewriting for the same AS; this “allows an organization with multiple connections into an IXP configured with different IP addresses to direct traffic off the IXP infrastructure through any of their connections for traffic engineering or other purposes.” In this mode, all the IP addresses of clients that fall under the same ASN will be allowed. This is limited to the IP addresses of known clients configured in the clients.yml file.

    • authorized_addresses: check that the BGP NEXT_HOP attribute for routes received from a route server client matches one of the IP addresses reported in the client-specific authorized_addresses_list option. This allows a route server client to announce routes whose NEXT_HOP attribute is the IP address of a non-client router. The authorized_addresses_list option must be configured in the clients.yml file for those clients that have policy set to authorized_addresses.

    https://tools.ietf.org/html/rfc7948#section-4.8

    Can be overwritten on a client-by-client basis.

    Default: strict

    Example:

    policy: "strict"
    

Prefix length: ipv4_pref_len and ipv6_pref_len

Min and max prefix length for IPv4 and IPv6 prefixes accepted by the route server. Boundaries are inclusive.

Can be overwritten on a client-by-client basis.

Default: 8-24 for IPv4, 12-48 for IPv6

Filtered prefixes: global_black_list_pref

List of prefixes that are unconditionally rejected. For example: local networks.

A list of prefixes is expected to be found here, like the one reported in the bogons.yml file.

Default: none

Example:

global_black_list_pref:
   - prefix: "192.0.2.0"
     length: 24
     comment: "Local network"

Max AS_PATH length: max_as_path_len

Max length of AS_PATH attribute.

Can be overwritten on a client-by-client basis.

Default: 32

Example:

max_as_path_len: 32

Invalid ASNs in AS_PATH: reject_invalid_as_in_as_path

Reject routes that carry private/invalid AS numbers in their AS_PATH. http://mailman.nanog.org/pipermail/nanog/2016-June/086078.html

Can be overwritten on a client-by-client basis.

Default: True

Example:

reject_invalid_as_in_as_path: True

Transit-free networks: transit_free

Transit-free networks’ ASNs should appear in AS_PATH only in the left-most position.

  • action: If a policy is given here, it is applied to routes whose AS_PATH contains one of the following ASN in any position different from the first:

    • reject: the route is discarded.

    • warning: a warning is logged.

    OpenBGPD: used only if action is reject.

    Default: none

    Example:

    action: "reject"
    
  • asns: Comma separated list of ASNs which are considered transit-free. Used only if an action is provided above.

    Example:

    asns: >
         174, 701, 1299, 2914, 3257, 3320, 3356, 5511, 6453,
         6461, 6762, 6830, 7018, 12956
    

‘Never via route-servers’ networks: never_via_route_servers

Similarly to what happens with the transit_free config knob, any route with one of these ASNs in the AS_PATH will be rejected. If the peering_db option below within this section is set to True, ARouteServer acquires the list of ASNs from PeeringDB (based on the info_never_via_route_servers attribute). If peering_db is False and asns is not set or empty, the feature will be implicitly disabled.

  • peering_db: When set to True, the list of networks is automatically retrieved from PeeringDB.

    Default: True

    Example:

    peering_db: True
    
  • asns: Comma separated list of ASNs which will be used to filter incoming routes. When peering_db is True, the ASNs listed here are added to those retrieved from PeeringDB.

    Default: none

IRRDB filters: irrdb

With regards of the following two options, if no AS-SET is given in the clients configuration file for the specific client nor for its AS, then only the ASN of the announcing client is expanded and used to gather authorized origin ASNs and prefixes. If the peering_db option below within this section is set to True, ARouteServer acquires the AS-SET of the client ASN from PeeringDB.

More details on the Configuration page on ReadTheDocs: https://arouteserver.readthedocs.io/en/latest/CONFIG.html

  • enforce_origin_in_as_set: Accept only routes whose origin ASN is registered in the expanded AS-SET of the announcing client.

    Can be overwritten on a client-by-client basis.

    Default: True

    Example:

    enforce_origin_in_as_set: True
    
  • enforce_prefix_in_as_set: Accept only prefixes which are present in the expanded AS-SET of the announcing client.

    Can be overwritten on a client-by-client basis.

    Default: True

    Example:

    enforce_prefix_in_as_set: True
    
  • allow_longer_prefixes: By default, only prefixes that have a strict correspondence in the route-set obtained by expading the AS-SET are allowed. If this is set to True, more specific prefixes that don’t have a strict correspondence with but that are covered by a prefix from the route-set are accepted as well.

    Default: False

    Example:

    allow_longer_prefixes: False
    
  • tag_as_set: Tag routes whose prefix is (not) present in a client’s AS-SET. If a client’s enforce_[origin|prefix]in_as_set is True then unauthorized routes are rejected and not tagged (unless they match a client-level white_list_route entry). BGP communities used to tag these routes are:

    • [origin|prefix]_(not_)present_in_as_set

    • prefix_validated_via_rpki_roas

    • prefix_validated_via_arin_whois_db_dump

    • prefix_validated_via_registrobr_whois_db_dump

    • route_validated_via_white_list (only for routes validated solely because of a client-level white_list_route entry)

    Default: True

    Example:

    tag_as_set: True
    
  • peering_db: If this option is set to True and no AS-SETs are given for a client nor for its ASN then ARouteServer tries to acquire the AS-SET from PeeringDB. Please note that data quality in PeeringDB has large variations; setting this option to True could lead to unwanted and unpredictable behaviours.

    Default: False

    Example:

    peering_db: False
    
  • use_rpki_roas_as_route_objects: With regards of prefix validation, when this option is enabled ARouteServer uses RPKI ROAs as if they were route objects. Routes whose origin ASN is authorized by a client’s AS-SET but whose prefix has not a corresponding route object will be accepted if a covering ROA exists for that origin ASN. In this case, if tag_as_set is True, these routes are tagged with the prefix_validated_via_rpki_roas community.

  • enabled: Set this to True to enable this feature.

    When enabled, the rpki_roas section must be configured in order to set the method used to gather RPKI ROAs.

    Default: False

    Example:

    enabled: False
    
  • use_arin_bulk_whois_data: Similarly to the use_rpki_roas_as_route_objects option, this one allows to back IRR filters up by using “Origin AS” data from an ARIN bulk Whois database dump. It is a dump of the whole ARIN Whois database that contains all the prefixes for which one or more authorized origin ASNs have been set by the resource holder. Routes whose origin ASN is authorized by a client’s AS-SET but whose prefix has not a corresponding route object will be accepted if an entry exists in this database for that origin ASN. In this case, if tag_as_set is True, these routes are tagged with the prefix_validated_via_arin_whois_db_dump community.

    The setting of the allow_longer_prefixes option will be honored.

    See also: https://mailman.nanog.org/pipermail/nanog/2017-December/093525.html

  • enabled: Set this to True to enable this feature.

    Please note that the ARIN Advisory Counsel recommended the ARIN Board of Trustees to deprecate the “ARIN AS Origins” feature in the ARIN WHOIS database. See https://www.arin.net/participate/policy/drafts/2021_8/ and also https://github.com/pierky/arouteserver/issues/116. Consequently, this feature will be removed in future releases of ARouteServer, and starting from v1.19.0 a warning message will be logged during the route server config generation process if it is enabled.

    Default: False

    Example:

    enabled: False
    
  • source: The source of the data must be set here.

    It can be an http:// or https:// URL or a local file path. The file must be in JSON format, according to the following schema:

    { “json_schema”: “0.0.2”, “source”: “ARIN-WHOIS”, “whois_records”: { “v4”: [{“originas”: “ASxxx”, “prefix”: “w.x.y.z/l”}], “v6”: [{“originas”: “ASxxx”, “prefix”: “a:b:c:d::/l”}] } }

    Optionally it can be compressed in BZ2 format. In that case the filename must end with the “.bz2” extension.

    The following script can be used to convert the original XML file provided by ARIN into the expected JSON format:

    https://github.com/NLNOG/arin-whois-bulk-parser

    Default: none

    Example:

    source: ""
    
  • use_registrobr_bulk_whois_data: Similarly to the use_arin_bulk_whois_data option, this one allows to back IRR filters up by using “Registro.br” data from the NIC.BR Whois database. In this case, if tag_as_set is True, these routes are tagged with the prefix_validated_via_registrobr_whois_db_dump community.

    The setting of the allow_longer_prefixes option will be honored.

  • enabled: Set this to True to enable this feature.

    Default: False

    Example:

    enabled: False
    
  • source: The source of the data must be set here.

    It can be an http://, https://, ftp:// URL or a local file path. The file must be in CSV format, with | as a field separator, accordingly to the following schema:

    ASxxx|Organization|OrgID|w.x.y.z/l|a:b:c:d::/l|…

    Default: URL of the dump published by Registro.br.

    Example:

    source: "ftp://ftp.registro.br/pub/numeracao/origin/nicbr-asn-blk-latest.txt"
    

RPKI BGP Origin Validation: rpki_bgp_origin_validation

  • enabled: Enable BGP Prefix Origin Validation for routes received from clients. https://tools.ietf.org/html/rfc6811

    When enabled, the rpki_roas section must be configured in order to set the method used to gather RPKI ROAs.

    Default: False

    Example:

    enabled: False
    
  • reject_invalid: If reject_invalid is True, when an INVALID route is received the route server rejects it. If it is False, INVALID routes are accepted and tagged with RFC8097 BGP communities for further internal processing or to be used by external custom functions implemented in .local files. In any case, INVALID routes are not announced to clients.

    Can be overwritten on a client-by-client basis.

    Default: True

    Example:

    reject_invalid: True
    

Max prefix: max_prefix

Dynamically adjust max-prefix limit of each client on the basis of the following criteria, in priority order:

  • client’s limit_ipv[4|6] configuration statement, if given;

  • client’s ASN PeeringDB record, if enabled by the peering_db option;

  • general limit set in general_limit_ipv[4|6], if given.

In the end, if no limit is found for a given AF or if it is 0, no max-prefix limit is configured for the specific client.

  • action: If action is not given, no max-prefix enforcement will be implemented.

    Action to be taken when the limit is hit by clients:

    • shutdown: the BGP session is disabled.

    • restart: the BGP session is restarted.

    • block: new routes are discarded.

    • warning: log a warning message.

    OpenBGPD: used only if action is shutdown or restart.

    Can be overwritten on a client-by-client basis.

    Default: none

    Example:

    action: "shutdown"
    
  • restart_after: OpenBGPD only: for the restart action, sessions will be restarted after restart_after minutes.

    Example:

    restart_after: 15
    
  • count_rejected_routes: BIRD only: when set to True, routes received by the route server and rejected by the filters are also counted towards the limit; when set to False, only routes that are accepted are taken into account. In OpenBGPD, the only available behaviour is to have the rejected routes counted towards the limit.

    Can be overwritten on a client-by-client basis.

    Example:

    count_rejected_routes: True
    
  • peering_db: Used to set client’s max-pref limit if limit_ipv[4|6] option is not given for the specific client.

  • enabled: If enabled is True and client’s max-pref limit is not set, ARouteServer fetches the limits from PeeringDB.

    Can be overwritten on a client-by-client basis.

    Default: True

    Example:

    enabled: True
    
  • increment: The following section can be used to accommodate cases of networks that fill the PeeringDB records using their exact route announcement count rather than a recommendation on what others should configure as max-prefix limit.

    The value that will be used is given by: (<PeeringDB value> + <absolute>) * (1 + <relative> / 100)

    Can be overwritten on a client-by-client basis.

  • absolute: Absolute increment in terms of number of prefixes.

    Default: 100

    Example:

    absolute: 100
    
  • relative: Relative increment in terms of percentage.

    Default: 15

    Example:

    relative: 15
    
  • general_limit_ipv4 and general_limit_ipv6: Used to set client’s max-pref limit if limit_ipv[4|6] option is not given for the specific client and if the PeeringDB option is disabled or a PeeringDB record can’t be found.

    Default: 170000 for IPv4 and 12000 for IPv6

    Example:

    general_limit_ipv4: 170000
    

RFC9234 roles: roles

Route leak prevention and detection using roles can be enabled here (https://www.rfc-editor.org/rfc/rfc9234). When enabled, the local role of BGP sessions will be set to “Route Server (RS)” and the role expected from client will be “Route Server Client (RS-Client)”. Unless strict-mode will be enabled, clients that do not announce any role will be handled in backward compatibility mode and sessions will be established regularly.

  • enabled: Enable the use of roles.

    Can be overwritten on a client-by-client basis.

    Also, the local role (route-server side) can be set on a client-by-client basis in the clients.yml file.

    OpenBGPD: this feature is available only from release 7.5, but its usage is discouraged by developers until 7.8. Details on https://github.com/openbgpd-portable/openbgpd-portable/issues/51

    BIRD: this feature is available only from release 2.0.11.

    Example:

    enabled: False
    
  • strict_mode: Configure RFC9234 “strict mode”, in which the receipt of a BGP Role Capability from the client is required. When operating in the “strict mode”, if the BGP Role Capability is sent but one is not received, the connection is rejected.

    Can be overwritten on a client-by-client basis.

    Default: False

    Example:

    strict_mode: False
    

Reject policy: reject_policy

  • policy: The route server can be configured to immediately discard the routes that are considered to be rejected or to keep them and tag them with a BGP community that describes the cause for which they are considered so. These routes are not propagated to other clients anyway, but they can be used for analysis, statistics or reports. A numeric value is used to identify the reason that led to consider them as invalid; this identifier is used in the last part of the reject_cause BGP community, that is finally attached to the route. The LOCAL_PREF attribute is also set to a value lower than the default one, to avoid invalid routes to be preferred over valid ones even in cases where path-hiding mitigation is not enabled.

    If policy is set to reject, invalid routes are immediately discarded as they enter the route server. If it is set to tag, they are tagged as described above (and not propagated anyway to other clients). In this case, the reject_cause BGP community must be also set. If it is set to tag_and_reject, they are tagged as in tag but also discarded as in reject mode.

    OpenBGPD: only reject and tag modes are allowed.

    Can be overwritten on a client-by-client basis.

    Default: reject

    Example:

    policy: "reject"
    

RPKI ROAs: rpki_roas

This section is used to configure how RPKI ROAs are gathered when filtering.irrdb.use_rpki_roas_as_route_objects or filtering.rpki_bgp_origin_validation are enabled.

  • source: The source used to gather RPKI ROAs.

    Can be one of the following options:

    • rtr: ROAs are loaded from an external RTR source. rtrllib (https://github.com/rtrlib/bird-rtrlib-cli) can be used for BIRD 1.6.x; in BIRD v2, v3 and OpenBGPD there is built-in support for the RTR protocol. The name of the table where send the ROAs to is RPKI for BIRD 1.6.x and RPKI4 and RPKI6 for BIRD v2 and v3. When the built-in implementation is used for OpenBGPD or BIRD v2/v3, an external file rpki_rtr_config.local must be found within the same directory where the main configuration file is stored (/etc/bird or /etc/bgpd usually) and must contain the configuration of the RTR sessions specific for that daemon. An example on how to setup that file can be found in the examples/rpki_rtr directory (please note, in order to use the RTR protocol BIRD must be compiled with –enable-libssh).

    • ripe-rpki-validator-cache: ROAs are loaded from a JSON file in RIPE NCC RPKI Validator cache format.

    Known compatible implementations at time of writing:

    Please note that the second method is far from guaranteeing that a cryptographically validated dataset is retrieved from a trusted cache, unless the URL of a local, trusted instance of a RPKI validator is provided below in the ripe_rpki_validator_url option.

    Default: ripe-rpki-validator-cache

    Example:

    source: "ripe-rpki-validator-cache"
    
  • ripe_rpki_validator_url: URLs of files in RIPE NCC RPKI Validator cache format. Meaningful only when source is ripe-rpki-validator-cache. Multiple URLs can be provided here; they will be tried in the same order in which they are listed below. They can be http:// or https:// URLs or paths of local files.

    Default: rpki-client instance, NTT instance, RIPE NCC instance

  • allowed_trust_anchors: When using the ripe-rpki-validator-cache source, only the following Trust Anchors will be taken into account.

    Values must be taken among those published in the RIPE RPKI Validator cache file configured above.

    Configured Trust Anchors pages:

    Before enabling any ARIN TA, please consider the following URLs:

    http://lists.arin.net/pipermail/arin-ppml/2017-January/031231.html

    https://www.arin.net/resources/rpki/rpa.pdf

    Default: APNIC, AfriNIC, LACNIC and RIPE NCC.

  • ignore_cache_files_older_than: When using the ripe-rpki-validator-cache source, ignore cache files that are older than this period of time (in seconds).

    When a file is ignored, the next source is used (from the ripe_rpki_validator_url list).

    Depending on the format of the cache file, the build time may be unavailable. At the moment, this information is known to be included in the rpki-client and OctoRPKI JSON formats, but not in the original RIPE NCC RPKI Validator format.

    Default: 6 hours (21600 seconds).

    Example:

    ignore_cache_files_older_than: 21600
    

Blackhole filtering: blackhole_filtering

Destination-based blackholing policy: if a policy is given, accept prefixes of any length if they are tagged with the blackholing BGP community and if they are “covered by an equal or shorter prefix that the neighboring network is authorized to advertise.” (https://tools.ietf.org/html/rfc7999#section-3.3).

  • policy_ipv4 and policy_ipv6: How to treat prefixes subject to blackhole filtering.

    If no policy is provided here then blackhole filtering is not implemented in the route server.

    Options:

    • propagate-unchanged: the route is accepted and propagated to clients unchanged. If missing, the BLACKHOLE well-known community 65535:666 is added. Other local blackholing communities are scrubbed. It’s up to the receiving client to accept the route and to discard traffic toward its prefix.

    • rewrite-next-hop: same behaviour of propagate-unchanged option; in addition, the route server rewrites the NEXT_HOP attribute of the advertised route with the address of the blackhole next-hop (BN). BN should have a unique MAC address determined by ARP/NDP used to filter L2 frames entering clients ports on the basis of their destination MAC address.

    Default: none

  • rewrite_next_hop_ipv4 and rewrite_next_hop_ipv6: IP addresses of BN used for rewrite-next-hop option:

    Default: none

    Example:

    rewrite_next_hop_ipv4: "192.0.2.66"
    
  • announce_to_client: How tagged routes should be propagated to clients. This configuration statement works together with the same client-level blackhole_filtering.announce_to_client option. If here announce_to_client is True, tagged routes are announced to clients unless they have their announce_to_client option explicitly set to False. If here announce_to_client is False, tagged routes are announced to clients only if they have the announce_to_client option explicitly set to True.

    Can be overwritten on a client-by-client basis.

    Default: True

    Example:

    announce_to_client: True
    
  • add_noexport: Automatically add the NO_EXPORT well-known community to tagged routes before announcing them to clients.

    Example:

    add_noexport: True
    

Graceful shutdown: graceful_shutdown

Graceful BGP session shutdown (gshut) can be configured here. When enabled is True, the route server processes the routes that are tagged with the GRACEFUL_SHUTDOWN BGP community (65535:0) accordingly to draft-ietf-grow-bgp-gshut, that is it lowers their LOCAL_PREF to the value set in local_pref. (https://tools.ietf.org/html/draft-ietf-grow-bgp-gshut-11)

  • enabled: Enable processing of GRACEFUL_SHUTDOWN BGP community.

    If enabled is False in the general.yml configuration then routes tagged with the GRACEFUL_SHUTDOWN BGP community are treated transparently; the gshut community is not stripped off.

    If enabled is True in the general.yml configuration but False on a specific client configuration then routes tagged with the GRACEFUL_SHUTDOWN BGP community received from that client will be treated as if the gshut community was missing and the community stripped off. Can be overwritten on a client-by-client basis.

    Default: False

    Example:

    enabled: False
    
  • local_pref: Value used to set the new LOCAL_PREF attribute of routes processed accordingly to gshut. Meaningful only when enabled is True.

    Default: 0

    Example:

    local_pref: 0
    

RFC1997 well-known communities: rfc1997_wellknown_communities

RFC1997 well-known communities (NO_EXPORT and NO_ADVERTISE) can be locally interpreted or passed through the route server, depending on the policy that a route server operator decides to implement. This section allows to configure this policy.

  • policy: The policy used to process routes tagged with NO_EXPORT or NO_ADVERTISE that are received from clients.

    Options:

    • rfc1997: routes are processed accordingly to RFC1997;

    • pass: routes are propagated to other clients with the NO_EXPORT/NO_ADVERTISE communities unaltered.

    Default: pass

    Example:

    policy: "pass"
    

RTT thresholds: rtt_thresholds

Thresholds used for actions that are performed on the basis of clients RTT, triggered using RTT-based BGP communities.

Used only if one or more of those BGP communities are set.

The value in the last part of the community identifies the threshold for which the action is requested; only values from the rtt_thresholds are taken into account and actually used to understand if the desired action should be performed.

Lower-than actions are inclusive, higher-than are exclusive.

Some examples (based on the default values below):

  • 15, lower-than: action is performed for peers with RTT <= 15

  • 30, higher-than: action is performed for peers with RTT > 30

  • 1000, not in rtt_thresholds, action not performed

  • 0, not in rtt_thresholds, action not performed

The values must be provided in ascending order.

Example:

rtt_thresholds: 5, 10, 15, 20, 30, 50, 100, 200, 500

BGP Communities: communities

For each community name below, Standard, Large and Extended BGP Communities can be provided in the std, lrg and ext statements respectively. Communities values must be given using the following formats:

  • std: x:x

  • lrg: x:x:x

  • ext: [rt|ro]:x:x

The rs_as macro is replaced with the route server ASN given in cfg.rs_as. The peer_as macro, where allowed, is replaced with the ASN of the client the route is announced to. The dyn_val macro, where allowed, is replaced with a numeric value that is significant to the function the BGP community is responsible for.

Prefix/origin AS present in client’s AS-SET

  • prefix_present_in_as_set, prefix_not_present_in_as_set, origin_present_in_as_set, origin_not_present_in_as_set, prefix_validated_via_rpki_roas, prefix_validated_via_arin_whois_db_dump, prefix_validated_via_registrobr_whois_db_dump and route_validated_via_white_list: Prefix/origin AS present in client’s AS-SET.

    If tag_as_set = True, prefixes that are (not) part of an AS-SET or whose origin ASN is (not) part of an AS-SET are tagged with the following BGP communities, provided that they are set below.

    The following communities are scrubbed from inbound routes.

    The rs_as macro can be used here.

RPKI BGP Origin Validation communities

  • rpki_bgp_origin_validation_not_performed: RPKI BGP Origin Validation not performed.

    When rpki_bgp_origin_validation.enabled is False (thus BGP origin validation is not performed), if the next community is configured the routes are tagged with it. Similarly, this community is also used to tag routes that are processed according to the blackhole policy when the BLACKHOLE community (or the custom one defined in blackholing below) is used, even though RPKI BGP Origin Validation is globally enabled.

    The following communities are scrubbed from inbound routes.

    The rs_as macro can be used here.

  • rpki_bgp_origin_validation_valid, rpki_bgp_origin_validation_unknown and rpki_bgp_origin_validation_invalid: RPKI BGP Origin Validation state.

    When rpki_bgp_origin_validation.enabled is True and BGP origin validation is performed, in addition to RFC8097 BGP communities the following ones are also used to tag routes depending on their state. These communities are not advertised to the clients, they are meant to be used only “internally” to the route server (for example for troubleshooting purposes or via looking glasses).

    The following communities are scrubbed from inbound and outbound routes.

    The rs_as macro can be used here.

Blackhole filtering

  • blackholing: Blackhole filtering.

    If a policy is given in blackhole_filtering, it is applied to routes tagged with one of the following communities:

    • the BLACKHOLE well-known community 65535:666, that is always implemented if a blackhole_filtering policy is given (https://tools.ietf.org/html/rfc7999#section-5)

    • one of the following blackholing Standard, Large or Extended BGP communities.

    The following community is scrubbed from outbound routes.

    The rs_as macro can be used here.

Propagation control

  • do_not_announce_to_any: Control communities.

    Routes that are tagged with the following community are not announced to any client, unless they are also tagged with the announce_to_peer communities: in this case, such routes are announced only to the clients whose ASN matches the value given in the announce_to_peer communities.

    The following community is scrubbed from outbound routes.

    The rs_as macro can be used here.

  • do_not_announce_to_peer: Routes that are tagged with the following community are not announced to clients whose ASN matches the value given in the community itself. If a route is tagged with the two conflicting communities do_not_announce_to_peer and announce_to_peer, the route is not advertised to the peer.

    The following community is scrubbed from outbound routes.

    The rs_as macro can be used here. The peer_as macro must appear in the last part of values.

  • announce_to_peer: Routes that are tagged with the following community are announced to clients whose ASN matches the value given in the community itself even if they are tagged with the do_not_announce_to_any community. If a route is tagged with the two conflicting communities do_not_announce_to_peer and announce_to_peer, the route is not advertised to the peer.

    The following community is scrubbed from outbound routes.

    The rs_as macro can be used here. The peer_as macro must appear in the last part of values.

  • do_not_announce_to_peers_with_rtt_lower_than and do_not_announce_to_peers_with_rtt_higher_than: Routes that are tagged with the following community are not announced to clients that have a RTT lower/higher than the value of the threshold identified by the last part of the community.

    The following communities are scrubbed from outbound routes.

    The rs_as macro can be used here. The dyn_val macro must appear in the last part of values. The dyn_val macro must contain a value from the rtt_thresholds list that identifies the RTT value for which the action is requested.

  • announce_to_peers_with_rtt_lower_than and announce_to_peers_with_rtt_higher_than: Routes that are tagged with the following community are announced to clients that have a RTT lower/higher than the value of the threshold identified by the last part of the community, even if they are tagged with the do_not_announce_to_any community. If a route is also tagged with the do_not_announce_to_peer community it is not advertised to the client even if it matches the RTT criterion.

    The following communities are scrubbed from outbound routes.

    The rs_as macro can be used here. The dyn_val macro must appear in the last part of values. The dyn_val macro must contain a value from the rtt_thresholds list that identifies the RTT value for which the action is requested.

Prepending

  • prepend_once_to_any, prepend_twice_to_any and prepend_thrice_to_any: Prepending communities.

    The 3 “flavors” of prepending actions (to_peer, rtt based and to_any) are applied in the following order:

    • prepend_x_to_peer

    • prepend_x_to_peers_with_rtt_higher_than (RTTs in desc order)

    • prepend_x_to_peers_with_rtt_lower_than (RTTs in asc order)

    • prepend_x_to_any (x is always in the ascending order: once, twice, thrice).

    For example, if a route is tagged with both a prepend_x_to_any and a prepend_x_to_peer community, only the latter will be considered when announcing to the clients whose ASN match the one given in its value. Routes that are tagged with the following communities are propagated to all the clients with an AS_PATH prepended once, twice or thrice with the announcing client’s ASN.

    The following communities are scrubbed from outbound routes.

    The rs_as macro can be used here.

  • prepend_once_to_peer, prepend_twice_to_peer and prepend_thrice_to_peer: Routes that are tagged with the following communities are propagated to the clients whose ASN matches the one given in the community with an AS_PATH prepended once, twice or thrice with the announcing client’s ASN.

    The following communities are scrubbed from outbound routes.

    The rs_as macro can be used here. The peer_as macro must appear in the last part of values.

  • prepend_once_to_peers_with_rtt_lower_than, prepend_twice_to_peers_with_rtt_lower_than, prepend_thrice_to_peers_with_rtt_lower_than, prepend_once_to_peers_with_rtt_higher_than, prepend_twice_to_peers_with_rtt_higher_than and prepend_thrice_to_peers_with_rtt_higher_than: Routes that are tagged with the following communities are propagated to clients having a RTT lower/higher than the value of the threshold identified by the last part of the community with an AS_PATH prepended once, twice or thrice with the announcing client’s ASN.

    The following communities are scrubbed from outbound routes. The peer_as macro must appear in the last part of values.

    The rs_as macro can be used here. The dyn_val macro must appear in the last part of values. The dyn_val macro must contain a value from the rtt_thresholds list that identifies the RTT value for which the action is requested.

NO_EXPORT / NO_ADVERTISE

  • add_noexport_to_any and add_noadvertise_to_any: Routes that are tagged with the following communities are propagated to other clients before the NO_EXPORT (65535:65281) and/or the NO_ADVERTISE (65535:65282) well-known communities are added. When rfc1997_wellknown_communities.enabled is set to pass this behaviour can be obtained by announcing routes to the route server after tagging them with RFC1997 NO_EXPORT or NO_ADVERTISE.

    The following communities are scrubbed from outbound routes.

    The rs_as macro can be used here.

  • add_noexport_to_peer and add_noadvertise_to_peer:

    The rs_as macro can be used here. The peer_as macro must appear in the last part of values.

Reject cause

  • reject_cause: This BGP community is used when the reject_policy option is set to tag or tag_and_reject. It is used to track the code of the reason that led the route to be considered as invalid.

    The list of reject codes can be found at this URL: https://arouteserver.readthedocs.io/en/latest/CONFIG.html#reject-reasons

    The following community is scrubbed from inbound routes.

    The rs_as macro can be used here. The dyn_val macro must appear in the last part of values.

  • reject_cause_map: This section can be used to map reject codes to specific BGP communities, without following the general pattern imposed in reject_cause. It can be used only when the reject_policy option is set to tag or tag_and_reject.

    The reject_cause_map does not replace the use of reject_cause: the BGP communities configured in this map are added to those built according to reject_cause. When a route is rejected, in order to determine the BGP community to be attached to it to describe the reject reason, a lookup is performed in this table for the reject code: if an entry is found, the community mapped to that reject code is attached to the route, in addition to the BGP community formatted according to reject_cause.

    To configure this section, values from the official list of reject codes must be used as the key of the dictionary.

    The rs_as macro can be used here.

    Example:

    reject_cause_map: “14”: lrg: rs_as:1101:13

    In the example, 14 is the reject code for RPKI INVALID routes

    The list of reject codes can be found at this URL: https://arouteserver.readthedocs.io/en/latest/CONFIG.html#reject-reasons

    The communities configured here are scrubbed from inbound routes.

  • rejected_route_announced_by: This BGP community is used when the reject_policy option is set to tag or tag_and_reject. If configured, it is used to track the ASN of the peer that announced the invalid route to the route server.

    The following community is scrubbed from inbound routes.

    The rs_as macro can be used here. The dyn_val macro must appear in the last part of values.

Custom BGP communities: custom_communities

  • custom_community1_name: Custom BGP communities can be added to routes that enter the route server from clients. Each client can be configured with a set of custom communities that are added to the routes it announces to the route server; these communities will be then propagated to other clients as the routes leave the server.

    The name of a custom BGP community can’t be the same of any built-in community.

    The rs_as macro can be used here.