** This project is no longer being maintained, please use at your own discretion! **
Solenoid takes a third-party BGP protocol and sends the BGP updates to Cisco's RIB table on the IOS-XR devices, allowing for increased flexibility over the BGP protocols used on the box.
The changes to the RIB are accomplished by using gRPC calls to send JSON modeled by YANG. The YANG model currently in use is [Cisco-IOS-XR-ip-static-cfg] (https://github.com/YangModels/yang/blob/master/vendor/cisco/xr/600/Cisco-IOS-XR-ip-static-cfg.yang), see Current Limitations for more information.
[exaBGP] (https://github.com/Exa-Networks/exabgp) is used for reading BGP updates. exaBGP is a tool for monitoring BGP network announcements, withdrawals, etc. and it triggers the gRPC changes based on these updates.
Please refer to the Wiki for further documentation.
As of now, the IOS-XR does not support YANG models that can add true BGP or Application routes to the RIB table. As a workaround, static routes are added instead. Be aware of the limits of static routes before using this application.
RESTconf is not available on public images of the IOS-XR 6.X. If you are interested in testing RESTconf, please reach out to your Cisco account team or contact Lisa Roach directly.
For an easy Solenoid-in-a-box demonstration, please refer to the vagrant directory. Here you will be able to download a fully functional vagrant environment that has Solenoid up and running already.
Check the out XR-Docs tutorial for a walkthrough of setting up a Solenoid LXC and playing with the demo.
This installation and testing process (minus the integration tests) can run in any Linux environment. To fully use the application, it must be connected to a running IOS-XR 6.1+ device. It is recommended that Solenoid be run in an LXC on the IOS-XR you wish to control, see Creating a Solenoid LXC tarball for information about creating your own LXC.
Step 1: Clone this repo and cd into Solenoid.
Step 2: It is highly recommended you install and use a virtualenv.
pip install virtualenv
virtualenv venv
source venv/bin/activate
Step 3: Install gRPC (if you are using gRPC). Note: if you experience errors at this step and are not using a virtualenv, we encourage reconsidering using virtualenv. It often makes these problems go away. Otherwise, please consult grpcio documentation for assistance.
pip install grpcio
Step 4: Install Solenoid.
python setup.py install
Step 5 : Create a solenoid.config file in your top-level solenoid directory and fill in the values in the key:value pair. Please refer to the Config File section of the wiki for more information.
[default]
transport: transport # Either gRPC or RESTconf
ip: ip_address # IP address of the destination RIB table (the XR device you intend to control)
port: port number # Depends on what is configured for your gRPC or RESTconf servers
username: username # Username for the router
password: password # Password for the router
Example:
[IOS-XRv]
transport: gRPC
ip: 192.168.1.2
port: 57777
username: vagrant
password: vagrant
Step 6 (optional): Create a filter.txt file to include the ranges of prefixes to be filtered with. This is a whitelist of prefixes, so all of these will be accepted and all others will be dropped. Single prefixes are also acceptable. Example:
1.1.1.0/32-1.1.2.0/32
10.1.1.0/32-10.1.5.0/32
10.1.1.6/32
192.168.1.0/28-192.168.2.0/28
Step 7: Set up [exaBGP] (https://github.com/Exa-Networks/exabgp). Form a neighborship with your BGP network.
Step 8: Change your exaBGP configuration file to run the edit_rib.py script. The important part is the process monitor-neighbors section, the rest is basic exaBGP configuration.
Example:
group test {
router-id x.x.x.x;
process monitor-neighbors {
encoder json;
receive {
parsed;
updates;
neighbor-changes;
}
run /your/python/location /path/to/solenoid/solenoid/edit_rib.py;
}
neighbor y.y.y.y {
local-address x.x.x.x;
local as ####;
peer-as ####;
}
}
If you chose to add a filter file, you must add the path to the file in the run call with the file flag -f (be sure to include the quotes):
run /your/python/location /path/to//solenoid/solenoid/edit_rib.py -f '/path/to/filter/file';
Step 9: Launch your exaBGP instance. You should see the syslog HTTP status codes if it is successful.
###Testing
In order to run the full suite of unit tests, ensure that grpcio is installed. Run the tests with the following command from the Solenoid/ directory:
python -m unittest discover solenoid.tests.mock
If you only wish to use RESTconf and will not be testing the gRPC code, feel free to run the following individual tests:
python -m unittest solenoid.tests.mock.test_rib_rest
python -m unittest solenoid.tests.mock.test_rib_general
The following is expected output from the unit tests:
python -m unittest discover solenoid.tests.mock
............................
----------------------------------------------------------------------
Ran 28 tests in 0.042s
OK
If you recieve the final status of 'OK' you are good to go!
To run integration testing, run the following command from the Solenoid/ directory. CAUTION This will make changes to your router's RIB table! Do not run this code in a production environment!
For these tests to run, you must provide a properly formatted solenoid.config file, as described in step 3, and ensure that no other instance of Solenoid is currently running.
python -m unittest discover solenoid.tests.integration
Expected output:
python -m unittest discover solenoid.tests.integration
Thu, 01 Sep 2016 22:21:41 | INFO | 19738 | solenoid | ANNOUNCE | OK
.Thu, 01 Sep 2016 22:21:41 | INFO | 19738 | solenoid | WITHDRAW | OK
.Thu, 01 Sep 2016 22:21:42 | INFO | 19738 | solenoid | ANNOUNCE | OK
.Thu, 01 Sep 2016 22:21:42 | INFO | 19738 | solenoid | WITHDRAW | OK
.Thu, 01 Sep 2016 22:21:42 | INFO | 19738 | solenoid | EOR message
.
----------------------------------------------------------------------
Ran 5 tests in 0.890s
OK