Installation ============ .. Hint:: A Docker-based `playground `__ is available to experiment with the installation and configuration steps reported in this section. For a quick start, please also see the official `Docker image `__. Dependencies ------------ Some components used by ARouteServer need Python dev header files and static libraries: some distributions have them already included, others may need to manually install them: .. code:: bash # Debian Jessie, Ubuntu Trusty apt-get install python-dev # for Python 2 apt-get install python3-dev # for Python 3 # CentOS yum -y install gcc python-devel Please note that ARouteServer also needs `bgpq4 `_ (preferred) or `bgpq3 `_ to build IRR-based filters: details on their installation can be found within the :ref:`External programs` section. Install using ``pip`` (suggested) --------------------------------- If you plan to just use the program to build configurations or to run your own live tests scenarios, you can install it using ``pip``. Strongly suggested: setup a `Virtualenv `_. .. code:: bash # on Debian/Ubuntu: sudo apt-get install python3-pip python3-virtualenv # on CentOS: sudo yum install epel-release sudo yum install python-pip python-virtualenv # on OpenBSD pkg_add python3 pkg_add py3-packaging py3-wheel py3-pip py3-virtualenv # setup a virtualenv mkdir -p ~/.virtualenvs/arouteserver virtualenv ~/.virtualenvs/arouteserver source ~/.virtualenvs/arouteserver/bin/activate # install the program pip3 install arouteserver More: ``virtualenv`` `installation `_ and `usage `_. .. note:: If you receive the following error while installing the program (or its requirements): **error in setup command: 'install_requires' must be a string or list of strings containing valid project/version requirement specifiers** then please upgrade the *setuptools* package that is used in your virtualenv: ``pip install --upgrade setuptools``. .. note:: In the case the pip installation process breaks with the **Failed building wheel for py-radix / fatal error: Python.h: No such file or directory** error, please verify that the dependencies are satisfied. Install from GitHub ------------------- If you plan to run built-in :doc:`Live tests ` on your own or to contribute to the project, clone the GitHub repository locally and install dependencies: .. code:: bash mkdir -p ~/src/arouteserver cd ~/src/arouteserver # use the URL of your fork here: git clone https://github.com/USERNAME/arouteserver.git ./ export PYTHONPATH="`pwd`" pip install -r requirements.txt Setup and initialization ------------------------ - Setup your system layout (confirmation will be asked before each action): .. code:: bash # if you used pip arouteserver setup # if you installed from GitHub export PYTHONPATH="`pwd`" ./scripts/arouteserver setup The program will ask you to create some directories (under ``~/arouteserver`` by default) and to copy some files there. These paths can be changed by editing the ``arouteserver.yml`` program configuration file or by using command line arguments. More information in the :doc:`configuration section `. - Define the route server configuration policies, using the ``configure`` command or manually by editing the ``general.yml`` file: .. code:: bash # if you used pip arouteserver configure # if you installed from GitHub ./scripts/arouteserver configure The ``configure`` command asks some questions about the route server environment (ASN, router ID, local subnets) and then it builds a policy definition file based on best practices and suggestions which also includes a rich BGP communities list. - If you plan to use features that are based on PeeringDB data (some of them are enabled by default or proposed as part of the policies generated by the ``configure`` command above) it is strongly suggested that you create a PeeringDB API key and configure it in the system where ARouteServer runs. Using an API key allows to mitigate the effect of the anonymous API throttling mechanism. The key can be exposed via the environment variable ``SECRET_PEERINGDB_API_KEY``, or stored inside a local file, at one of the following well-known paths: ``~/.arouteserver/peeringdb_api.key``, ``~/.peeringdb_api.key``. Details on how to obtain an API key can be found on the `PeeringDB web site `__. External programs ----------------- ARouteServer uses the following external programs: - (mandatory) `bgpq4 `_ or `bgpq3 `_ are used to gather information from IRRDBs: at least one of them must be installed on the system where ARouteServer is executed. **Please note**: the ``libtool`` package may need to be added to the system in order to compile bgpq4: ``apt-get install libtool`` / ``yum install -y libtool``. To install bgpq4: .. code:: bash mkdir /path/to/bgpq4/directory cd /path/to/bgpq4/directory git clone https://github.com/bgp/bgpq4.git ./ # automake, autoconf, make and gcc packages required ./bootstrap ./configure make sudo make install To install bgpq3: .. code:: bash mkdir /path/to/bgpq3/directory cd /path/to/bgpq3/directory git clone https://github.com/snar/bgpq3.git ./ # make and gcc packages required ./configure make sudo make install On OpenBSD you can also install the package directly: .. code:: bash pkg_add bgpq3 - (optional) `Docker `_ is used to perform :doc:`live validation ` of configurations. To install it, please refer to its `official guide `_. - (optional) `KVM `_ is also used to perform :doc:`live tests ` of OpenBGPD configurations on an OpenBSD virtual machine. To install it: .. code:: bash apt-get install qemu-kvm virtinst More details: https://wiki.debian.org/KVM - (optional) `rtrlib `_ and `bird-rtrlib-cli `_; ARouteServer can use these tools to load RPKI data into BIRD 1.6.x. More details in :ref:`ROAs sources`. To install them: .. code:: bash curl -o rtrlib.zip -L https://github.com/rtrlib/rtrlib/archive/v0.3.6.zip unzip rtrlib.zip cd rtrlib-0.3.6 && \ cmake -D CMAKE_BUILD_TYPE=Release . && \ make && \ make install curl -o bird-rtrlib-cli.zip -L https://github.com/rtrlib/bird-rtrlib-cli/archive/v0.1.1.zip unzip bird-rtrlib-cli.zip cd bird-rtrlib-cli-0.1.1 && \ cmake . && \ make More details: https://github.com/rtrlib/rtrlib/wiki/Installation To configure bird-rtrlib-cli please refer to the `README `_. Upgrading --------- Often upgrades bring new features and new options, sometimes they also introduce changes that might break backward compatibility with previous versions. It is advisable to always check the :doc:`CHANGELOG ` to verify what's new: the ``arouteserver show_config`` command can also be used to verify if new configuration options are available and how they are set by default. To upgrade the program, download the new version... .. code:: bash # if you cloned the repository from GitHub, # from within the local repository's directory: git pull origin master # if you installed it with pip: pip install --upgrade arouteserver ... then sync the local templates with those distributed in the new version: .. code:: bash arouteserver setup-templates If local templates have been edited, make a backup of your files in order to merge your changes in the new ones later. To customize the configuration of the route server with your own options, please consider using :ref:`site-specific-custom-config` instead of editing the template files. Development and pre-release versions ------------------------------------ .. note:: Consider your needs carefully before using a version other than the current production versions. These are preview releases, and their use is not recommended in production settings. The **dev** `branch `__ is used for the development of the project, while the **master** branch always contains the latest, (hopefully) stable production-ready code. To install or to upgrade to `the latest pre-release version `__ use the `TestPyPI `__ instance of the Python Package Index (PyPI): .. code:: bash pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple --pre arouteserver Ansible role ------------ An Ansible role to install and configure ARouteServer can be found on `Galaxy `__ or on `GitHub `__. It is tested on Debian (Jessie, Stretch), Ubuntu (Trusty, Xenial) and CentOS 7.