.. DO NOT EDIT: this file is automatically created by /utils/build_doc
|Documentation| |Build Status| |PYPI Version| |Requirements|
A Python tool to automatically build (and test) feature-rich configurations for BGP route servers.
How it works
#. Two YAML files provide *general policies* and *clients configurations* options:
.. code:: yaml
.. code:: yaml
- asn: 111
#. ARouteServer acquires external information to enrich them: `bgpq3`_ for IRRDb data, `PeeringDB`_ for max-prefix limit, ...
#. `Jinja2`_ built-in templates are used to render the final route server's configuration file.
Currently, **BIRD** (1.6.3) and **OpenBGPD** (OpenBSD 6.0 and 6.1) are supported.
**Validation** and testing are performed using the built-in **live tests** framework: `Docker`_ instances are used to simulate several scenarios, and more custom scenarios can be built on the basis of the user's needs. More details on the `Live tests <https://arouteserver.readthedocs.io/en/latest/LIVETESTS.html>`_ section.
.. _bgpq3: https://github.com/snar/bgpq3
.. _PeeringDB: https://www.peeringdb.com/
.. _Jinja2: http://jinja.pocoo.org/
.. _Docker: https://www.docker.com/
- **Path hiding** mitigation techniques (`RFC7947`_ `section 2.3.1 <https://tools.ietf.org/html/rfc7947#section-2.3.1>`_).
- Filtering features (most enabled by default):
- **NEXT_HOP** enforcement (strict / same AS - `RFC7948`_ `section 4.8 <https://tools.ietf.org/html/rfc7948#section-4.8>`_);
- minimum and maximum IPv4/IPv6 **prefix length**;
- maximum **AS_PATH length**;
- reject **invalid AS_PATHs** (containing `private/invalid ASNs <http://mailman.nanog.org/pipermail/nanog/2016-June/086078.html>`_);
- reject AS_PATHs containing **transit-free** ASNs;
- **RPKI**-based filtering (`RFC6811`_);
- reject **bogons**;
- prefixes and origin ASNs enforcing via **RPSL/IRRdb AS-SETs** (`RFC7948`_ `section 4.6.2 <https://tools.ietf.org/html/rfc7948#section-4.6.2>`_);
- **max-prefix limit** based on global or client-specific values or on **PeeringDB** data.
- **Blackhole filtering** support:
- optional **NEXT_HOP rewriting**;
- signalling via BGP Communities (`BLACKHOLE <https://tools.ietf.org/html/rfc7999#section-5>`_ and custom communities);
- client-by-client control over propagation.
- Control and informative communities:
- prefix/origin ASN present/not present in **IRRDB data**;
- routes **RPKI** validity state;
- do (not) announce to any / **peer**;
- **prepend** to any / **peer**;
- add **NO_EXPORT** / **NO_ADVERTISE** to any / **peer**;
- custom informational BGP communities.
- Optional session features on a client-by-client basis:
- prepend route server ASN (`RFC7947`_ `section 18.104.22.168 <https://tools.ietf.org/html/rfc7947#section-22.214.171.124>`_);
- active sessions;
- **GTSM** (Generalized TTL Security Mechanism - `RFC5082`_);
- **ADD-PATH** capability (`RFC7911`_).
- Automatic building of clients list:
- `integration <https://arouteserver.readthedocs.io/en/latest/USAGE.html#ixp-manager-integration>`_ with **IXP-Manager**;
- `fetch lists <https://arouteserver.readthedocs.io/en/latest/USAGE.html#automatic-clients>`_ from **PeeringDB** records and **Euro-IX member list JSON** files.
- Built-in tools:
- `Invalid routes reporter <https://arouteserver.readthedocs.io/en/latest/TOOLS.html>`_, to log or report rejected routes and the reject reason.
A comprehensive list of features can be found within the comments of the distributed configuration file on `GitHub <https://github.com/pierky/arouteserver/blob/master/config.d/general.yml>`_.
More feature are already planned: see the `Future work <https://arouteserver.readthedocs.io/en/latest/FUTUREWORK.html>`_ section for more details.
.. _RFC7947: https://tools.ietf.org/html/rfc7947
.. _RFC7948: https://tools.ietf.org/html/rfc7948
.. _RFC5082: https://tools.ietf.org/html/rfc5082
.. _RFC7911: https://tools.ietf.org/html/rfc7911
.. _RFC6811: https://tools.ietf.org/html/rfc6811
Full documentation can be found on ReadTheDocs: https://arouteserver.readthedocs.org/
- RIPE74, 10 May 2017, Connect Working Group: `video <https://ripe74.ripe.net/archives/video/87/>`_ (9:53), `slides <https://ripe74.ripe.net/presentations/22-RIPE74-ARouteServer.pdf>`_ (PDF)
- Salottino MIX, 30 May 2017: `slides <https://www.slideshare.net/PierCarloChiodi/salottino-mix-2017-arouteserver-ixp-automation-made-easy>`_
**Beta testing**, looking for testers and reviewers.
Anyone who wants to share his/her point of view, to review the output configurations or to test them is **more than welcome**!
But also suggestions? New ideas?
Please create an `issue on GitHub <https://github.com/pierky/arouteserver/issues>`_ or `drop me a message <https://pierky.com/#contactme>`_.
Pier Carlo Chiodi - https://pierky.com
Blog: https://blog.pierky.com Twitter: `@pierky <https://twitter.com/pierky>`_
.. |Documentation| image:: https://readthedocs.org/projects/arouteserver/badge/?version=latest
.. |Build Status| image:: https://travis-ci.org/pierky/arouteserver.svg?branch=master
.. |PYPI Version| image:: https://img.shields.io/pypi/v/arouteserver.svg
.. |Requirements| image:: https://requires.io/github/pierky/arouteserver/requirements.svg?branch=master
:alt: Requirements Status
.. note:: **Upgrade notes**: after upgrading, run the ``arouteserver setup-templates`` command to sync the local templates with those distributed with the new version. More details on the `Upgrading <https://arouteserver.readthedocs.io/en/latest/INSTALLATION.html#upgrading>`_ section of the documentation.
- New feature: `reject policy <https://arouteserver.readthedocs.io/en/latest/CONFIG.html#reject-policy>`_ configuration option, to control how invalid routes must be treated: immediately discarded or kept for troubleshooting purposes, analysis or statistic reporting.
- New tool: `invalid routes reporter <https://arouteserver.readthedocs.io/en/latest/TOOLS.html>`_.
- Fix: the following networks have been removed from the bogons.yml file: 126.96.36.199/22, 188.8.131.52/21, 184.108.40.206/29.
- New feature: `custom BGP communities <https://arouteserver.readthedocs.io/en/latest/CONFIG.html#custom-bgp-communities>`_ can be configured on a client-by-client basis to tag routes entering the route server (for example, for informative purposes).
- Fix: validation of BGP communities configuration for OpenBGPD.
Error is given if a peer-AS-specific BGP community overlaps with another community, even if the last part of the latter is a private/reserved ASN.
- Improvement: the custom ``!include <filepath>`` statement can be used now in YAML configuration files to include other files.
More details `here <https://arouteserver.readthedocs.io/en/latest/CONFIG.html#yaml-files-inclusion>`_.
- Improvement: IRRDB-based filters can be configured to allow more specific prefixes (``allow_longer_prefixes`` option).
- OpenBGPD 6.1 support: enable large BGP communities support.
- Improvement: the ``clients-from-peeringdb`` command now uses the `IX-F database <http://www.ix-f.net/ixp-database.html>`_ to show a list of IXP and their PeeringDB ID.
- Improvement: enable NEXT_HOP rewriting for IPv6 blackhole filtering requests on OpenBGPD after `OpenBSD 6.1 fixup <https://github.com/openbsd/src/commit/f1385c8f4f9b9e193ff65d9f2039862d3e230a45>`_.
Related: `issue #3 <https://github.com/pierky/arouteserver/issues/3>`_.
- Improvement: BIRD, client-level `.local file <https://arouteserver.readthedocs.io/en/latest/CONFIG.html#site-specific-custom-config>`_.
- Improvement: next-hop checks, the ``authorized_addresses`` option allows to authorize IP addresses of non-client routers for NEXT_HOP attribute of routes received from a client.
- Fix: avoid the use of standard communities in the range 65535:x.
- Improvement: option to set max-prefix restart timer for OpenBGPD.
- Deleted feature: tagging of routes à la RPKI-Light has been removed.
- The ``reject_invalid`` flag, that previously was on general scope only, now can be set on a client-by-client basis.
- The ``roa_valid``, ``roa_invalid``, and ``roa_unknown`` communities no longer exist.
Related: `issue #4 on GitHub <https://github.com/pierky/arouteserver/issues/4>`_
This **breaks backward compatibility**.
- New feature: `BIRD hooks <https://arouteserver.readthedocs.io/en/latest/CONFIG.html#bird-hooks>`_ to add site-specific custom implementations.
- Improvement: `BIRD local files <https://arouteserver.readthedocs.io/en/latest/CONFIG.html#site-specific-custom-config>`_.
This **breaks backward compatibility**: previously, \*.local, \*.local4 and \*.local6 files that were found in the same directory where the BIRD configuration was stored were automatically included. Now, only the header([4|6]).local and footer([4|6]).local files are included, depending on the values passed to the ``--use-local-files`` command line argument.
- Improvement: ``setup`` command and program's configuration file.
The default path of the cache directory (*cache_dir* option) has changed: it was ``/var/lib/arouteserver`` and now it is ``cache``, that is a directory which is relative to the *cfg_dir* option (by default, the directory where the program's configuration file is stored).
- OpenBGPD support (some `limitations <https://arouteserver.readthedocs.io/en/latest/CONFIG.html#caveats-and-limitations>`_ apply).
- Add MD5 password support on clients configuration.
- The ``build`` command used to generate route server configurations has been removed in favor of BGP-speaker-specific sub-commands: ``bird`` and ``openbgpd``.
- New ``--test-only`` flag for builder commands.
- New ``--clients-from-euroix`` `command <https://arouteserver.readthedocs.io/en/latest/USAGE.html#create-clients-yml-file-from-euro-ix-member-list-json-file>`_ to build the ``clients.yml`` file on the basis of records from an `Euro-IX member list JSON file <https://github.com/euro-ix/json-schemas>`_.
This also allows the `integration <https://arouteserver.readthedocs.io/en/latest/USAGE.html#ixp-manager-integration>`_ with `IXP-Manager <https://github.com/inex/IXP-Manager>`_.
- New BGP communities: add NO_EXPORT and/or NO_ADVERTISE to any client or to specific peers.
- New option (set by default) to automatically add the NO_EXPORT community to blackhole filtering announcements.
- ``setup-templates`` command to just sync local templates with those distributed within a new release.
- Multithreading support for tasks that acquire data from external sources (IRRDB info, PeeringDB max-prefix).
Can be set using the ``threads`` option in the ``arouteserver.yml`` configuration file.
- New ``template-context`` command, useful to dump the list of context variables and data that can be used inside a template.
- New empty AS-SETs handling: if an AS-SET is empty, no errors are given but only a warning is logged and the configuration building process goes on.
Any client with IRRDB enforcing enabled and whose AS-SET is empty will have its routes rejected by the route server.
- Fix local files usage among IPv4/IPv6 processes.
Before of this release, only *.local* files were included into the route server configuration, for both the IPv4 and IPv6 configurations.
After this, *.local* files continue to be used for both the address families but *.local4* and *.local6* files can also be used to include IP version specific options, depending on the IP version used to build the configuration. Details `here <https://arouteserver.readthedocs.io/en/latest/CONFIG.html#site-specific-custom-configuration-files>`_.
.. code:: bash
# pull from GitHub master branch or use pip:
pip install --upgrade arouteserver
# install the new template files into local system
- Add local static files into the route server's configuration.
- First beta version.
- The ``filtering.rpsl`` section of general and clients configuration files has been renamed into ``filtering.irrdb``.
- The command line argument ``--template-dir`` has been renamed into ``--templates-dir``.
- New options in the program's configuration file: ``bgpq3_host`` and ``bgpq3_sources``, used to set bgpq3 ``-h`` and ``-S`` arguments when gathering info from IRRDBs.
- New command to build textual representations of configurations: ``html``.
- New command to initialize a custom live test scenario: ``init-scenario``.
- New feature: selective path prepending via BGP communities.
- The ``control_communities`` general option has been removed: it was redundant.
- Improved communities configuration and handling.
- Fix issue on standard communities matching against 32-bit ASNs.
- Fix issue on IPv6 prefix validation.
- New feature: RPKI-based filtering/tagging.
- New feature: transit-free ASNs filtering.
- Program command line: subcommands + ``clients-from-peeringdb``.
- More logging and some warning.
- Fix issue with GTSM default value.
- Add default route to bogons.
- Better as-sets handling and cache handling.
- Config syntax change: clients 'as' -> 'asn'.
- AS-SETs at AS-level.
- Live tests: path hiding mitigation scenario.
- Improvements in templates.
- Fix some cache issues.
- System setup via ``arouteserver --setup``.
First push on GitHub.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.