On the customer overview page from IXP Manager v5.0, we provide an indication (yes/no) as to whether a customer has a PeeringDB record. Generally it is important for IXPs to encourage their members to create PeeringDB entries to ensure your IXP is properly represented on their database.
-Whether a customer has a PeeringDB entry is updated daily via the cronjobs.md. If you want to run it manually, run this Artisan command:
+Whether a customer has a PeeringDB entry is updated daily via the task scheduler. If you want to run it manually, run this Artisan command:
$ php artisan ixp-manager:update-in-peeringdb -vv
PeeringDB membership updated - before/after/missing: 92/92/17
IXP Manager is the most trusted IXP platform worldwide.
It is a full stack management system for Internet eXchange Points (IXPs) which includes an administration and customer portal; provides end to end provisioning; and both teaches and implements best practice. It allows IXPs to manage new customers, provision new connections / services and monitor traffic usage. It has a number of provisioning templates including its ability to generate secure proven route server configuration and provides a built in looking glass for these.
INEX are pleased to release IXP Manager under an open source license (the GNU Public License V2) which we hope will benefit the wider IXP community, and especially new and small IXPs looking to expand.
Additional information: https://www.ixpmanager.org/
"},{"location":"#other-links","title":"Other Links","text":"INEX is an Internet eXchange Point and Ireland's IP peering hub. It is a neutral, industry-owned Association, founded in 1996, that provides IP peering facilities for its members. INEX membership is open to all organisations that can benefit from peering their IP traffic. See: https://www.inex.ie/. INEX is IXP Manager's core team and founder.
Principle Authors:
The team at INEX deserves special mention - its CEO, Eileen Gallagher for her steadfast support and promotion of the project; the INEX Board of Directors - past and present - for their approval to open source the project and their on-going support of the project; and all team members who contribute real-world feedback, suggestions and all-round support!
See the team page on the IXP Manager website for more details.
We are also grateful for all the individuals who have contributed code, issues, mailing list help and feature requests.
"},{"location":"#sponsors","title":"Sponsors","text":"IXP Manager is extremely grateful to its existing sponsors and patrons and continues to seek sponsors for on going development. If you are interested, please see out call for sponsorship.
"},{"location":"#license","title":"License","text":"IXP Manager is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version v2.0 of the License.
IXP Manager is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License v2.0 along with IXP Manager. If not, see:
http://www.gnu.org/licenses/gpl-2.0.html
"},{"location":"#documentation-license","title":"Documentation License","text":"This documentation is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
"},{"location":"dev/api/","title":"API","text":"You'll find API documentation when logged into IXP manager under My Account / API Keys.
"},{"location":"dev/authentication/","title":"Authentication & Session Management (Development Notes)","text":"Please read the authentication usage instructions first as that provides some key information for understanding the below brief notes.
IXP Manager uses Laravel's standard authentication framework with Laravel's Eloquent ORM.
See also Barry O'Donovan's PHP write up of the 2fa and user session management changes introduced in v5.3.0 and the v5.2.0 to v5.3.0 diff.
"},{"location":"dev/authentication/#multiple-sessions-remember-me-cookies","title":"Multiple Sessions / Remember Me Cookies","text":"The default Laravel functionality around remember me is a single shared token across multiple devices. In practice this never worked well for us (but this is most likely a consequence of using LaravelDoctrine). Regardless, we also wanted to expand the functionality to uniquely identify each session and allow other sessions to be logged out by the user.
"},{"location":"dev/authentication/#sessionguard-and-userprovider","title":"SessionGuard and UserProvider","text":"Most of the functionality exists in the session guard and user provider classes. We have overridden these here:
app/Services/Auth/SessionGuard.phpapp/Services/Auth/EloquentUserProvider.phpAgain, the idea is to minimise the changes required to the core Laravel framework (and Laravel Eloquent).
"},{"location":"dev/authentication/#how-it-works","title":"How It Works","text":"When you log in and check remember me, IXP Manager will create a new UserRememberToken database entry with a unique token and an expiry set to config( 'auth.guards.web.expire') (note this is minutes).
Your browser will be sent a cookie named remember_web_xxxx (where xxxx is random). This cookie contains the encrypted token that was created (UserRememberToken). IXP Manager uses this cookie to create a new authenticated session if your previous session has timed out, etc.
Note that this remember_web_xxxx cookie has an indefinite expiry date - the actual expiring of the remember me session is handled by the expiry field in the UserRememberToken database entry.
When you subsequently make a request to IXP Manager:
user() method) first tries to retrieve your session via the standard browser session cookie (laravel_session).remember_web_xxxx cookie and, if it exists, validates it and looks you in with a new laravel_session.Two-factor authentication (2fa) is implemented using the pragmarx/google2fa package via its Laravel bridge antonioribeiro/google2fa-laravel.
The database table for storing a user's secret key is user_2fa. 2FA for a user is enabled if:
$user->user2FA entity (one to one); andAuth::getUser()->user2FA->enabled is true.Once 2fa is enabled, the mechanism for enforcing it is the 2fa middleware. This is applied to all authenticated http web requests via app/Providers/RouteServiceProvider.php.
We use the antonioribeiro/google2fa-laravel bridge's PragmaRX\\Google2FALaravel\\Events\\LoginSucceeded event to update a user's remember me token via the listener IXP\\Listeners\\Auth\\Google2FALoginSucceeded. The update is to set user_remember_tokens.is_2fa_complete to true so that the SessionGuard knows to skip 2fa on these sessions.
IXP Manager grew out of a code base and schema that started in the early '90s. Long before test driven development or behaviour driven development was fashionable for PHP. However, as IXP Manager is taking over more and more critical configuration tasks, we continue to back fill some automated testing with continuous integration for critical elements.
We use GitHub Actions for continuous integration which is provided free for public repositories.
Our current build status is:
The CI system runs the full suite of tests every time a commit is pushed to GitHub. As such, any build failing states are usually transitory. Official IXP Manager releases are only made when all tests pass.
We use two types of unit tests:
We won't be aggressively writing tests for the existing codebase but will add tests as appropriate as we continue development. What follows is some basic instructions on how to set up tests and an overview (or links) to some of the tests we have implemented.
DISCLAIMER: This is not a tutorial on unit testing, phpunit, Laravel Dusk or anything else. If you have no experience with these tools, please read up on them elsewhere first.
"},{"location":"dev/ci/#setting-up-phpunit-tests","title":"Setting Up PHPUnit Tests","text":"Documentation by real example can be found via the GitHub Actions workflow files and the CI data directory which contains scripts, database dumps and configurations.
Testing assumes a known good sample database which contains a small mix of customers with different configuration options. The files generated from this database are tested against known good configuration files. You first need to create a database, add a database user, import this testing database and then configure a .env file for testing (see the one here use here).
In MySQL:
CREATE DATABASE ixp_ci CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_unicode_ci';\nGRANT ALL ON `ixp_ci`.* TO `ixp_ci`@`localhost` IDENTIFIED BY 'somepassword';\nFLUSH PRIVILEGES;\nThen import the sample database:
cat data/ci/ci_test_db.sql.bz2 | mysql -h localhost -u ixp_ci -psomepassword ixp_ci\nNow, create your .env for testing, such as:
DB_HOST=localhost\nDB_DATABASE=ixp_ci\nDB_USERNAME=ixp_ci\nDB_PASSWORD=somepassword\nNote that the phpunit.xml file in the root directory has some default settings matching the test database. You should not need to edit these.
Please review the official documentation here.
You need to ensure the development packages for IXP Manager are installed via:
# move to the root directory of IXP Manager\ncd $IXPROOT\ncomposer install --dev\nYou need to set the APP_URL environment variable in your .env file. This value should match the URL you use to access your application in a browser.
travis / travisci.hecustadmin / travisci and imcustadmin / travisci.hecustuser / travisci and imcustuser / travisci.In one console session, start the artisan / Laravel web server:
# move to the root directory of IXP Manager\ncd $IXPROOT\nphp artisan serve\nAnd then kick off all the tests which includes PHPUnit and Laravel Dusk tests, run:
./vendor/bin/phpunit\nSample output:
PHPUnit 7.2.2 by Sebastian Bergmann and contributors.\n\n............................................................... 63 / 144 ( 43%)\n............................................................... 126 / 144 ( 87%)\n.................. 144 / 144 (100%)\n\nTime: 1.86 minutes, Memory: 103.73MB\nIf you only want to run Laravel Dusk / browser tests, run the following (shown with sample output):
$ php artisan dusk\nPHPUnit 6.5.8 by Sebastian Bergmann and contributors.\n\n.. 2 / 2 (100%)\n\nTime: 12.73 seconds, Memory: 24.00MB\nIf you want to exclude the browser based tests, just exclude that directory as follows:
$ ./vendor/bin/phpunit --filter '/^((?!Tests\\\\Browser).)*$/'\nPHPUnit 7.2.2 by Sebastian Bergmann and contributors.\n\n............................................................... 63 / 142 ( 44%)\n............................................................... 126 / 142 ( 88%)\n................ 142 / 142 (100%)\n\nTime: 1.59 minutes, Memory: 106.41MB\nYou can also limit tests to specific test suites:
$ ./vendor/bin/phpunit --testsuite 'Dusk / Browser Test Suite'\n$ ./vendor/bin/phpunit --testsuite 'Docstore Test Suite'\n$ ./vendor/bin/phpunit --testsuite 'IXP Manager Test Suite'\nPlease see the contributing instructions for full details.
Third-party patches are welcomed for adding functionality and fixing bugs. Before they can be accepted into the project, contributors must sign the below Contributor License Agreement (gpg --clearsign inex-cla.txt) and email it to operations (at) inex (dot) ie.
Individual Contributor License Agreement v1.1\n=============================================\n\nInternet Neutral Exchange Association Company Limited By Guarantee\n\nThis document clarifies the terms under which You, the person listed below,\nmay make Contributions \u2014 which may include without limitation, software, bug\nfixes, configuration changes, documentation, or any other materials \u2014 to any\nof the projects owned or managed by Internet Neutral Exchange Association\nCompany Limited By Guarantee, hereinafter known as \"INEX\".\n\nPlease complete the following information about You and the Contributions.\nIf You have questions about these terms, please contact us at\noperations@inex.ie.\n\nYou accept and agree to the following terms and conditions for Your present\nand future Contributions submitted to INEX. Except for the license granted\nherein to INEX, You reserve all right, title, and interest in and to Your\nContributions.\n\nINEX projects (code, documentation, and any other materials) are released\nunder the terms of the GNU General Public License, v2.0.\n\nYou certify that:\n\n(a) Your Contributions are created in whole or in part by You and You have\nthe right to submit it under the designated license; or\n\n(b) Your Contributions are based upon previous work that, to the best of\nyour knowledge, is covered under an appropriate open source license and You\nhave the right under that license to submit that work with modifications,\nwhether created in whole or in part by You, under the designated license; or\n\n(c) Your Contributions are provided directly to You by some other person who\ncertified (a) or (b) and You have not modified them.\n\n(d) You understand and agree that INEX projects and Your Contributions are\npublic and that a record of the Contributions (including all metadata and\npersonal information You submit with them) is maintained indefinitely and\nmay be redistributed in a manner consistent with INEX's policies and/or the\nrequirements of the GNU General Public License v2.0 where they are relevant.\n\n(e) You are granting Your Contributions to INEX under the terms of the GNU\nGeneral Public License v2.0.\n\nFull Name:\nEmail Addresses:\nDate:\nFor development purposes, we have both Docker and Vagrant build files.
This page on Docker for IXP Manager development should be read in conjunction with the official IXP Manager Docker repository. While that repository is not for development purposes, the terminology and container descriptions apply here also.
"},{"location":"dev/docker/#tldr-guide-to-get-docker-running","title":"TL;DR Guide to Get Docker Running","text":"If you want to get IXP Manager with Docker up and running quickly, follow these steps:
Clone IXP Manager to a directory:
git clone https://github.com/inex/IXP-Manager.git ixpmanager\ncd ixpmanager\ncp .env.docker .env\ncp tools/docker/containers/mysql/docker.sql.dist tools/docker/containers/mysql/docker.sql\nSpin up the Docker containers
docker-compose -p ixpm up\nAccess IXP Manager on: http://localhost:8880/
Log in with one of the following username / passwords:
Admin user: docker / docker01
as112admin / as112adminas112user / as112userAs the IXP Manager ecosystem grows, it becomes harder and harder to maintain ubiquitous development environments. Docker is ideally suited to solving these issues.
The multi-container Docker environment for developing IXP Manager builds an IXP Manager system which includes:
The following are a list of Docker commands that are useful in general but also specifically for the IXP Manager Docker environment.
Note that in our examples, we set the Docker project name to ixpm and so that prefix is used in some of the below. We also assume that only one IXP Manager Docker environments is running and so we complete Docker container names with _1.
# show all running containers\ndocker ps\n\n# show all containers - running and stopped\ndocker ps -a\n\n# stop a container:\ndocker stop <container>\n\n# start a container:\ndocker start <container>\n\n# we create a 'ixpmanager' network. Sometimes you need to delete this when\n# stopping / starting the environment\ndocker network rm ixpm_ixpmanager\n\n# you can copy files into a docker container via:\ndocker cp test.sql ixmp_mysql_1:/tmp\n# where 'ixmp_mysql_1' is the container name.\n# reverse it to copy a file out:\ndocker cp ixmp_mysql_1:/tmp/dump.sql .\n\n# I use two useful aliases for stopping and removing all containers:\nalias docker-stop-all='docker stop $(docker ps -a -q)'\nalias docker-rm-all='docker rm $(docker ps -a -q)'\n\n# You can also remove all unused (unattached) volumes:\ndocker volume prune\n# WARNING: you might want to check what will be deleted with:\ndocker volume ls -f dangling=true\nAs above, please note that in our examples, we set the Docker project name to ixpm and so that prefix is used in some of the below. We also assume that only one IXP Manager Docker environments is running and so we complete Docker container names with _1.
For most routine development use, you only need two containers usually:
docker-compose -p ixpm up mysql www\nIf you are sending emails as part of your development process, include the mail catcher:
docker-compose -p ixpm up mysql www mailcatcher\nWhen the mysql container builds, it pre-populates the database with the contents of the SQL file found at tools/docker/containers/mysql/docker.sql. This is not present by default and is ignored by Git (to ensure you do not accidentally commit a production database!).
A default SQL database is bundled and should be placed in this location via:
cp tools/docker/containers/mysql/docker.sql.dist tools/docker/containers/mysql/docker.sql\nYou can put your own database here also. If you do, you will need to rebuilt the mysql contain:
docker-compose build mysql\nYou can access the MySQL database via:
docker exec -it ixpm_mysql_1 mysql -i ixpmanager\nAnd you can get shell access to the container with:
docker exec -it ixpm_mysql_1 bash\nYou can also connect to the MySQL server from your local machine using tools such as the standard MySQL client, TablePlus or Sequel Pro with the following settings:
mysql --protocol=TCP --port 33060 -u root\nNote that the www container mounts the IXP Manager development directory under /srv/ixpmanager. This means all local code changes are immediately reflected on the Docker web server.
The Dockerfile used to build the www container can be found at tools/docker/containers/www/Dockerfile.
You can access the container with:
docker exec -it ixpm_www_1 bash\nWe include a mailcatcher container which catches all emails IXP Manager sends and displays them on a web frontend. Ensure this container is started by either:
# start all containers:\ndocker-compose -p ixpm up\n# start mailcatcher with (at least) mysql and www:\ndocker-compose -p ixpm up mysql www mailcatcher\nThe .env.docker config contains the following SMTP / mail settings which ensure emails get send to the mailcatcher:
MAIL_HOST=172.30.201.11\nMAIL_PORT=1025\nYou can then view emails sent on: http://localhost:1080/
"},{"location":"dev/docker/#emulating-switches","title":"Emulating Switches","text":"ixpm_switch1_1 and ixpm_switch2_1 emulate switches by replaying SNMP dumps from real INEX switches (with some sanitisation). The OIDs for traffic have been replaced with a dynamic function to give varying values.
From the www container, you can interact with these via:
$ docker exec -it ixpm_www_1 bash\n# ping switch1\n...\n64 bytes from switch1 (172.30.201.60): icmp_seq=1 ttl=64 time=0.135 ms\n...\n# ping switch2\n...\n64 bytes from switch2 (172.30.201.61): icmp_seq=1 ttl=64 time=0.150 ms\n...\n\n\n# snmpwalk -On -v 2c -c switch1 switch1 .1.3.6.1.2.1.1.5.0\n.1.3.6.1.2.1.1.5.0 = STRING: \"switch1\"\n# snmpwalk -On -v 2c -c switch2 switch2 .1.3.6.1.2.1.1.5.0\n.1.3.6.1.2.1.1.5.0 = STRING: \"switch2\"\nYou'll note from the above that the hostnames switch1 and switch2 work from the www container. Note also that the SNMP community is the hostname (switch1 or switch2 as appropriate).
The packaged database only contains switch1. This allows you can add the second switch via http://localhost:8880/switch/add-by-snmp by setting the hostname and community to switch2.
If you want to add new customers for testing, add switch2 and then use interfaces Ethernet 2, 8, 13 and 6 and 7 as a lag as these have been preset to provide dynamic stats.
The containers include a working route server (ixpm_rs1_1) with 3 IPv4 clients (ixpm_cust-as112_1, ixpm_cust-as42_1, ixpm_cust-as1213_1) and and 2 IPv6 clients (ixpm_cust-as1213-v6_1, ixpm_cust-as25441-v6_1). IXP Manager also includes a working looking glass for this with Bird's Eye installed on the route server.
You can access the Bird BGP clients on the five sample customers using the following examples:
# access Bird command line interface:\ndocker exec -it ixpm_cust-as112_1 birdc\n\n# run a specific Bird command\ndocker exec -it ixpm_cust-as112_1 birdc show protocols\nThe route server runs an IPv4 and an IPv6 daemon. These can be accessed via the looking glass at http://127.0.0.1:8881/ or on the command line via:
# ipv4 daemon:\ndocker exec -it ixpm_rs1_1 birdc -s /var/run/bird/bird-rs1-ipv4.ctl\n\n# ipv6 daemon:\ndocker exec -it ixpm_rs1_1 birdc6 -s /var/run/bird/bird-rs1-ipv6.ctl\nIn this container, Bird's Eye can be found at /srv/birdseye with the web server config under /etc/lighttpd/lighttpd.conf.
We include the IXP Manager scripts for updating the route server configuration and reconfiguring Bird:
# get shell access to the container\ndocker exec -it ixpm_rs1_1 bash\n\n# all scripts under the following directory\ncd /usr/local/sbin/\n\n# reconfigure both daemons:\n./api-reconfigure-all-v4.sh\n\n# reconfigure a specific daemon with verbosity:\n./api-reconfigure-v4.sh -d -h rs1-ipv4\nFor developing / testing Grapher with Mrtg, we include a container that runs Mrtg via cron from a pre-configured mrtg.conf file.
NB: please ensure to update the GRAPHER_BACKENDS option in .env so it includes mrtg as follows:
GRAPHER_BACKENDS=\"mrtg|dummy\"\nThe configuration file matches the docker.sql configuration and can be seen in the IXP Manager source directory at tools/docker/mrtg/mrtg.cfg.
You can access the Mrtg container via:
docker exec -it ixpm_mrtg_1 sh\nWe also install a script in the root directory of the container that will pull a new configuration from IXP Manager. Run it via:
docker exec -it ixpm_mrtg_1 sh\ncd /\n./update-mrtg-conf.sh\n\n# or without entering the container:\ndocker exec -it ixpm_mrtg_1 /update-mrtg-conf.sh\nIt will replace /etc/mrtg.conf for the next cron run. It also sets the configuration not to run as a daemon as cron is more useful for development.
In this example, we look at the ixpmanager/www Docker image and update it from base php:7.0-apache to php:7.3-apache:
cd cd tools/docker/containers/www\n# replace:\n# FROM php:7.0-apache\n# with:\n# FROM php:7.3-apache\ndocker build .\n# or tag with: docker build -t ixpmanager/www:v5.0.0\ndocker push\n# if you're not logged in, use: docker login\nDo not forget to update your docker-compose.yml files to reference the new tag.
"},{"location":"dev/docker/#dev-tool-integrations","title":"Dev Tool Integrations","text":"NB: these tools and integrations are not IXP Manager specific but rather the typical Docker / PHP development tool chain. Please use support forums for the relevant sections / tools rather than contacting the IXP Manager developers directly.
"},{"location":"dev/docker/#php-storm-and-xdebug","title":"PHP Storm and Xdebug","text":"We are big fans of PhpStorm at IXP Manager DevHQ. One key feature is PhpStorm's integration with PHP Xdebug. We of course also need this to work with Docker.
Some background information on Xdebug is provided below but you are expected to be familiar with the Xdebug documentation on remote debugging.
The way interactive remote debugging works with Xdebug is as follows:
php.ini settings on the www container).To get this working with Docker, we need to work through each of these steps.
1. Enable Remote Debugging in the Docker Container
If you examine the www container Dockerfile in the IXP Manager source under tools/docker/containers/www/Dockerfile, you will see that we:
pecl install xdebug)./usr/local/etc/php/conf.d/local-ixpmanager-xdebug.ini as follows:[xdebug]\nzend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20151012/xdebug.so\nxdebug.remote_enable=1\nxdebug.remote_port=9001\nxdebug.remote_autostart=0\nxdebug.idekey=PHPSTORM\nxdebug.profiler_enable=0\nxdebug.profiler_enable_trigger=1\nxdebug.profiler_output_dir=/srv/ixpmanager/storage/tmp\nxdebug.auto_trace=0\nxdebug.trace_enable_trigger=1\nxdebug.trace_output_dir=/srv/ixpmanager/storage/tmp\nNote that the zend_extension may change as it is dynamically set by the build script. We also chose port 9001 rather than the default of 9000 due to local conflicts with common tool chains.
The one key element that is missing in the INI is the remote debugger IP address. This needs to be set to your development computer's LAN address (there are other options but this works best in practice). Once you know this address (say it's 192.0.2.23), set the following in the ${IXPROOT}/.env:
# For PHP xdebug, put in the IP address of your host\nDOCKER_XDEBUG_CONFIG_REMOTE_HOST=192.0.2.23\nWhen you start the Docker environment from $IXPROOT using docker-compose with something like:
cd $IXPROOT\ndocker-compose -p ixpm up mysql www\nthen docker-compose will use this setting from the .env file and it will be passed through the Xdebug.
2. Install a Xdebug Plugin on Your Browser
Some recommended plugins from the Xdebug documentation on remote debugging are these: Firefox, Chrome, Safari. It can also be enabled manually using a GET parameter - see the Xdebug documentation.
The only required parameter is the session key. For PhpStorm, the default is PHPSTORM unless you have configured it differently (see step 3 below).
The PHP Xdebug browser plugins allow you to enable debugging on a per request basis. See the Firefox link above to the plugin homepage for screenshots (as of 2018-01 at least).
3. Configure PhpStorm
PhpStorm have their own documentation for Xdebug. The short version to match the above two steps is:
You now need to create a Run/Debug Configuration. This is so you can map file paths on the remote system (www container) to your local development files:
For testing, set a break point in public/index.php and access your development IXP Manager using your new browser plugin. You should be able to step through each statement and - presuming your mappings are correctly set up - step into any file in the project.
Profiling and Function Traces
You may have noticed in the Xdebug configuration above, we have allowed for the triggering of function traces and profiling also. The browser plugins should support these - certainly the Firefox one does (leave the trigger key blank in both cases).
When you request an IXP Manager page via Firefox with profiling enabled, you will find the cachegrind file in $IXPROOT/storage/tmp on your own system You can then view this in PhpStorm via the menu Tools -> Analyze Xdebug Profiler Snapshot....
Function traces can be found in the same directory - these are just text files.
"},{"location":"dev/docs/","title":"Documentation","text":"From v4 onwards, we use GitHub Pages with MkDocs to build the documentation.
Both the site and the content are hosted on GitHub.
"},{"location":"dev/docs/#contributing-suggesting-errata","title":"Contributing / Suggesting Errata","text":"We welcome contributions or errata that improve the quality of our documentation. Please use one of the following two channels:
If you haven't already, install MkDocs. These instructions work on MacOS as of 2024:
# create a venv\npython3 -m venv venv\ncd venv\n\n# install mkdocs\n./bin/pip install mkdocs mike pymdown-extensions mkdocs-material mkdocs-git-revision-date-localized-plugin\nThe documentation can then be built locally as follows:
git clone https://github.com/inex/ixp-manager-docs-md.git\ncd ixp-manager-docs-md\n./venv/bin/mkdocs build\nYou can serve them locally with the following and then access them via http://127.0.0.1:8000 -
./venv/bin/mkdocs serve\nOr to see the full versioning site, use:
./venv/bin/mike serve\nSince September 2024, we now use documentation versioning and so you should only be pushing to the latest major.minor release of the dev major.minor version.
Never deploy to historical versions!
As an example, as the time of writing, 6.4.x is the latest release and 7.0 is in development. We did our final push to 6.4 via:
PATH=./venv/bin:$PATH ./venv/bin/mike deploy --push --update-aliases 6.4 latest\nAnd all new documentation will be pushed to dev via:
PATH=./venv/bin:$PATH ./venv/bin/mike deploy --push --update-aliases 7.0 dev\nOnce 7.0 is released, we will push a final update to 7.0 updating it to latest:
PATH=./venv/bin:$PATH ./venv/bin/mike deploy --push --update-aliases 7.0 latest\nAnd all new documentation will be pushed to dev via:
PATH=./venv/bin:$PATH ./venv/bin/mike deploy --push --update-aliases 7.1 dev\nNote that PATH=./venv/bin:$PATH is used as mike in turn calls mkdocs which is in this path.
You must be an authorised user for this but we welcome pull requests against the documentation repository!
Do not forget to push your changes to GutHub (if you have push permissions):
git add .\ngit commit -am \"your commit message\"\ngit push\nFoil is the view layer of IXP Manager.
"},{"location":"dev/foil/#undefined-variables","title":"Undefined Variables","text":"Foil is configured to throw an exception if a variable is undefined.
Methods to test a variable include:
<?= isset( $t->aaa ) ? 'b' : 'c' ?>\n// c\nMethods that do not work include:
<?= $t->aaa ?? 'c' ?>\nThis page collates various notes and bets practice for writing HTML forms with IXP Manager and Laravel.
IXP Manager uses the library Former to generate forms. Here are some examples of how to use Former.
"},{"location":"dev/forms/#html5-validation","title":"HTML5 Validation","text":"Former adds HTML5 validation tags when it created forms. If you wish to test the PHP code's validation rules, you will need to disable this is development by setting the following .env setting:
FORMER_LIVE_VALIDATION=false\nWe had some issues using Former's checkboxes correctly - this is why we are providing the correct way to use them.
"},{"location":"dev/forms/#configuration","title":"Configuration","text":"First make sure that the Former configuration file (config/former.php) is correctly configured:
// Whether checkboxes should always be present in the POST data,\n// no matter if you checked them or not\n'push_checkboxes' => true,\n\n// The value a checkbox will have in the POST array if unchecked\n'unchecked_value' => 0,\nThe following is the structure of a checkbox input:
Former::checkbox( 'checkbox-name' ) will be the HTML name=\"\" of the input in the DOM.->id( 'checkbox-id' ) will be the HTML `id=\"\"`` of the input in the DOM, it is not required and defaults to the name above.->label( 'my-label' ) will be the label of the input displayed on the left of the checkbox, it is not required. If you are just using a right hand side text label, setting this to ' ' can help improve layout.->label( 'my-text' ) will be the text of the input displayed on the right of the checkbox, it is not required.->value( 1 ) this is really important for the correct functioning of the checkboxes.->blockHelp( \"help text\u201d) will be the help text of the checkbox.Note: in this example the checkbox will be unchecked:
Former::checkbox( 'checkbox-name' )\n ->id( 'checkbox-id' )\n ->label( 'my-label' )\n ->text( 'my-text' )\n ->value( 1 )\n ->blockHelp( \"Help text\u201d );\nTo check a checkbox by default add the following function to the checkbox structure above:
->check()\nIf the checkbox has to be checked depending on a variable:
->check( $myVariableIsChecked ? 1 : 0 )\nNote: The above case should be an exception and not a common way to populate the checkboxes. To populate the checkboxes correctly you have to do it via the controller as explained below.
"},{"location":"dev/forms/#controller","title":"Controller","text":"You can populate a form via the controller with the function Former::populate() by the usual method of passing an array of values:
Former::populate([\n 'my-checkbox' => $object->isChecked() ? 1 : 0,\n]);\nIXP Manager uses the library Mardown to edit notes input field. Here are some examples of how to use Markdown.
"},{"location":"dev/forms/#view_1","title":"View","text":"You will have to use the following HTML structure to be able to add markdown to your textrea :
<div class=\"form-group\">\n <label for=\"notes\" class=\"control-label col-lg-2 col-sm-4\">Notes</label>\n <div class=\"col-sm-8\">\n <ul class=\"nav nav-tabs\">\n <li role=\"presentation\" class=\"active\">\n <a class=\"tab-link-body-note\" href=\"#body\">Body</a>\n </li>\n <li role=\"presentation\">\n <a class=\"tab-link-preview-note\" href=\"#preview\">Preview</a>\n </li>\n </ul>\n <br>\n <div class=\"tab-content\">\n <div role=\"tabpanel\" class=\"tab-pane active\" id=\"body\">\n <textarea class=\"form-control\" style=\"font-family:monospace;\" rows=\"20\" id=\"notes\" name=\"notes\"><?= $note_value ?></textarea>\n </div>\n <div role=\"tabpanel\" class=\"tab-pane\" id=\"preview\">\n <div class=\"well well-preview\" style=\"background: rgb(255,255,255);\">\n Loading...\n </div>\n </div>\n </div>\n <br><br>\n </div>\n</div>\nhref=\"#body\" from <a id=\"tab-link-body\" class=\"tab-link-body-note\" href=\"#body\">Body</a> have to match with the id=\"body\" from <div role=\"tabpanel\" class=\"tab-pane active\" id=\"body\">. The same for <a id=\"tab-link-preview\" class=\"tab-link-preview-note\" href=\"#preview\">Preview</a> and <div role=\"tabpanel\" class=\"tab-pane\" id=\"preview\">.
If you want to add more than one textarea with markdown to your page you will have to make sure that the HTML ID of the inputs are different like on the following example :
<div class=\"form-group\">\n <label for=\"notes\" class=\"control-label col-lg-2 col-sm-4\">Public Notes</label>\n <div class=\"col-sm-8\">\n\n <ul class=\"nav nav-tabs\">\n <li role=\"presentation\" class=\"active\">\n <a class=\"tab-link-body-note\" href=\"#body1\">Body</a>\n </li>\n <li role=\"presentation\">\n <a class=\"tab-link-preview-note\" href=\"#preview1\">Preview</a>\n </li>\n </ul>\n\n <br>\n\n <div class=\"tab-content\">\n <div role=\"tabpanel\" class=\"tab-pane active\" id=\"body1\">\n <textarea class=\"form-control\" style=\"font-family:monospace;\" rows=\"20\" id=\"notes\" name=\"notes\"><?= $t->notes ?></textarea>\n <p class=\"help-block\">These notes are visible (but not editable) to the member. You can use markdown here.</p>\n </div>\n <div role=\"tabpanel\" class=\"tab-pane\" id=\"preview1\">\n <div class=\"well well-preview\" style=\"background: rgb(255,255,255);\">\n Loading...\n </div>\n </div>\n </div>\n\n <br><br>\n </div>\n\n</div>\n\n\n<div class=\"form-group\">\n\n <label for=\"private_notes\" class=\"control-label col-lg-2 col-sm-4\">Private Notes</label>\n <div class=\"col-sm-8\">\n\n <ul class=\"nav nav-tabs\">\n <li role=\"presentation\" class=\"active\">\n <a class=\"tab-link-body-note\" href=\"#body2\">Body</a>\n </li>\n <li role=\"presentation\">\n <a class=\"tab-link-preview-note\" href=\"#preview2\">Preview</a> \n </li>\n </ul>\n\n <br>\n\n <div class=\"tab-content\">\n <div role=\"tabpanel\" class=\"tab-pane active\" id=\"body2\">\n <textarea class=\"form-control\" style=\"font-family:monospace;\" rows=\"20\" id=\"private_notes\" name=\"private_notes\"><?= $t->private_notes ?></textarea>\n <p class=\"help-block\">These notes are <b>NOT</b> visible to the member. You can use markdown here.</p>\n </div>\n <div role=\"tabpanel\" class=\"tab-pane\" id=\"preview2\">\n <div class=\"well well-preview\" style=\"background: rgb(255,255,255);\">\n Loading...\n </div>\n </div>\n </div>\n\n <br><br>\n </div>\n\n</div>\nNote: Please do not change the HTML class of the elements!
"},{"location":"dev/frontend-crud/","title":"Frontend CRUD","text":"IXP Manager, like many applications, has a lot of tables that need basic CRUD access: Ceate, Read, Update and Delete (plus list and view). In older versions of IXP Manager (and as yet unupdated code), we used this Zend Framework trait to allow us to repidly deploy CRUD interfaces.
For IXP Manager >= v4.7, we have duplicated (and improved) this to create a scaffolding framework in Laravel. This page documents that class.
"},{"location":"dev/frontend-crud/#configuration","title":"Configuration","text":"In any controller using extending the Doctrine2Frontend class, a _feInit() method is required which configures the controller and, for example, allows you to set what is displayed for different levels of user privileges.
The primary purpose of this function is to define the anonymous object _feParams (using an object ensures that the view gets a reference to the object and not a copy of a static array at a point in time):
<?php\nprotected function _feInit()\n{\n $this->view->feParams = $this->_feParams = (object)[\n\n // the ORM entity object that CRUD operations will affect:\n 'entity' => InfrastructureEntity::class,\n\n 'pagetitle' => 'Infrastructures',\n\n // default is false. If true, add / edit / delete will be disabled\n 'readonly' => false,\n\n 'titleSingular' => 'Infrastructure',\n 'nameSingular' => 'an infrastructure',\n\n 'viewFolderName' => 'infrastructure',\n\n 'readonly' => self::$read_only,\n\n 'listColumns' => [\n // what columns to display in the list view\n 'id' => [ 'title' => 'DB ID', 'display' => true ],\n 'name' => 'Name',\n 'shortname' => 'Shortname'\n ],\n\n 'listOrderBy' => 'name', // how to order columns\n 'listOrderByDir' => 'ASC', // direction of order columns\n ];\n\n // you can then override some of the above for different user privileges (for example)\n switch( Auth::user() ? Auth::user()->getPrivs() : UserEntity::AUTH_PUBLIC ) {\n\n case UserEntity::AUTH_SUPERUSER:\n $this->_feParams->pagetitle = 'Infrastructures (Superuser View)';\n\n $this->_feParams->listColumns = array_merge(\n $this->_feParams->listColumns, [\n // ...\n ];\n );\n break;\n\n default:\n if( php_sapi_name() !== \"cli\" ) {\n abort( 'error/insufficient-permissions' );\n }\n }\n\n // display the same information in the single object view as the list of objects\n $this->_feParams->viewColumns = $this->_feParams->listColumns;\n}\nBy default, all Doctrine2Frontend controllers can only be accessed by an authenticated super user (Entities\\User::AUTH_SUPERUSER). You can change this by setting the following property on your implementation:
<?php\n/**\n * The minimum privileges required to access this controller.\n *\n * If you set this to less than the superuser, you need to manage privileges and access\n * within your own implementation yourself.\n *\n * @var int\n */\npublic static $minimum_privilege = UserEntity::AUTH_SUPERUSER;\nIf you set this to less than the superuser, you need to manage privileges and access within your own implementation yourself.
This is normally handled in a number of ways:
Request object utilising the authorize() method;feInit()The feInit() method would normally look something like the following:
<?php\n// phpunit / artisan trips up here without the cli test:\nif( php_sapi_name() !== 'cli' ) {\n\n // custom access controls:\n switch( Auth::check() ? Auth::user()->getPrivs() : UserEntity::AUTH_PUBLIC ) {\n case UserEntity::AUTH_SUPERUSER:\n break;\n\n case UserEntity::AUTH_CUSTUSER:\n switch( Route::current()->getName() ) {\n case 'Layer2AddressController@forVlanInterface':\n break;\n\n default:\n $this->unauthorized();\n }\n break;\n\n default:\n $this->unauthorized();\n }\n}\nThe $this->unauthorized( $url = '', $code = 302 ) calls abort() with the given redirect code and URL. The default parameters will do the right thing.
Routes are explicitly defined in Laravel. The Doctrine2Frontend class sets up the standard routes automatically once you add the following to your routes/web.php (or as appropriate) file on a per implementation basis. E.g. for the Infrastructure implementation, we add to routes/web-doctrine2frontend.php:
<?php\nIXP\\Http\\Controllers\\InfrastructureController::routes();\nNote that by placing the above in routes/web-doctrine2frontend.php, you ensure the appropriate middleware is attached.
This routes() function determines the route prefix using kebab case of the controller name. That is to say: if the controller is CustKitController, the determined prefix is cust-kit. You can override this by setting a $route_prefix class constant in your implementation.
The standard routes added (using infrastructure as an example) are:
infrastructure/addinfrastructure/edit/{id}infrastructure/listinfrastructure/view/{id}infrastructure/delete/{id}infrastructure/storeIf you want to create your own additional routes, create a function as follows in your implementation:
<?php\npublic static function additionalRoutes( $route_prefix ) {}\nAnd add routes (using the normal Route::get() / ::post() / etc Laravel methods).
If you want to completely change the routes, just override the public static function routes() {} function.
All the common view templates for thss functionality can be found in resources/views/frontend directory. You can override any of these with your own by creating a template of the same name and placing it under resources/views/xxx (or resources/skins/skinname/xxx) where xxx is the feParams['viewFolderName'].
If your controller should be read only (list and view actions, no add, edit or delete) then set the following static member:
<?php\n/**\n * Is this a read only controller?\n *\n * @var boolean\n */\npublic static $read_only = true;\nEach of the typical CRUD actions will be described here.
NB: the best documentation is sometimes the code. Check out the above routes file (routes/web-doctrine2frontend.php) and examine some of the implemented controllers directly.
The list action is for listing the contents of a database table in a HTML / DataTables view.
The only requirement of the list action is that the following abstract function is implemented:
<?php\n/**\n * Provide array of table rows for the list action (and view action)\n *\n * @param int $id The `id` of the row to load for `view` action. `null` if `list` action.\n * @return array\n */\nabstract protected function listGetData( $id = null );\nA sample implementation for the infrastructure controller just calls a Doctrine2 repository function:
<?php\nprotected function listGetData( $id = null ) {\n return D2EM::getRepository( InfrastructureEntity::class )->getAllForFeList( $this->feParams, $id );\n}\nThe table rows returned in the above array must be associatative arrays with keys matching the feParams['listColumns'] definition.
The list view template optionally includes other templates you can define (where xxx below is the feParams['viewFolderName']):
resources/views/frontend/js/list which activates the DataTables, sets up sorting, etc. You can override this (and include the original if appropriate) if you want to add additional JS functionality.resources/views/xxx/list-preamble template exists, it is included just before the table.resources/views/xxx/list-postamble template exists, it is included just after the table.resources/views/xxx/list-head-override template exists, it will replace the <thead> element of the list table (example).resources/views/xxx/list-head-override template exists, it will replace the <tr> elements of the list table (example).resources/views/xxx/list-empty-message template exists, it will replace the the standard information box when a table is empty (example).The following hooks are available:
protected function preList():void {} - called before the list is displayed allowing you to add elements to the template, etc.The view action is for showing a single database row identified by the id passed in the URL.
The only requirement of the view action is that the abstract function listGetData( $id = null ) as used by the list action has been correctly implemented to take an optional ID and return an array with a single element matching that ID.
The table rows returned in the above array must be associatative arrays with keys matching the feParams['viewColumns'] definition.
The list view template optionally includes other templates you can define (where xxx below is the feParams['viewFolderName']):
resources/views/frontend/js/view.resources/views/xxx/view-preamble template exists, it is included just before the view panel.resources/views/xxx/view-postamble template exists, it is included just after the view panel.resources/views/xxx/view-row-override template exists, it will replace the <tr> element of the view (example).The presentation of the create / update (also known as add / edit) page is discussed here. Form processing and storage will be dealt with in the next section.
The first required element of this functionality is the implementation of the following abstract function:
<?php\nabstract protected function addEditPrepareForm( $id = null ): array;\nThe use of this function is best explained with reference to an implementation from the infrastructure controller:
<?php\n/**\n * Display the form to add/edit an object\n * @param int $id ID of the row to edit\n * @return array\n */\nprotected function addEditPrepareForm( $id = null ): array {\n if( $id !== null ) {\n\n if( !( $this->object = D2EM::getRepository( InfrastructureEntity::class )->find( $id) ) ) {\n abort(404);\n }\n\n $old = request()->old();\n\n // we use array_key_exists() here as the array can contain the\n // key with a null value.\n\n Former::populate([\n 'name' => array_key_exists( 'name', $old ) ? $old['name'] : $this->object->getName(),\n 'shortname' => array_key_exists( 'shortname', $old ) ? $old['shortname'] : $this->object->getShortname(),\n 'isPrimary' => array_key_exists( 'isPrimary', $old ) ? $old['isPrimary'] : ( $this->object->getIsPrimary() ?? false ),\n ]);\n }\n\n return [\n 'object' => $this->object,\n ];\n}\nNote from the above:
$t->params in the template. Note that $t->params['data'] is added later and contains the feParams object.The next required element is building the actual Former object for display. For this, you must create a custom resources/views/xxx/edit-form template. See, as an example, the infrastructure one under resources/views/infrastructure/edit-form.js.
The add/edit view template optionally includes other templates you can define (where xxx below is the feParams['viewFolderName']):
resources/views/xxx/js/edit.resources/views/xxx/edit-preamble template exists, it is included just before the view panel.resources/views/xxx/edit-postamble template exists, it is included just after the view panel.You can query the boolean $t->params['isAdd'] in your templates to distinguish between add and edit operations.
Storing the edited / new object requires implementing a single abstract method which manages validation and storage. This is best explained with a practical implementation:
<?php\n/**\n * Function to do the actual validation and storing of the submitted object.\n * @param Request $request\n * @return bool|RedirectResponse\n */\npublic function doStore( Request $request )\n{\n $validator = Validator::make( $request->all(), [\n 'name' => 'required|string|max:255',\n 'shortname' => 'required|string|max:255',\n ]);\n\n if( $validator->fails() ) {\n return Redirect::back()->withErrors($validator)->withInput();\n }\n\n if( $request->input( 'id', false ) ) {\n if( !( $this->object = D2EM::getRepository( InfrastructureEntity::class )->find( $request->input( 'id' ) ) ) ) {\n abort(404);\n }\n } else {\n $this->object = new InfrastructureEntity;\n D2EM::persist( $this->object );\n }\n\n $this->object->setName( $request->input( 'name' ) );\n $this->object->setShortname( $request->input( 'shortname' ) );\n $this->object->setIxfIxId( $request->input( 'ixf_ix_id' ) ? $request->input( 'ixf_ix_id' ) : null );\n $this->object->setPeeringdbIxId( $request->input( 'pdb_ixp' ) ? $request->input( 'pdb_ixp' ) : null );\n $this->object->setIsPrimary( $request->input( 'primary' ) ?? false );\n $this->object->setIXP( D2EM::getRepository( IXPEntity::class )->getDefault() );\n\n D2EM::flush($this->object);\n\n if( $this->object->getIsPrimary() ) {\n // reset the rest:\n /** @var InfrastructureEntity $i */\n foreach( D2EM::getRepository( InfrastructureEntity::class )->findAll() as $i ) {\n if( $i->getId() == $this->object->getId() || !$i->getIsPrimary() ) {\n continue;\n }\n $i->setIsPrimary( false );\n }\n D2EM::flush();\n }\n\n return true;\n}\nNote from this:
$this->object = $inf; as it is used to create log messages, etc.The following hooks are available:
protected function postStoreRedirect() {} - the Doctrine2Frontend class returns null. Override it to return a valid route name to have the post store redirect go somewhere besides /list.$this->store_alert_success_message (string) in doStore().Deletes are handled via posts and so have Laravel's built in CSRF protection. The logic is quiet simple:
<?php\npublic function delete( Request $request ) {\n\n if( !( $this->object = D2EM::getRepository( $this->feParams->entity )->find( $request->input( 'id' ) ) ) ) {\n return abort( '404' );\n }\n\n if( $this->preDelete() ) {\n D2EM::remove( $this->object );\n D2EM::flush();\n $this->postFlush( 'delete' );\n AlertContainer::push( $this->feParams->titleSingular . \" deleted.\", Alert::SUCCESS );\n }\n\n return redirect()->action( $this->feParams->defaultController.'@'.$this->feParams->defaultAction );\n}\nAs you can see, it calls a protected function preDelete(): bool {} hook which, if it returns false, the delete operation is abandoned.
The following hooks are available:
* `protected function postDeleteRedirect() {}` - the *Doctrine2Frontend* class returns null. Override it to return\n a valid route name to have the post store redirect go somewhere besides `/list`.\nThere is a postFlush() hook:
<?php\n/**\n * Optional method to be overridden if a D2F controllers needs to perform post-database flush actions\n *\n * @param string $action Either 'add', 'edit', 'delete'\n * @return bool\n */\nprotected function postFlush( string $action ): bool\n{\n return true;\n}\nwhich is called during some actions with the action name as a parameter: add, edit, delete. This function is called just after the database flush operation.
This is a quick write up as I commit a new graph type. To be fleshed out.
Our new graphing backend, Grapher, supports different graph types from different backends. To add a new graph type - let's call it Example - you need to do the following:
app/Services/Grapher/Graph/Example.php. This must extend the abstract class app/Services/Grapher/Graph.php.example() function to app/Services/Grapher.php which instantiates the above graph object.app/Services/Grapher/Backend/xxx) to handle this new graph file. I.e. create the actual implementation for getting the data to process this graph.supports() function in the appropriate backends (and the app/Services/Grapher/Backend/Dummy backend).To serve this graph over HTTP:
Create a GET route in app/Providers/GrapherServiceProvider.php
app/Http/Controllers/Services/Grapher.phpapp/Http/Middleware/Services/Grapher.phpHere's a great example from a Github commit.
"},{"location":"dev/grapher/#adding-a-new-mrtg-graph","title":"Adding a New MRTG Graph","text":"Here is an example of adding broadcast graphs to MRTG.
"},{"location":"dev/helpders/","title":"Helpers","text":"Various helpers we use within IXP Manager.
"},{"location":"dev/helpders/#alerts","title":"Alerts","text":"To show Bootstrap-styled alerts on view (Foil) templates, add them in your controllers as follows:
<?php\n use IXP\\Utils\\View\\Alert\\Container as AlertContainer;\n use IXP\\Utils\\View\\Alert\\Alert;\n\n ...\n\n AlertContainer::push( '<b>Example:</b> This is a success alert!, Alert::SUCCESS );\nwhere the types available are: SUCCESS, INFO (default), DANGER, WARNING.
To then display (all) the alerts, in your foil template add:
<?= $t->alerts() ?>\nThese alerts are HTML-safe as they display the message using HTML Purifier's ''clean()''.
"},{"location":"dev/introduction/","title":"Development Introduction","text":"We welcome contributions to IXP Manager from the community. The main requirement is that you sign the contributor's license agreement.
"},{"location":"dev/introduction/#core-vs-packages","title":"Core vs Packages","text":"If you plan to add a significant / large piece of functionality, then please come and talk to us first via the mailing lists. There are two ways to get such contributions into IXP Manager:
The following is a reply to someone looking to contribute something that didn't fit with what IXP Manager's mission was which may also help anyone considering contributing.
We have learned the very (very) hard way to avoid adding non-core functionality into the core of IXP Manager. At INEX, we won't be using XXX in the short to medium term and nor are we aware of IX's that use it.
This means that XXX code will be non-core and not used or tested (or testable easily) by the core IXP Manager developers. This creates a bunch of issues including:
a) becomes a new consideration for IXP Manager updates and schema changes;
b) the IXP Manager issue tracker and mailing list will be the goto place for people seeking help with this functionality and we will not be able to provide that;
c) would require assurances of maintainers and support for XXX to the project - I'm not sure that can be given at this stage;
d) large features require documentation: https://docs.ixpmanager.org/
e) past experience has shown us that we often end up having to remove chunks of non-core functionality due to (a), (b) and (c) above and this is also costly on time.
Now, we really do not want to discourage adding XXX support to IXP Manager - I like the project and you have shown it can work at an IX. It'd be great to have it as part of the IXP Manager tool chain.
One of the advantages of switching from Zend Framework to Laravel has been the ability to have add on functionality by way of packages:
https://laravel.com/docs/5.6/packages
I think this is a perfect way to add XXX support and we can help ensuring UI hooks by detecting the packet and adding menu options.
This also solves all the issues above:
a) is not an impediment to upgrades: if the XXX package falls behind the pace of IXP Manager development and someone wants XXX support, they just install a version of IXP Manager that is aligned with the XXX package.
b) issue and support wise, having XXX as a package creates a clean line of delineation between IXP Manager and XXX code bases so people can raise issues and questions with the correct project.
c) is mostly answered by (a).
d) documentation becomes the purview of the XXX team and we can provide the appropriate links from ours.
"},{"location":"dev/introduction/#database-orms","title":"Database / ORMs","text":"As of v6.0.0, IXP Manager uses the Laravel Eloquent ORM, replacing the Doctrine ORM used in previous versions.
a) do not change the schema of any existing table. This would need to be done in IXP Manager core via Eloquent as part of a new release and should be discussed with the core developers.
b) ideally schema changes would be limited to namespaced (xxx_*) tables (where xxx represents your package / feature.)
IXP Manager has looking glass support allowing IXPs to expose details on route server / collector / AS112 BGP sessions to their members.
As it stands, we have only implemented one looking glass backend - Bird's Eye; a simple secure micro service for querying Bird (JSON API) (and also written by us, INEX).
We have implemented this in IXP Manager as a service so that other backends can be added easily.
Disclaimer: the links and line numbers here are against IXP Manager v4.5.0 and they may have changed since.
"},{"location":"dev/looking-glass/#adding-support-for-additional-lgs","title":"Adding Support for Additional LGs","text":"An additional API backend needs to be given a constant in Entities\\Router named API_TYPE_XXX where XXX is an appropriate name.
It then needs to have a case: check in app/Services/LookingGlass.php. This needs to instantiate your service provider.
Your service provider must implement the App\\Contracts\\LookingGlass interface.
For a concrete example, see the Bird's Eye implementation.
"},{"location":"dev/release-procedure/","title":"Release Procedure","text":"DRAFT: in advance of the v4.8.0 release, I am gathering some notes here towards writing for formal release procedure for new minor versions of IXP Manager.
release-v5..env.example has been updated with new options and comments.Laravel Telescope is an elegant debug assistant for the Laravel framework. Telescope provides insight into the requests coming into your application, exceptions, log entries, database queries, queued jobs, mail, notifications, cache operations, scheduled tasks, variable dumps and more. Telescope makes a wonderful companion to your local Laravel development environment.
"},{"location":"dev/users/","title":"Development Notes for User Management","text":"The project management of this m:n (customer:user) enhancement is an internal Island Bridge Networks issue and this page serves to expose that and more information publicly.
Read the official user documentation first as that will answer questions around how it is meant to work.
Here is the schema for customers / users around the time of the v5 release:
One for the goals of this enhancement was to try to not break as much existing functionality as possible. As an example, we would typically get the user's customer relation using $user->getCustomer() and this was linked via the user.custid column.
In developing this enhancement, we needed to track two things:
By using the user.custid for this purpose, we retained the ability to call $user->getCustomer() which meant the vast majority of existing code continued to work as expected.
So, the mechanism for switching a user from one customer to another is:
user.custid to the target customer ID;When logging in, the system will:
For development purposes, we have Vagrant build files.
The Vagrant file was updated for IXP Manager v7.
The entire system is built from a fresh Ubuntu 24.04 installation via the tools/vagrant/bootstrap.sh script. This also installs a systemd service to run tools/vagrant/startup.sh on a reboot to restart the various services.
Note the developers use Parallels (see below) and have not tested on VirtualBox for sometime.
If you want to get IXP Manager with Vagrant and VirtualBox up and running quickly, follow these steps:
Clone IXP Manager to a directory:
git clone https://github.com/inex/IXP-Manager.git ixpmanager\ncd ixpmanager\nEdit the Vagrantfile in the root of IXP Manager and delete the config.vm.provider \"parallels\" do |prl| block and uncomment the config.vm.provider \"virtualbox\" do |vb|.
Spin up a Vagrant virtual machine:
vagrant up\nbrew tap hashicorp/tap\nbrew install hashicorp/tap/hashicorp-vagrant\nvagrant plugin install vagrant-parallels\ngit clone https://github.com/inex/IXP-Manager.git ixpmanager\ncd ixpmanager\nvagrant up\nAccess IXP Manager on: http://localhost:8088/
Log in with one of the following username / passwords:
Admin user: vagrant / Vagrant1 (api key: r8sFfkGamCjrbbLC12yIoCJooIRXzY9CYPaLVz92GFQyGqLq)
as112 / AS112as112as112user / AS112as112Please see Vagrant's own documentation for a full description of how to use it fully.
To access the virtual machine that the above has spun up, just run the following from the ixpmanager directory:
vagrant ssh\nOnce logged into the Linux machine, you'll find the ixpmanager directory mounted under /vagrant.
sudo su - root/password via:mysql -u root -ppassword ixpmysql -u root -ppassword -h 127.0.0.1 -P 33061/vagrant in the Vagrant virtual machine. This is mounted as the vagrant user. Any changes made on your own machine are immediately reflected on the virtual machine and vice-versa.vagrant to avoid all file system permission issues.Spinning up Vagrant in the above manner loads a sample database from tools/vagrant/vagrant-base.sql. If you have a preferred development database, place a bzip'd copy of it in the ixpmanager directory called ixpmanager-preferred.sql.bz2 before step 5 above.
The Vagrant bootstrapping includes installing snmpsim making three \"switches\" matching those in the supplied database available for polling. The source snmpwalks for these are copied from tools/vagrant/snmpwalks to /srv/snmpclients and values can be freely edited there.
Example of polling when ssh'd into vagrant:
snmpwalk -c swi1-fac1-1 -v 2c swi1-fac1-1\nsnmpwalk -c swi1-fac2-1 -v 2c swi1-fac1-1\nsnmpwalk -c swi2-fac1-1 -v 2c swi2-fac1-1\nAs you can see, the community selects the source file - i.e., -c swi1-fac1-1 for /srv/snmpclients/swi1-fac1-1.snmprec. The Vagrant bootstrap file adds these switch names to /etc/hosts also.
The bootstrapping also configures mrtg to run and includes this in the crontab rather than using dummy graphs. The snmp simulator has some randomised elements for some of the interface counters.
"},{"location":"dev/vagrant/#route-server-collector-as112-testbed-and-looking-glass","title":"Route Server / Collector / AS112 Testbed and Looking Glass","text":"When running vagrant up for the first time, it will create a full route server / collector /as112 testbed complete with clients:
All Bird instance sockets are located in /var/run/bird/ allowing you to connect to them using birdc -s /var/run/bird/xxx.ctl.
In additional to this, a second Apache virtual host is set up listening on port 81 locally providing access to Birdseye installed in /srv/birdseye. The bundled Vagrant database is already configured for this and should work out of the box. All of Birdseye's env files are generated via:
php /vagrant/artisan vagrant:generate-birdseye-configurations\nVarious additional scripts support all of this:
tools/vagrant/bootstrap.sh file which sets everything up.tools/vagrant/scripts/refresh-router-testbed.sh will reconfigure all routers.tools/vagrant/scripts/as112-reconfigure-bird2.sh will (re)configure and start, if necessary, the AS112 Bird instances.tools/vagrant/scripts/rs-api-reconfigure-all.sh will (re)configure and start, if necessary, the route server Bird instances.tools/vagrant/scripts/rc-reconfigure.sh will (re)configure and start, if necessary, the route collector Bird instances.For the clients, we run the following:
mkdir -p /srv/clients\nchown -R vagrant: /srv/clients\nphp /vagrant/artisan vagrant:generate-client-router-configurations\nchmod a+x /srv/clients/start-reload-clients.sh\n/srv/clients/start-reload-clients.sh\nAll router IPs are added to the loopback interface as part of the tools/vagrant/bootstrap.sh (or the startup.sh script on a reboot). There are also necessary entries in /etc/hosts to map router handles to IP addresses. There are two critical Bird BGP configuration options to allow multiple instances to run on the same server and speak with each other:
strict bind yes;\nmultihop;\nIXP Manager has a number of API endpoints which are documented in the appropriate places throughout the documentation.
Please find details below about authenticating for API access to secured functions.
"},{"location":"features/api/#creating-an-api-key","title":"Creating an API Key","text":"When logged into IXP Manager, create an API as follows:
Treat your API key as a password and do not copy the below URLs into public websites and other public forums.
"},{"location":"features/api/#api-authentication","title":"API Authentication","text":"There are two ways to use your API key to authenticate to IXP Manager.
You can test these using the API test endpoint at api/v4/test. For example:
https://ixp.example.com/api/v4/test\nThe plaintext response will also indicate if you are authenticated or not (which can be via existing session or API key).
"},{"location":"features/api/#1-http-header-parameter","title":"1. HTTP Header Parameter","text":"You can pass your API key in the HTTP request as a request header parameter called X-IXP-Manager-API-Key. For example:
curl -X GET -H \"X-IXP-Manager-API-Key: my-api-key\" https://ixp.example.com/api/v4/test\nThis is a legacy method that is still supported. You can tack your key on as follows:
https://ixp.example.com/api/v4/test?apikey=my-api-key\nIn IXP Manager v5.1 we introduced some new API Key management features:
API keys are not shown by default but require a password to be entered to show them. If you wish to show the keys (inadvisable), you can set IXP_FE_API_KEYS_SHOW=true in .env. This is only available to mimic historic functionality and will be removed in the future.
By default, a user can create no more than 10 keys. If you wish to change this, set IXP_FE_API_KEYS_MAX=n in .env where n is an integer value > 0.
Prerequisite Reading: Ensure you first familiarize yourself with the generic documentation on managing and generating router configurations here.
AS112 is a service which provides anycast reverse DNS lookup for several prefixes, namely:
Because these IP addresses are widely used for private networking, many end-user systems are configured to perform reverse DNS lookups for these address ranges. DNS lookups for these ranges should always be null-answered quickly, in order to make sure that DNS retransmits don\u2019t occur (thereby overloading local DNS resolvers), and to prevent end-user systems from hanging due to DNS lookups.
AS112 services are provided around the world by a group of volunteers and, very often, by IXP operators for the benefit of their members.
INEX has always provided an AS112 service to our members on all peering LANs and so it is an integral part of IXP Manager. You can read all about INEX's implementation at https://www.inex.ie/technical/as112-service/ including graphs for the service. Feel free to use our test and examples from that page for your own IXP.
"},{"location":"features/as112/#building-an-as112-service","title":"Building an AS112 Service","text":"You can find instructions for building an AS112 service in rfc7534. You should also add AS112 redirection using DNAME functionality as per rfc7535.
You will also find a lot more information and how-tos on the official website at: https://www.as112.net/.
Follow these instructions in every way to build the AS112 service on a (virtual) machine with an appropriate DNS server - except skip the installation and configuration of the BGP daemon. When using IXP Manager, you will need to use Bird for this and IXP Manager will create the configuration.
"},{"location":"features/as112/#managing-your-as112-service-from-ixp-manager","title":"Managing Your AS112 Service from IXP Manager","text":"AS112 is disabled by default in IXP Manager. This really just means UI elements are hidden. To enable these, set the following in your .env file:
IXP_AS112_UI_ACTIVE=true\nThis will add UI elements including:
Enabling the AS112 service simply indicates if a BGP peering session should be created in the AS112 BGP configuration when downloading the AS112 router's BGP configuration from IXP Manager.
"},{"location":"features/as112/#creating-the-pro-bono-as112-customer","title":"Creating the Pro-Bono AS112 Customer","text":"You need to add the AS112 service as a pro-bono member of your IXP in IXP Manager. Here's INEX's example:
You then need to create an interface for the AS112 service on each peering LAN where the service will be offered. Here again is INEX's example from our peering LAN1 in Dublin:
Note that historically INEX has not used MD5 on our AS112 service. This is because the service dates from over 20 years ago at INEX when MD5 support was not available. There is no reason not to use MD5 on the service if you wish.
"},{"location":"features/as112/#generating-the-bird-configuration","title":"Generating the Bird Configuration","text":"Please see the router configuration generation for this.
For your AS112 server, we have a sample script(s) for pulling and updating the configuration from IXP Manager. We typically put this in an hourly cron.
"},{"location":"features/as112/#other-notes","title":"Other Notes","text":"At INEX, we typically have our AS112 service peer with our route servers.
This will happen automatically if you check the Route Server Client on the AS112 VLAN interface configuration (see above screen shot) and also check the AS112 Client checkbox on the VLAN interfaces of your route servers in IXP Manager. Note that in the same way as you create an AS112 pro-bono customer, you should also have a dedicated route server internal customer.
"},{"location":"features/console-servers/","title":"Console Servers","text":"An IXP would typically have out of band access (for emergencies, firmware upgrades, etc) to critical infrastructure devices by means of a console server.
IXP Manager has Console Servers and Console Server Connections menu options to allow IXP administrators add / edit / delete / list console server devices and, for any such device, record what console server port is connected to what device (as well as connection characteristics such as baud rate).
From IXP Manager v4.8.0 onwards, each of these pages has a notes field which supports markdown to allow you to include sample connection sessions to devices. This is especially useful for rarely used console connections to awkward devices.
"},{"location":"features/console-servers/#improvements-from-v480","title":"Improvements from v4.8.0","text":"One of the new features of v4.8.0 is fixing the switch database table which until now could hold switches and console servers. This was awkward in practice and we have split these into distinct database tables and menu options.
"},{"location":"features/core-bundles/","title":"Core Bundles","text":"A core bundle is a link between the IXP's own switches. These are often referred to as trunks, interswitch links (ISLs), core links, etc. IXP Manager has a number of features to support these since v6 was released.
Before continuing with this document, it is critical you have read and understand how IXP Manager represents normal member connections - please read the Customer Connections page before proceeding as the rest of this document assumes that foundational knowledge.
Within IXP Manager, a core bundle represents a link(s) between two switches. This bundle may have one or more links and it may be one of three types:
A layer 2 LACP link (L2-LAG). Where your exchange has more than two switches, a protocol such as spanning tree would operate across these links to prevent loops.
If you are running just two switches with a single link between them, this is also the option you would choose. We'd typically recommend a protocol such as LACP or UDLD runs across even single links to detect unidirectional link errors.
A layer 3 LAG (L3-LAG) is for one or more aggregated links between a switch when using a routed underlay such as MPLS / VPLS / VXLAN. Each end of the link would have an IP address and participate in a routed core network.
ECMP is similar to L3-LAG above, each individual link in the core bundle has its own IP addressing and traffic distribution across the links is handled via equal-cost multi-path (ECMP) routing.
Some of the features that core bundles provide and enable include:
To fully understand IXP Manager's implementation of core bundles, it is important to have an awareness of the database representation of them. This is why reading the customer connections page is important - core bundles have been designed to fit into the existing database representation:
As you'll note, we still have a virtual interface (VI) as the syntactic sugar to represent a link where:
What's new is we've added a new element of syntactic sugar - the core bundle (CB) - and this is used to group the two ends of the link(s) between switches together.
The above may seem quite complex but it works well in practice. Most importantly, IXP Manager guides you through most of the complexity when setting up and managing core bundles. However, it's still important to have a grasp of the above as the user interface does reflect the underlying database schema.
"},{"location":"features/core-bundles/#creating-a-core-bundle","title":"Creating a Core Bundle","text":"Core bundles can be added like any another object in IXP Manager: find Core Bundles under IXP Admin Actions on the left hand side menu and then, when you are on the core bundles page, select the [+] add button on the top right of the page.
Adding a core bundle is presented with wizard-type functionality. As with most IXP Manager pages, there is extensive context-based help available by clicking the help button at the end of the form.
There's a number of elements to adding a core bundle and we'll take them individually here using an ECMP bundle as an example.
"},{"location":"features/core-bundles/#general-settings","title":"General Settings","text":"The context help shown in the image explains each element's requirements quite well.
You will notice that we often say informational unless you are provisioning your switches from IXP Manager. This is because many of these settings have no impact with IXP Manager or associated functions such as graphing. The value of entering this information won't be appreciated unless you are provisioning switches via IXP Manager using something such as Napalm.
Manually provisioning a core bundle with 8 x 10Gb ECMP links for a VXLAN underlay requires 16 interface configurations with consistent and correct IP addressing, MTU, BFD, etc. Add to that the 16 BGP neighbor configurations required. This does not scale beyond a handful of switches. We'd argue it barely scales to two switches. Especially when you then need to change the cost / preference settings.
Using IXP Manager, INEX can edit the cost of a core bundle and push it out through our SaltStack + Napalm configuration in a quick and error free manner.
It should also be recognised that the specific meaning of cost, preference, STP, etc. do not need to be taken literally - use them as appropriate for your network design and technology. For example, INEX uses cost for BGP metrics.
Lastly, some elements appear in general settings as they need to be consistent across all links in a core bundle - for example the MTU.
"},{"location":"features/core-bundles/#common-link-settings","title":"Common Link Settings","text":"Again, the context help shown in the image explains each element's requirements quite well. In addition to those, please note:
The final section requires you add one or more core links and select the 'a side' and 'b side' ports for each link added.
Note that some elements are core bundle type specific - e.g. as this is an ECMP core bundle, the subnet and BFD can be configured on a per link basis. For a L3-LAG, these are configured as part of the general settings.
There are a number of features to assist with adding large bundles (e.g. when we developed this using INEX as a test case, and before the widespread deployment of 100Gb WDM kit, 8 x 10Gb bundles were not uncommon). When you click Add another core link to the bundle...:
The next subnet will be calculated and populated. E.g. if you chose 10.10.20.0/30 for link 1, then 10.10.20.4/30 will be populated for link 2, and so on.
We have discussed this with some IXPs who use an addressing scheme where they try and embed information in the IP address such as facility or switch. We always advise that you treat an IP address as a 32-bit unique identifier and nothing else. If you choose a more complex addressing scheme, you can of course override IXP Manager's assistance here.
Your provisioning system will be responsible for picking the IP address for each side from 10.10.20.4/30. We recommend (and implement) a system such that the lowest usable address is assigned to the 'a side' and the next usable address is assigned to the 'b side'. For illustration:
10.10.20.0/31 10.10.20.0 10.10.20.1 10.10.20.0/30 10.10.20.1 10.10.20.2 10.10.20.0/24 10.10.20.1 10.10.20.2 Core bundles make graphing inter-switch links really easy - in fact, so long as you already have MRTG graphing configured, you just need to add the bundle, allow MRTG configuration to update and the graphs will appear in the statistics menu.
In fact, you can see a live example from INEX here. If this link yields a 404, it will mean we've since mothballed that specific link. Just browse to the Statistics menu and select Inter-Switch / PoP Graphs for another.
You'll note:
There is an API endpoint for superadmins to get the status of core bundles:
/api/v4/switch/{switchid}/core-bundles-status\nwhere {switchid} is the database ID of the switch.
A sample of the JSON output is:
{\n \"status\": true,\n \"switchname\": \"swi1-cwt1-4\",\n \"msgs\": [\n \"swi1-cwt1-4 - swi1-cwt1-1 OK - 1\\/1 links up\",\n \"swi1-cwt1-4 - swi1-cwt1-2 OK - 1\\/1 links up\",\n \"swi1-cwt1-4 - swi1-cwt2-1 OK - 1\\/1 links up\",\n \"swi1-cwt1-3 - swi1-cwt1-4 OK - 3\\/3 links up\",\n \"swi1-cwt1-4 - swi1-cwt2-3 OK - 4\\/4 links up\"\n ]\n}\nIf any individual link has failed, status will return false and an appropriate message will be provided for the relevant link(s):
\"ISSUE: swi1-cwt1-4 - swi1-cwt1-1 has 0\\/1 links up\"\nIndividually disabled core links (via the core bundle UI) will not trigger an alert. If an entire core bundle is disabled in the UI it will be listed as follows:
\"Ignoring swi1-cwt1-4 - swi1-cwt1-1 as core bundle disabled\"\nAs you can see, it returns a msgs[] element for each core bundle indicating the number of core links up.
The Nagios script we use at INEX to check the core bundles on a switch can be found here on the GitHub repository here: tools/runtime/nagios/ixp-manager-check-core-bundles.sh.
The Nagios command and service definition is as follows (this is an example - please alter to suit your own environment):
define command {\n command_name check_ixpmanager_core_bundles\n command_line /path/to/ixp-manager-check-core-bundles.sh -k <API Key> -i $_HOSTDBID$ -u 'https://ixpmanager.example.com'\n}\n\ndefine service {\n use ixp-production-switch-service\n hostgroup_name ixp-production-switches\n service_description Core Bundles\n check_command check_ixpmanager_core_bundles\n}\nThe hostgroup_name and _HOSTDBID come from the Switch Monitoring section in Nagios Monitoring.
NB: Nagios monitoring requires that the Automated Polling / SNMP Updates for switches is working and is working for any switch you want monitored. The Nagios script / API check is a database check. This means if you poll switches every $x minutes (5 by default) and your Nagios script runs the service check every $y minutes (also 5 by default), the maximum delay in notification of a core bundle with issues should be approx. $x + $y minutes.
At INEX, we use Network Weathermap to create the weathermaps on our website.
This isn't something we can document exhaustively as it varys from IXP to IXP. The general approach to take is:
As an outline of this process, here's the script Nick created for INEX:
#!/bin/sh\n\nPATH=/opt/local/bin:${PATH}\netcdir=/opt/local/etc\n\nAPIKEY=xxxx\nAPIURL=https://ixpmanager.example.com/api/v4\n\ncurl -s -X GET -H \"X-IXP-Manager-API-Key: ${APIKEY}\" \\\n ${APIURL}/provisioner/corebundle/list.yaml > ${etcdir}/ixp-corebundles.yaml\ncurl -s -X GET -H \"X-IXP-Manager-API-Key: ${APIKEY}\" \\\n ${APIURL}/provisioner/switch/list.yaml > ${etcdir}/ixp-switches.yaml\n\nrender-jinja-template.py \\\n --yaml ${etcdir}/ixp-corebundles.yaml \\\n --yaml ${etcdir}/ixp-switches.yaml \\\n --yaml ${etcdir}/switchpos.yaml \\\n --jinja ${etcdir}/ixp-weathermap.conf\nThe switchpos.yaml file is a manual file that contains the x/y coordinates for each switch in the following format:
---\nswitchpos:\n\n swi1-cls1-1:\n x: 130\n y: 40\n\n swi1-cwt1-1:\n x: 50\n y: 100\nHopefully this helps - improving this is something that is on our TODO list.
"},{"location":"features/cronjobs/","title":"Cron Jobs - Task Scheduling","text":"Prior to IXP Manager v5, a number of cron jobs had to be configured manually. From v5.0 onwards, cron jobs are handled by Laravel's task scheduler. As such, you just need a single cron job entry such as:
* * * * * www-data cd /path-to-your-ixp-manager && php artisan schedule:run >> /dev/null 2>&1\nYou can see the full schedule in code here (look for the function protected function schedule(Schedule $schedule)).
The following tasks are run via this mechanism and are referenced elsewhere in the documentation:
telescope:prune daily.Some data should not be retained indefinitely for user privacy / GDPR / housekeeping reasons. The utils:expunge-logs command runs daily at 03:04 and currently:
An IXP assigns each customer (an) IP address(es) from the range used on the peering LAN(s). These IP addresses can show up in traceroutes (for example) and both IXPs and customers like to have these resolve to a hostname.
When creating VLAN Interfaces in IXP Manager there is a field called IPv[4/6] Hostname. This is intended for this DNS ARPA purpose. Some customers have specific requirements for these while other smaller customers may not fully understand the use cases. At INEX, we typically default to entries such as:
customer-name.v4.example.com (where example.com would be inex.ie in our case)customer-name.v6.example.comIXP Manager can generate your ARPA DNS entries for your peering IP space as per the hostnames configured on each VLAN interface and provide them in two ways:
Both of these are explained below.
Note that the API endpoints below can be tested in your browser by directly accessing the URLs when logged in. Otherwise, you need an API key when using them in scripts.
"},{"location":"features/dns-arpa/#as-json","title":"As JSON","text":"You can use the IXP Manager API to get all ARPA entries for a given VLAN and protocol as a JSON object using the following endpoint format:
https://ixp.example.com/api/v4/dns/arpa/{vlanid}/{protocol}\nwhere:
vlanid is the database ID (DB ID) of the VLAN. You can find the DB ID in IXP Manager in the VLAN table (select VLANs from the left hand side menu).protocol is either 4 for IPv4 or 6 for IPv6.If either of these are invalid, the API will return with a HTTP 404 response.
And example of the JSON response returned is:
[\n {\n \"enabled\": true,\n \"address\": \"192.0.2.67\",\n \"hostname\": \"cherrie.example.com\",\n \"arpa\": \"67.2.0.192.in-addr.arpa.\"\n },\n ...\n]\nwhere:
enabled indicates if the protocol has been enabled for this user. This is nearly always true. A situation where it may be false is if you enabled IPv6 for a user; then that user subsequently decided to not use IPv6; then you unchecked the IPv6 Enabled box in the VLAN Interface form without removing address / hostname entries.address - this IPv4/6 address of the VLAN interface as assigned by the IXP.hostname - the configured hostname for this address as entered into IXP Manager.arpa: the generated ARPA record name for the IP address assigned by the IXP.You can now feed the JSON object into a script to create your own DNS zones appropriate to your DNS infrastructure.
When scripting, we would normally pull the JSON object using something like:
#! /usr/bin/env bash\n\nKEY=\"your-ixp-manager-api-key\"\nURL=\"https://ixp.example.com/api/v4/dns/arpa\"\nVLANIDS=\"1 2\"\nPROTOCOLS=\"4 6\"\n\nfor v in $VLANIDS; do\n for p in $PROTOCOLS; do\n\n cmd=\"/usr/local/bin/curl --fail -s \\\n -H \\\"X-IXP-Manager-API-Key: ${KEY}\\\" \\\n ${URL}/${v}/${p} \\\n >/tmp/dns-arpa-vlanid$v-ipv$p.json.$$\"\n eval $cmd\n\n if [[ $? -ne 0 ]]; then\n echo \"ERROR: non-zero return from DNS ARPA API call for vlan ID $v with protocol $p\"\n continue\n fi\n\n // do something\n\n rm /tmp/dns-arpa-vlanid$v-ipv$p.json.$$\n done\ndone\nRather than writing your own scripts to consume the JSON object as above, it may be easier to use the bundled ISC Bind templates or to write your own template for IXP Manager.
You can use the IXP Manager API to get all ARPA entries for a given VLAN and protocol as plain text based on a template by using the following API endpoint:
https://ixp.example.com/api/v4/dns/arpa/{vlanid}/{protocol}/{template}\nwhere:
vlanid and protocol is as above in As JSON.template is the name of a template file residing in the view path api/v4/dns/.Remember that the included ISC Bind templates can be skinned or you can add custom templates to your skin directory. More detail on this can be found in the dedicated section below.
The bundled ISC Bind templates can be used by setting {template} to bind or bind-full in the above URL. For the example interface in the JSON above, the ISC Bind bind template would yield:
67.2.0.192.in-addr.arpa. IN PTR cherrie.example.com.\n(note that the terminated period on the hostname is added by the template)
The two bundled templates are:
bind: outputs resource records only as per the above example.bind-full: outputs a complete Bind zone file including head and serialized serial number (UNIX timestamp). This must be templated as it uses example.com for email and name server domains.You can use skinning to make changes to the bundled ISC Bind template or add your own.
Let's say you wanted to add your own template called mytemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/dns\ncp resources/views/api/v4/dns/bind.foil.php resources/skins/myskin/api/v4/dns/mytemplate1.foil.php\nYou can now edit this template as required. The only constraint on the template name is it can only contain characters from the classes a-z, 0-9, -. NB: do not use uppercase characters.
Contribute back - if you write a useful generator, please open a pull request and contribute it back to the project.
The following variables are available in the template:
$t->arpa: array of the ARPA entries - see below.$t->vlan: instance of the Vlan entity object.$t->protocol: either 4 or 6.The following variables are available for each element of the $t->arpa array (essentially the same as the JSON object above): enabled, hostname, address, arpa. See above for a description.
The actual code in the bundled ISC Bind sample is as simple as:
<?php foreach( $t->arpa as $a ): ?>\n<?= trim($a['arpa']) ?> IN PTR <?= trim($a['hostname']) ?>.\n<?php endforeach; ?>\nAt INEX, we have (for example) one peering LAN that is a /25 IPv4 network and so is not a zone file in its own right. As such, we make up the zone file using includes. The main zone file looks like:
$TTL 86400\n\n$INCLUDE /usr/local/etc/namedb/zones/soa-0.2.192.in-addr.arpa.inc\n\n$INCLUDE zones/inex-dns-slave-nslist.inc\n\n$INCLUDE zones/reverse-mgmt-hosts-ipv4.include\n$INCLUDE zones/reverse-vlan-12-ipv4.include\nThe SOA file looks like (as you might expect):
@ IN SOA ns.example.come. hostmaster.example.com. (\n 2017051701 ; Serial\n 43200 ; Refresh\n 7200 ; Retry\n 1209600 ; Expire\n 7200 ) ; Minimum\nThe reverse-vlan-12-ipv4.include is the output of the ISC Bind bind template above for a given VLAN ID.
We use the sample script update-dns-from-ixp-manager.sh which can be found in this directory to keep this updated ourselves.
IXP Manager has two document stores which allow administrators to upload and manage document. The two types are:
Both document stores support:
.txt) and display and parsing of Markdown (.md) files within IXP Manager.Also for the general document store, and non-public documents within it, logging and reporting of downloads (total downloads and unique user downloads).
Please note that all actions except for viewing and downloading files are restricted to super users.
The general document store is accessible:
The per-member document store is accessible:
In the following sections, we use screenshots from the general document store but will highlight and specific differences for the per-member document store.
"},{"location":"features/docstore/#directories","title":"Directories","text":"Directories are database entries to which uploaded files are attached (rather than actual directories on the storage media).
Directories can be created via the Create Directory button on the top right of the document store. See the following image showing the Create Directory form. As usual, contextual help is available via the green Help button.
To create per-member directories: First select the appropriate member from the Members/Customers list on the left-hand menu, then select the Documents tab, then select the Create Directory button on the top right.
Note that you do not need to set any permissions on directories - directories (and directory hierarchy) will only be visible to each user class if they contain files that the specific user class should be able to see.
If you enter a description, you will see a gray section at the top of the directory listing as shown in the following image. The text you enter will be parsed as Markdown and displayed as HTML. If you leave the description blank, no such section will be shown. This is a useful feature to provide context to your users about the documents in a given directory.
When viewing directories in a directory listing, a per-directory context menu is available per the following image and with the following two options:
Files can be uploaded via the Upload File button on the top right of the document store. See the following image showing the Upload File form with the contextual help shown (via the green Help button).
To upload per-member files: First select the appropriate member from the Members/Customers list on the left-hand menu, then select the Documents tab, then select the Upload File button on the top right.
The various fields are well explained by the contextual help above and we will add some additional emphasis here:
NB: for the per-member document store, there is no option to make a file Publicly available.
The following is how a file appears in a directory listing:
CUSTUSER indicates the minimum access permissions for the file. The numbers 19 (10) tell super admins that there have been a total of 19 downloads and 10 of those were unique to individual users in IXP Manager (i.e. some users would have downloaded this file two or more times). Note that only downloads by logged in users are counted. Publicly accessible files downloaded by non-logged in users are not recorded (if you must know this then that information is available from your web server log files). The date, Feb 29, 2020 is the date the file itself (not metadata) was last changed via the Edit option.
NB: there is no logging of files downloaded in the per-member document store. Please see below for more information.
The options in the per-file context menu are:
If you wish to purge the download logs for a file, you will find a Purge all download logs and reset download statistics checkbox on the file edit form. You can check this without making any other changes except to purge the logs.
"},{"location":"features/docstore/#sha256-functionality","title":"SHA256 Functionality","text":"Checksums can be used to verify the authenticity / integrity of downloaded files. The primary use-case when developing the Document Store at INEX was for official documents from the INEX Board of Directors which they wished to share with the membership - for example minutes of board meetings.
The INEX Board Secretary would provide the PDF documents to the operations team for upload. In parallel the Secretary would also email the members' mailing list to inform them that a new set of minutes are being uploaded and the secretary would include the sha256 checksum in that email. This is a useful way to independently verify the authenticity of official documents and the reason this feature exists.
When uploading (or changing an uploaded file), if you enter a sha256 checksum, it will be verified on upload (and rejected if it does not match). If you leave it blank, the sha256 checksum will be calculated by IXP Manager.
"},{"location":"features/docstore/#download-logs","title":"Download Logs","text":"The general Document Store logs file downloads / views by user. The total number of downloads and the unique users download count is shown on the directory listing. You can also get access to the individual download logs for each file via its context menu.
Non-unique individual download logs are expunged once they are more than six months old - except for the first download by each user. The user interface presents this information differently so that it is clear when you are looking at a file that is more than six months old.
There are a number of reasons to log file downloads:
However, there is no reasonable need that we can see to retain individual downloads for more than 6 months. As such, these are automatically expunged by the scheduler.
Note also that all we record is user ID, file ID and time. No IP address or other information is recorded.
"},{"location":"features/docstore/#patch-panel-files","title":"Patch Panel Files","text":"As a useful convenience, the per-member document store presents a virtual directory which collates any patch panel files that have been uploaded to a member's current or past cross connect record.
"},{"location":"features/docstore/#access-considerations","title":"Access Considerations","text":"IXP Manager generates a complete directory hierarchy for each of the four user classes. As such, users will only see the directory hierarchies that lead to files that are accessible to them. If a leaf directory does not contain a file that a user class cannot access then they will not see the directory in the listings.
Similarly, users will only see files listed that they can access.
If there are no documents in the Document Store for a specific user class (or public user), the the Document Store menu item will not appear under Customer / Member Information at the top of the page.
If you wish to complete disable the general document store, set the following option in .env:
IXP_FE_FRONTEND_DISABLED_DOCSTORE=true\nIf you wish to complete disable the per-member document store, set the following option in .env:
IXP_FE_FRONTEND_DISABLED_DOCSTORE_CUSTOMER=true\nThe best way to view the limitations described herein is to understand that the development goals of the document stores were to create something which is simple and secure while consciously avoiding a recreation of Dropbox or a CRM system. We discussed tens of features, dials and knobs for the document stores but chose to not implement them.
No backup / restore / undelete: if you delete a file (or directory) in the web user interface then you will also delete the file as it is stored on disk. This is not a soft-delete option and it does not include a Dropbox-esque undelete for 90 days. If you select and then confirm the deletion of a file or directory, then we assume you have made a deliberate and conscious decision to do just that.
It should be noted that while IXP Manager does not provide this kind of functionality - it also cannot reliably provide it. As a self-hosted application, it is up to the local system administrators to ensure adequate file system and database backups are in place. Then, with adequate local backup procedures (or the developers expectations that a copy of important documents would also be kept off IXP Manager's document store), restoration of deleted documents is possible.
No editing of files - particularly text and Markdown which are viewable within IXP Manager. We actually tried this but the code and user experience changes required pushed the complexity needle beyond where we wanted this feature to go.
Only superusers can upload / edit / delete files. This won't change for the general document store. We can review it for the per-member document store if the feature is requested.
Because only superusers can upload / edit files, there is no restriction on file types - we expect you to use your own good judgement here. There is also no restriction on file sizes - as a self-hosted application, storage space is your own consideration.
File upload size may be limited by your web server or PHP configuration. For PHP, find which .ini file is in use by running php --ini and then set the following as you wish (example values given):
upload_max_filesize = 100M\npost_max_size = 100M\nApache has no limit by default so if running Apache with PHP, just restart Apache (and / or PHP FPM) to apply the above. For Nginx, you need to set this as it has a default upload size of 1MB:
server {\n ...\n client_max_body_size 100M;\n}\nFor more information or other web server / PHP combinations, look at the specific documentation for those tools or Google it as this is a common question with many answers.
"},{"location":"features/helpdesk/","title":"Helpdesk Integration","text":"** WORK IN PROGRESS - DEVELOPMENT NOTES **
As an IXP scales, it will eventually have to replace email support via a simple alias / shared IMAP mailbox with a proper ticketing system. After extensive (and painful!) research, we at INEX chose Zendesk as the system that most matched our budget and required features (1).
While your mileage may vary on this - or you may already have something else - please note that the reference implementation for helpdesk integration on IXP Manager is Zendesk. So, if you haven't already chosen one, Zendesk will provide maximum integration with minimal pain.
Please do not open a feature request for other helpdesk implementations as the authors cannot undertake such additional work. If you wish to have integration with another helpdesk implemented, please consider commercial support
"},{"location":"features/helpdesk/#features-supported","title":"Features Supported","text":"IXP Manager currently supports:
Work that is in progress includes:
As Zendesk is the only implementation currently, this refers only to Zendesk.
"},{"location":"features/helpdesk/#zendesk","title":"Zendesk","text":"You need to enable API access to Zendesk as follows:
With your Zendesk login and the token from above, edit the .env file in the base directory of IXP Manager and set:
HELPDESK_BACKEND=zendesk\nHELPDESK_ZENDESK_SUBDOMAIN=ixp\nHELPDESK_ZENDESK_TOKEN=yyy\nHELPDESK_ZENDESK_EMAIL=john.doe@example.com\nYou can now test that your settings are correct with: FIXME
"},{"location":"features/helpdesk/#implementation-development","title":"Implementation Development","text":"The helpdesk implementation in IXP Manager is designed using contracts and service providers. I.e. it is done The Right Way (tm).
The reference implementation is for Zendesk but it's coded to a contract (interface) at app/Contracts/Helpdesk.php.
The actual Zendesk implementation can be found at: app/Services/Helpdesk/Zendesk.php.
The good news here is if you want another helpdesk supported, you just need to:
switch() statement in app/Providers/HelpdeskServiceProvider.php(1) Actually, Zendesk wasn't our first ticketing system. For a number of years we used Cerb but it didn't stay current in terms of modern HTML UI/UX and it suffered from feature bloat. One requirement for our replacement was a decent API and with Zendesk's API we were able to migrate all our old tickets using this script.
"},{"location":"features/irrdb/","title":"IRRDB Prefixes and ASN Filtering","text":"Prerequisite Reading: Ensure you first familiarize yourself with the generic documentation on managing and generating router configurations here.
IXP Manager can maintain a list of member route:/route6: prefixes and origin ASNs as registered in IRRDBs in its database and then use these to, for example, generate strict inbound filters on route servers.
"},{"location":"features/irrdb/#setup","title":"Setup","text":"You need to have set up some IRRDB sources (e.g. RIPE's whois service) under the IXP Admin Actions / IRRDB Configuration on the left hand side menu. If you do not have any entries here, there is a database seeder you can use to install some to start you off:
cd $IXPROOT\n./artisan db:seed --class=IRRDBs\nBGPQ3 is a very easy and fast way of querying IRRDBs. You first need to install this on your system. On a modern Ubuntu system this is as easy as:
apt install bgpq3\nThen configure the path to it in your .env file.
# Absolute path to run the bgpq3 utility\n# e.g. IXP_IRRDB_BGPQ3_PATH=/usr/local/bin/bgpq3\nIXP_IRRDB_BGPQ3_PATH=/usr/bin/bgpq3\nTo populate (and update) your local IRRDB, run the following commands:
cd $IXPROOT\nphp artisan irrdb:update-prefix-db\nphp artisan irrdb:update-asn-db\nFrom IXP Manager v5 onwards, and so long as your bgpq3 path is set as above and is executable, the task scheduler will take care of updating your local IRRDB a number of times a day. If you are using a version of IXP Manager before v5, then the above commands should be added to cron to run ~once per day (using the --quiet flag).
There are four levels of verbosity:
--quiet: no output unless there's an error / issue.-vv: include per customer and overall timings (database, processing and network).-vvv (debug): show prefixes/ASNs added remove also.You can also specify a specific customer to update (rather than all) with an additional free form parameter. The database is searched for a matching customer in the order: customer ASN; customer ID (database primary key); and customer shortname. E.g.:
php artisan irrdb:update-prefix-db 64511\nEssentially, based on a customers AS number / IPv4/6 Peering Macro, IXP Manager uses bgpq3 to query IRRDBs as follows:
bgpq3 -S $sources -l pl -j [-6] $asn/macro\nwhere $sources come from the IRRDB sources entries.
Or, a real example:
bgpq3 -S RIPE -l pl -j AS-BTIRE\nbgpq3 -S RIPE -l pl -j -6 AS-BTIRE\nThe IRRDB update commands will:
We use transactions to update the database so, even in the middle of a refresh, a full set of prefixes for all customers will still be available. It also means the update process can be safely interrupted.
Note that our current implementation only queries RADB as BGPQ3 does not support the RIPE whois protocol. Our version will however set the RADB source database according to the member's stated IRRDB database as set on the customer add / edit page - so, for customer's registered with the RIPE IRRDB, the RIPE database of RADB is queried.
"},{"location":"features/ixf-export/","title":"IX-F Member List Export","text":"The IX-F Member Export is an agreed and standardized JSON schema which allows IXPs to make their member lists available for consumption by tools such as PeeringDB, networks with automated peering managers, prospective members and the many other tools appearing in the peering eco-system.
Historical reference: INEX created and hosted a proof of concept directory for the IX-F Export Schema until Euro-IX/IX-F took it in house in 2018.
The key element of the IX-F Member Export is it makes you, the individual IXP, the canonical trusted source for data about your own IXP. Data that has the best chance of being correct and up to date. Particularly, PeeringDB has the option of allowing network data to be updated from IX records - see our documentation on this here.
To find out more about the JSON schema and see examples, you can read more here, explore many of the public IXP end points available here or see the GitHub euro-ix/json-schemas repository.
IXP Manager supports the IX-F Member List Export out of the box. It previously supported all versions from 0.3 to 0.5 but we now only support 0.6, 0.7 and 1.0 (for >=v5.1). We plan to deprecate support for 0.6 during 2019.
Sometimes you may need something more customized than the the IX-F Member Export. For that, see the other member export feature if IXP Manager.
"},{"location":"features/ixf-export/#preparing-the-ix-f-member-export","title":"Preparing the IX-F Member Export","text":"There are a small number of things you should do to ensure your IX-F export is correct.
Correctly set the PeeringDB ID and IX-F ID
The first is to ensure you have correctly set the PeeringDB ID and IX-F ID in your infrastructure (see Infrastructures under the left hand side IXP ADMIN ACTIONS menu).
The IX-F ID is mandatory. You will find yours by searching the IX-F providers database here. If you are a new IXP that is not registered here, please email your IXP's: full name, short name, city / region / country, GPS coordinates and website URL to ixpdb-admin (at) euro-ix (dot) net so they can register it in the IXPDB.
Create Network Info
From IXP Manager v4.9 and above, click VLANs on the left-hand-side menu and then chose Network Information. Once there, add the network address and network mask length for IPv4 and IPv6 for your peering LAN(s).
Prior to v4.9, this was a little hacky: there is a database table called networkinfo that requires you to manually insert some detail on your peering LAN.
The first thing you need is the peering VLAN DB ID. [clarification note: this is nothing to do with PeeringDB but the VLAN created within IXP Manager]. For this, select VLANs under the left hand side IXP ADMIN ACTIONS menu in IXP Manager. Locate your peering VLAN DB ID and note it.
For our example, we will use the following sample data:
192.0.2.0/25 with route servers on .8 and .92001:db8:1000::/64 with route servers on .8 and .9You need need to add this data to networkinfo with the following sample SQL commands:
INSERT INTO `networkinfo`\n ( `vlanid`, `protocol`, `network`, `masklen`, `rs1address`, `rs2address`),\nVALUES\n ( 66, 4, '192.0.2.0', '25', '192.0.2.8', '192.0.2.9' );\n\nINSERT INTO `networkinfo`\n ( `vlanid`, `protocol`, `network`, `masklen`, `rs1address`, `rs2address`),\nVALUES\n ( 66, 6, '2001:db8:1000::', '64', '2001:db8:1000::8', '2001:db8:1000::9' );\nSet Your IXP's Name / Country / etc
The third task is to ensure your IXP's details are correct in the IX-F export.
You will most likely have nothing to do here as it would have been done on installation but this reference may prove useful if there are any issues.
These are mostly set in the .env file (as well as some other places) and the following table shows how they get mapped to the IX-F Export:
shortname In IXP Manager, from the Infrastructure object name field name IDENTITY_LEGALNAME from .env country IDENTITY_COUNTRY from .env in 2-letter ISO2 format url IDENTITY_CORPORATE_URL from .env peeringdb_id In IXP Manager, from the Infrastructure object ixf_id In IXP Manager, from the Infrastructure object support_email IDENTITY_SUPPORT_EMAIL from .env support_phone IDENTITY_SUPPORT_PHONE from .env support_contact_hours IDENTITY_SUPPORT_HOURS from .env emergency_email IDENTITY_SUPPORT_EMAIL from .env emergency_phone IDENTITY_SUPPORT_PHONE from .env emergency_contact_hours IDENTITY_SUPPORT_HOURS from .env billing_email IDENTITY_BILLING_EMAIL billing_phone IDENTITY_BILLING_PHONE billing_contact_hours IDENTITY_BILLING_HOURS We we say from the Infrastructure object above, we mean that when you are logged into IXP Manager as an admin, it's the Infrastructures menu option under IXP Admin Actions on the left hand side.
"},{"location":"features/ixf-export/#accessing-the-ix-f-member-list","title":"Accessing the IX-F Member List","text":"If your version of IXP Manager is installed at, say, https://ixp.example.com/, then the IX-F Member List export can be accessed at:
https://ixp.example.com/api/v4/member-export/ixf/1.0\nwhere 1.0 is a version parameter which allows for support of potential future versions.
Note that the publicly accessible version does not include individual member details such as name, max prefixes, contact email and phone, when the member joined, member's web address, peering policy, NOC website, NOC hours or member type. This information is available to any logged in users or users querying the API with an API key.
"},{"location":"features/ixf-export/#access-without-ix-f-id-being-set","title":"Access Without IX-F ID Being Set","text":"While the IX-F ID is officially required for >= v0.7 of the schema, it may be overlooked on new installations or some IXPs may be uninterested in working with the IX-F IXP database.
The schema requirement for a valid IX-F ID should not prevent the IX-F exporter from working if someone wishes to pull the information regardless of that being set. There are two ways to override this and query the API available from IXP Manager v5.7.0:
The first is to pass an ixfid_y parameter (where y is the database ID of the infrastructure) every infrastructure that does not have one. Using this method will have IXP Manager set the IX-F ID in the generated JSON output suitable for processing by automated scripts. A sample URL for an IXP with two infrastructures might look like this:
https://ixpmanager.example.com/api/v4/member-export/ixf/1.0?ixfid_1=30&ixfid_2=31\nIf you wish to just ignore the IX-F ID and have it set to zero in the JSON output, you can use the following flag:
https://ixpmanager.example.com/api/v4/member-export/ixf/1.0?ignore_missing_ixfid=1\nIXPDB requires two pieces of information to fully integrate with the IXPDB. You can provide this information to ixpdb-admin (at) euro-ix (dot) net or - if you have a login to the Euro-IX website, you should be able to login and edit your own IXP directly on IXPDB.
The first element needed is the API endpoint as described above in Accessing the IX-F Member List.
The second is the API endpoint to export your statistics. This is:
https://ixp.example.com/grapher/infrastructure?id=1&type=log&period=day\nwhere id=1 is the infrastructure DB ID (see Infrastructures under the left hand side IXP ADMIN ACTIONS menu).
To disable public access to the restricted member export, set the following in your .env file:
IXP_API_JSONEXPORTSCHEMA_PUBLIC=false\nWe strongly advise you not to disable public access if you are a standard IXP. Remember, the public version is essentially the same list as you would provide on your standard website's list of members.
In addition, membership of an IXP is easily discernible from a number of other sources including:
Leave public access available, own your own data, ensure it's validity and advertise it!
If you must disable public access but would still like to provide IX-F (or others) with access, you can set a static access key in your .env file such as:
IXP_API_JSONEXPORTSCHEMA_ACCESS_KEY=\"super-secret-access-key\"\nand then provide the URL in the format:
https://ixp.example.com/api/v4/member-export/ixf/1.0?access_key=super-secret-access-key\nIf you wish to control access to the infrastructure statistics, see the Grapher API documentation. The statistics data is a JSON object representing each line of a the rest of the file from a standard MRTG log file. This means the per-line array elements are:
It is possible to exclude some data from v6.0.1 per GitHub issue #722:
While some exchanges are willing to share detailed information about their infrastructure via the IX-F Member Export Schema, others either do not want to or cannot due to regulation. Enabling exchanges to share a limited set of data about their infrastructure would help exchanges find others using the same platforms to learn from each other and shows the diversity of platforms in use across the market.
Please bear in mind that the more data you remove, the less useful the IX-F member export becomes. Most IXPs do not use this exclusion function and, ideally, you will only use it if there is no other choice.For example, a switch object typically looks like:
{\n \"id\": 50,\n \"name\": \"swi1-kcp1-2\",\n \"colo\": \"Equinix DB2 (Kilcarbery)\",\n \"city\": \"Dublin\",\n \"country\": \"IE\",\n \"pdb_facility_id\": 178,\n \"manufacturer\": \"Arista\",\n \"model\": \"DCS-7280SR-48C6\",\n \"software\": \"EOS 4.24.3M\"\n}\nIf, for example, you need to exclude the model and software version, you can add the following to your .env file:
IXP_API_JSONEXPORTSCHEMA_EXCLUDE_SWITCH=\"model|software\"\nwhich will yield:
{\n \"id\": 50,\n \"name\": \"swi1-kcp1-2\",\n \"colo\": \"Equinix DB2 (Kilcarbery)\",\n \"city\": \"Dublin\",\n \"country\": \"IE\",\n \"pdb_facility_id\": 178,\n \"manufacturer\": \"Arista\"\n}\nAs you can see, the configuration option is the set of identifiers you want to exclude (model and software) separated with the pipe symbol. Different combinations are possible - here are some examples:
IXP_API_JSONEXPORTSCHEMA_EXCLUDE_SWITCH=\"software\"\nIXP_API_JSONEXPORTSCHEMA_EXCLUDE_SWITCH=\"model|software\"\nIXP_API_JSONEXPORTSCHEMA_EXCLUDE_SWITCH=\"city|model|software\"\nYou should not exclude the id as these is referred to in the member interface list.
You can exclude detail for the IXP object:
{\n \"shortname\": \"INEX LAN1\",\n \"name\": \"Internet Neutral Exchange Association Limited by Guarantee\",\n \"country\": \"IE\",\n \"url\": \"https:\\/\\/www.inex.ie\\/\",\n \"peeringdb_id\": 48,\n \"ixf_id\": 20,\n \"ixp_id\": 1,\n \"support_email\": \"operations@example.com\",\n \"support_contact_hours\": \"24x7\",\n \"emergency_email\": \"operations@example.com\",\n \"emergency_contact_hours\": \"24x7\",\n \"billing_contact_hours\": \"8x5\",\n \"billing_email\": \"accounts@example.com\",\n ...\n}\nwith the option:
IXP_API_JSONEXPORTSCHEMA_EXCLUDE_IXP=\"name|url\"\nYou should not exclude any of the IDs (peeringdb_id, ixf_id and ixp_id) as these is referred to else where in the document and required externally when using the data.
You can exclude member detail:
{\n \"asnum\": 42,\n \"member_since\": \"2009-01-13T00:00:00Z\",\n \"url\": \"http:\\/\\/www.pch.net\\/\",\n \"name\": \"Packet Clearing House DNS\",\n \"peering_policy\": \"open\",\n \"member_type\": \"peering\",\n ...\n}\nwith the option:
IXP_API_JSONEXPORTSCHEMA_EXCLUDE_MEMBER=\"peering_policy|member_type\"\nAnd finally, you can include member VLAN/protocol detail:
\"ipv4\": {\n \"address\": \"185.6.36.60\",\n \"as_macro\": \"AS-PCH\",\n \"routeserver\": true,\n \"mac_addresses\": [\n \"00:xx:yy:11:22:33\"\n ],\n \"max_prefix\": 2000\n},\n\"ipv6\": {\n \"address\": \"2001:7f8:18::60\",\n \"as_macro\": \"AS-PCH\",\n \"routeserver\": true,\n \"mac_addresses\": [\n \"00:xx:yy:11:22:33\"\n ],\n \"max_prefix\": 2000\n}\nwith the option:
IXP_API_JSONEXPORTSCHEMA_EXCLUDE_INTINFO=\"mac_addresses|routeserver\"\nPlease note that the IXP_API_JSONEXPORTSCHEMA_EXCLUDE_INTINFO affects both the ipv4 and ipv6 clauses.
You can exclude members by ASN or by tag by setting the following .env option:
# Exclude members with certain AS numbers\n# IXP_API_JSONEXPORTSCHEMA_EXCLUDE_ASNUM=\"65001|65002|65003\"\n\n# Exclude members with certain tags\n# IXP_API_JSONEXPORTSCHEMA_EXCLUDE_TAGS=\"tag1|tag2\"\nThe following are enabled by default to prevent exporting test customers:
# Exclude documentation ASNs (64496 - 64511, 65536 - 65551)\n# IXP_API_JSONEXPORTSCHEMA_EXCLUDE_RFC5398=true\n\n# Exclude private ASNs (64512 - 65534, 4200000000 - 4294967294)\n# IXP_API_JSONEXPORTSCHEMA_EXCLUDE_RFC6996=true\nIf you pass withtags=1 as a parameter to the URL endpoint, then you will get an extra section in each member section:
\"ixp_manager\": {\n \"tags\": {\n \"exampletag1\": \"Example Tag #1\",\n \"exampletag2\": \"Example Tag #2\"\n },\n \"in_manrs\": false,\n \"is_reseller\": false,\n \"is_resold\": true,\n \"resold_via_asn\": 65501\n},\nAs you can see:
is_manrs indicates if the member is MANRS compliant.is_reseller indicates if this member is a reseller.is_resold indicates if the member has come via a reseller and, if so, resold_via_asn provides the AS number of the reseller.A common requirement of IXPs is to create a public member list on their official website. This can be done with the IX-F Member Export quite easily. The below HTML and JavaScript is a way to do it with INEX's endpoint. There's a live JSFiddle which demonstrates this also - https://jsfiddle.net/barryo/2tzuypf9/.
The HTML requires just a table with a placeholder and an id on the body:
<table class=\"table table-bordered\" style=\"margin: 10px\">\n <thead>\n <tr>\n <th>Company</th>\n <th>ASN</th>\n <th>Connections</th>\n </tr>\n </thead>\n <tbody id=\"list-members\">\n <tr>\n <td colspan=\"3\">Please wait, loading...</td>\n </tr>\n </tbody>\n</table>\nThe JavaScript loads the member list via the IX-F Export and processes it into the table above:
// Sample IX-F Member Export to Member List script\n//\n// License: MIT (https://en.wikipedia.org/wiki/MIT_License)\n// By @yannrobin and @barryo\n// 2018-03-06\n\nfunction prettySpeeds( s ) {\n switch( s ) {\n case 10: return \"10Mb\";\n case 100: return \"100Mb\";\n case 1000: return \"1Gb\";\n case 10000: return \"10Gb\";\n case 40000: return \"40Gb\";\n case 100000: return \"100Gb\";\n default: return s;\n }\n}\n\n$.getJSON( \"https://www.inex.ie/ixp/api/v4/member-export/ixf/0.7\", function( json ) {\n\n // sort by name\n json[ 'member_list' ].sort( function(a, b) {\n var nameA = a.name.toUpperCase(); // ignore upper and lowercase\n var nameB = b.name.toUpperCase(); // ignore upper and lowercase\n if (nameA < nameB) {\n return -1;\n }\n if (nameA > nameB) {\n return 1;\n }\n // names must be equal\n return 0;\n });\n\n let html = '';\n\n $.each( json[ 'member_list' ], function(i, member) {\n html += `<tr>\n <td>\n <a target=\"_blank\" href=\"${member.url}\">${member.name}</a>\n </td>\n <td>\n <a target=\"_blank\"\n href=\"http://www.ripe.net/perl/whois?searchtext=${member.asnum}&form_type=simple\">\n ${member.asnum}\n </a>\n </td>`;\n\n let connection = '';\n $.each( member[ 'connection_list' ], function(i, conn ) {\n if( conn[ 'if_list' ].length > 1 ){\n connection += conn[ 'if_list' ].length+ '*'\n }\n connection += prettySpeeds( conn[ 'if_list' ][0].if_speed );\n\n if(i < (member[ 'connection_list' ].length - 1 )){\n connection += \" + \";\n }\n });\n\n html += `<td>${connection}</td></tr>\\n`;\n });\n\n $( \"#list-members\" ).html(html);\n});\nThe end result is a table that looks like:
Company | ASN | Connections | --------------------|----------------------------------| 3 Ireland | 34218 | 2*10Gb + 2*10Gb | Afilias | 12041 | 1Gb | ... | ... | ... |
"},{"location":"features/layer2-addresses/","title":"MAC Addresses","text":"IXP Manager has support for layer2 / MAC addresses in two ways:
In early 2017, INEX migrated its primary peering LAN from a flat layer2 with spanning tree design to a VxLAN set-up with automation via Salt and Napalm (we will insert references to presentations here once we complete all required functionality).
Part of the requirements for this automation (and this was an existing feature request from other IXPs) was the management of MAC addresses within IXP Manager and, rather than assigning them to a virtual interface, assign them to specific VLAN interfaces.
Outside of our automation and VXLAN, other uses included:
The features of this system are listed below.
"},{"location":"features/layer2-addresses/#listing-and-searching-existing-configured-mac-addresses","title":"Listing and Searching Existing Configured MAC Addresses","text":"There is a new menu option (left hand side menu) under MAC Addresses called Configured Addresses. This lists all configured MAC addresses including the OUI manufacturer (see below), associated switch / switch port(s), customer name, IPv4 and v6 addresses. You can also:
When editing a customer's interface in the usual manner (customer overview -> Ports -> edit button), you will now see MAC address(es) under VLAN Interfaces:
In the event that there is zero or more than one MAC address, the MAC address demonstrated above will be replaced with an appropriate note to indicate this.
Clicking on the MAC address (or note when none / multiple) will bring you to the configured MAC address management page for this VLAN interface. Addresses can be added / removed on this page. MAC addresses can be entered in either upper or lower cases and can optionally include characters such as ., :, -. These are all stripped before validation and insertion.
As automation features are still a work in progress, not all methods are listed here. Please open an issue on GitHub or start a discussion on the mailing list for whatever methods you would like.
Currently implemented (see the API page for access details):
INEX's use case was to switch from the discovered MAC addresses table to the configured MAC addresses table without the need to data fill all preexisting ~200 MACs. As such we have created an Artisan migration script which can be run with:
php $IXPROOT/artisan l2addresses:populate\nYou will be prompted as follows:
Are you sure you wish to proceed? This command will CLEAR the layer2address table and then copy addresses from the read-only macaddress table. Generally, this command should only ever be run once when initially populating the new table.
One thing to note: as the discovered MAC Addresses table is per virtual interface and the new configured MAC address functionality is per VLAN interface, any MAC from discovered MAC Addresses that is populated into configured MAC Addresses will be populated for every VLAN interface associated with the virtual interface.
The script prints notices for these such as:
Created >1 layer2address for [member name]] with virtual interface: https://www.example.com/ixp/virtual-interface/edit/id/235
The inclusion of the URL makes it easy to double check the result.
For obvious reasons, we only allow a single / unique layer2 address per VLAN. In the event that the script tries to add the same MAC more than once, it will print:
Could not add additional instance of 001122334455 for [Customer]] with virtual interface: https://www.example.com/ixp/virtual-interface/edit/id/265 as it already exists in this Vlan [VLAN name]
These should all be checked manually.
A useful SQL command to double check the results for me was:
SELECT mac, COUNT(mac) AS c FROM l2address GROUP BY mac HAVING COUNT(mac) > 1;\nThis was the original functionality - a read-only table via an admin menu option called MAC Addresses -> Discovered Addresses which lists entries from a database of MAC addresses which are sourced via a script from the IXP's switches directly.
At an IXP, it can be extremely useful to have a quick look up table to see what member owns what MAC address - especially when they start injecting illegal packets into the exchange fabric.
We have a script, update-l2database.pl, for this. To set it up (using Ubuntu as an example), proceed as below. We are in the process of trying to reduce the reliance on the perl library and direct database access. But for now, this script still requires it.
# If you haven't already, install the Perl library for IXP Manager:\napt-get install libnet-snmp-perl libconfig-general-perl libnetaddr-ip-perl\ncd $IXPROOT/tools/perl-lib/IXPManager\nperl Makefile.PL\nmake install\n\n# Then copy and edit the configuration file to set the database connection settings:\ncp $IXPROOT/tools/perl-lib/IXPManager/ixpmanager.conf.dist /usr/local/etc/ixpmanager.conf\njoe /usr/local/etc/ixpmanager.conf #and set database settings\n\n# Now copy the script:\ncp $IXPROOT/tools/runtime/l2database/update-l2database.pl /usr/local/bin\n\n# and then add it to your periodic cron job with:\n/usr/local/bin/update-l2database.pl\nIXP Manager can store the IEEE OUI database and reference it to show the manufacturer behind a MAC address.
"},{"location":"features/layer2-addresses/#populating-and-updating-the-oui-database","title":"Populating and Updating the OUI Database","text":"The OUI is updated weekly by the task scheduler. You can force an update with the following Artisan command:
php $IXPROOT/artisan utils:oui-update\nwhich will populate / update the OUI database directly from the latest IEEE file from their website.
A specific file can be passed via the file parameter. You can also force a database reset (drop all OUI entries and re-populate) via the --refresh option.
Neither of these options are typically necessary.
"},{"location":"features/layer2-addresses/#end-user-access","title":"End User Access","text":"In v4.7.3 we introduced the ability for logged in users to management their own configured MAC addresses.
This is disabled by default but can be enabled with the following .env settings:
# Set this to allow customers to change their own configured MAC addresses:\nIXP_FE_LAYER2_ADDRESSES_CUST_CAN_EDIT=true\n\n# The following defaults are configured for min/max MAC addresses\nIXP_FE_LAYER2_ADDRESSES_CUST_PARAMS_MIN_ADDRESSES=1\nIXP_FE_LAYER2_ADDRESSES_CUST_PARAMS_MAX_ADDRESSES=2\nWhen a MAC is added, a IXP\\Events\\Layer2Address\\Added event is triggered and, similarly, when a MAC is deleted a IXP\\Events\\Layer2Address\\Deleted event is triggered. We have created an event listener for these to fire off an email in both cases. To enable this listener, set the following .env settings:
# Trigger an email when a superuser adds/deletes a MAC:\nIXP_FE_LAYER2_ADDRESSES_EMAIL_ON_SUPERUSER_CHANGE=true\n\n# Trigger an email when a customer user adds/deletes a MAC:\nIXP_FE_LAYER2_ADDRESSES_EMAIL_ON_CUSTOMER_CHANGE=true\n\n# Destination address of the email:\nIXP_FE_LAYER2_ADDRESSES_EMAIL_ON_CHANGE_DEST=ops@ixp.example.net\nThere are two files you can consider skinning with this functionality:
resources/views/layer2-address/emails/changed.blade.php - the email which is sent when a MAC is added / removed.resources/views/layer2-address/customer-edit-msg.foil.php - an informational alert box that is shown to the customer on the MAC add/delete page to set their expectations on time to complete on the IXP end.IXP Manager supports full looking glass features when using the Bird BGP daemon and Bird's Eye (a simple secure micro service for querying Bird).
A fully working example of this can be seen here on INEX's IXP Manager.
Enabling the looking glass just requires:
.env option: IXP_FE_FRONTEND_DISABLED_LOOKING_GLASS=false (in IXP Manager's .env and add it if it's missing as it defaults to true).The looking glass will not work if the versions are not matched correctly as above.
"},{"location":"features/looking-glass/#example-router-configuration","title":"Example Router Configuration","text":"See this screenshot for an appropriately configured INEX router with Bird's Eye:
"},{"location":"features/looking-glass/#looking-glass-pass-thru-api-calls","title":"Looking Glass 'Pass Thru' API Calls","text":"Depending on the configured LG Access Privileges for a given router, IXP Manager will pass through the following API calls to the router API.
https://ixp.example.com/api/v4/lg/{handle}/statushttps://ixp.example.com/api/v4/lg/{handle}/bgp-summaryand return the JSON result.
The rationale for this is that we expect most IX's to keep direct access to looking glass implementations on internal / private networks.
Here are two live examples from INEX:
You can see all of INEX's looking glasses at https://www.inex.ie/ixp/lg. GRNET have also a public IXP Manager integration at: https://portal.gr-ix.gr/lg.
"},{"location":"features/looking-glass/#debugging","title":"Debugging","text":"Generally speaking, if you carefully read the above and the Bird's Eye README file, you should be able to get IXP Manager / Bird's Eye integration working.
If you do not, try all of the following and solve any elements that fail. If you still have issues, email the IXP Manager mailing list with the output of all of the following commands from both sections.
For the following examples, we will use a real INEX example router with these settings:
mysql> SELECT * FROM routers WHERE id = 17\\G\n*************************** 1. row ***************************\n id: 17\n vlan_id: 2\n handle: as112-lan1-ipv4\n protocol: 4\n type: 3\n name: INEX LAN1 - AS112 - IPv4\n shortname: AS112 - LAN1 - IPv4\n router_id: 185.6.36.6\n peering_ip: 185.6.36.6\n asn: 112\n software: 1\n mgmt_host: 10.39.5.6\n api: http://as112-lan1-ipv4.mgmt.inex.ie/api\n api_type: 1\n lg_access: 0\n quarantine: 0\n bgp_lc: 0\n template: api/v4/router/as112/bird/standard\n skip_md5: 1\nlast_updated: 2018-02-03 14:26:15\nFrom the server running IXP Manager:
###############################################################################\n# Does the API hostname resolve?\n$ dig +short as112-lan1-ipv4.mgmt.inex.ie\n\n10.39.5.6\n\n\n###############################################################################\n# Is there network access?\n$ ping as112-lan1-ipv4.mgmt.inex.ie -c 1\n\nPING as112.mgmt.inex.ie (10.39.5.6) 56(84) bytes of data.\n64 bytes from as112.mgmt.inex.ie (10.39.5.6): icmp_seq=1 ttl=64 time=0.103 ms\n\n--- as112.mgmt.inex.ie ping statistics ---\n1 packets transmitted, 1 received, 0% packet loss, time 0ms\nrtt min/avg/max/mdev = 0.103/0.103/0.103/0.000 ms\n\n\n###############################################################################\n# Is the Bird's Eye service available?\n$ curl -v http://as112-lan1-ipv4.mgmt.inex.ie/api/status\n\n* Trying 10.39.5.6...\n* Connected to as112-lan1-ipv4.mgmt.inex.ie (10.39.5.6) port 80 (#0)\n> GET /api/status HTTP/1.1\n> Host: as112-lan1-ipv4.mgmt.inex.ie\n> User-Agent: curl/7.47.0\n> Accept: */*\n>\n< HTTP/1.1 200 OK\n< Cache-Control: no-cache\n< Content-Type: application/json\n< Date: Mon, 12 Feb 2018 16:29:52 GMT\n< Transfer-Encoding: chunked\n< Server: lighttpd/1.4.35\n<\n* Connection #0 to host as112-lan1-ipv4.mgmt.inex.ie left intact\n\n{\n \"api\": {\n \"from_cache\":true,\n \"ttl_mins\":1,\n \"version\":\"1.1.0\",\n \"max_routes\":1000\n },\n \"status\": {\n \"version\":\"1.6.3\",\n \"router_id\":\"185.6.36.6\",\n \"server_time\":\"2018-02-12T16:29:48+00:00\",\n \"last_reboot\":\"2017-11-09T00:23:24+00:00\",\n \"last_reconfig\":\"2018-02-12T16:26:14+00:00\",\n \"message\":\"Daemon is up and running\"\n }\n}\nIf all of the above checks out, watch the log file while you try and access the looking glass:
cd $IXPROOT\ntail -f storage/log/laravel.log\nIf there are error messages in the above log as you try and access the looking glass, include them when emailing the mailing list for help.
Then on the router (the server running Bird's Eye), you need to provide the following answers when seeking help:
###############################################################################\n# Are you running the correct version of Bird's Eye for IXP Manager?\n\ncat /srv/birdseye/version.php\n\n# see the documentation above for the correct versions to match to IXP Manager.\n\n###############################################################################\n# Is Bird actually running and what are the names of its sockets:\n$ ls -la /var/run/bird\n\ntotal 0\ndrwxrwxr-x 2 bird bird 120 Nov 9 00:26 .\ndrwxr-xr-x 25 root root 900 Feb 12 19:40 ..\nsrw-rw---- 1 root root 0 Nov 9 00:23 bird-as112-lan1-ipv4.ctl\nsrw-rw---- 1 root root 0 Nov 9 00:23 bird-as112-lan1-ipv6.ctl\nsrw-rw---- 1 root root 0 Nov 9 00:23 bird-as112-lan2-ipv4.ctl\nsrw-rw---- 1 root root 0 Nov 9 00:23 bird-as112-lan2-ipv6.ctl\n\n###############################################################################\n# What configuration file(s) exist:\n$ ls -la /srv/birdseye/*env\n\n-rw-r--r-- 1 root root 2833 Dec 5 2016 /srv/birdseye/birdseye-as112-lan1-ipv4.env\n-rw-r--r-- 1 root root 2833 Dec 5 2016 /srv/birdseye/birdseye-as112-lan1-ipv6.env\n-rw-r--r-- 1 root root 2833 Dec 5 2016 /srv/birdseye/birdseye-as112-lan2-ipv4.env\n-rw-r--r-- 1 root root 2833 Dec 5 2016 /srv/birdseye/birdseye-as112-lan2-ipv6.env\n\n###############################################################################\n# Let's see the contents of these:\n#\n# NB: when specifying the BIRDC parameter below, for Bird v1.x.y, use the -4/-6\n# switch when querying the ipv4/6 daemon respectively. For Bird v2.x.y, use\n# the -2 switch.\n#\n$ cat /srv/birdseye/*env | egrep -v '(^#)|(^\\s*$)'\n\nBIRDC=\"/usr/bin/sudo /srv/birdseye/bin/birdc -4 -s /var/run/bird/bird-as112-lan1-ipv4.ctl\"\nCACHE_DRIVER=file\nLOOKING_GLASS_ENABLED=true\nBIRDC=\"/usr/bin/sudo /srv/birdseye/bin/birdc -6 -s /var/run/bird/bird-as112-lan1-ipv6.ctl\"\nCACHE_DRIVER=file\nLOOKING_GLASS_ENABLED=true\nBIRDC=\"/usr/bin/sudo /srv/birdseye/bin/birdc -4 -s /var/run/bird/bird-as112-lan2-ipv4.ctl\"\nCACHE_DRIVER=file\nLOOKING_GLASS_ENABLED=true\nBIRDC=\"/usr/bin/sudo /srv/birdseye/bin/birdc -6 -s /var/run/bird/bird-as112-lan2-ipv6.ctl\"\nCACHE_DRIVER=file\nLOOKING_GLASS_ENABLED=true\n\n###############################################################################\n# Test birdc access to the daemon - run for each socket found above:\n# (only one shown here for brevity - include all in your request for help!)\n$ /usr/sbin/birdc -s /var/run/bird/bird-as112-lan1-ipv4.ctl show status\n\nBIRD 1.6.3 ready.\nBIRD 1.6.3\nRouter ID is 185.6.36.6\nCurrent server time is 2018-02-12 19:42:42\nLast reboot on 2017-11-09 00:23:25\nLast reconfiguration on 2018-02-12 19:26:15\nDaemon is up and running\n\n###############################################################################\n# Have you created the sudo file for www-data to be able to access Birdc?\n$ cat /etc/sudoers /etc/sudoers.d/* | grep birdseye\n\nwww-data ALL=(ALL) NOPASSWD: /srv/birdseye/bin/birdc\n\n###############################################################################\n# Does the Bird's Eye client work?\n#\u00a0Run for each socket found above with the appropriate protocol (-4/-6):\n# (only one shown here for brevity - include all in your request for help!)\n\n$ /srv/birdseye/bin/birdc -4 -s /var/run/bird/bird-as112-lan1-ipv4.ctl show status\n\nBIRD 1.6.3 ready.\nAccess restricted\nBIRD 1.6.3\nRouter ID is 185.6.36.6\nCurrent server time is 2018-02-12 19:44:31\nLast reboot on 2017-11-09 00:23:25\nLast reconfiguration on 2018-02-12 19:26:15\nDaemon is up and running\n\n\n###############################################################################\n# Is the web server running:\n$ netstat -lpn | grep lighttpd\n\ntcp 0 0 10.39.5.6:80 0.0.0.0:* LISTEN 1165/lighttpd\ntcp6 0 0 2001:7f8:18:5::6:80 :::* LISTEN 1165/lighttpd\nunix 2 [ ACC ] STREAM LISTENING 13970 635/php-cgi /var/run/lighttpd/php.socket-0\n\n###############################################################################\n# Is PHP running:\n$ netstat -lpn | grep php\n\nunix 2 [ ACC ] STREAM LISTENING 13970 635/php-cgi /var/run/lighttpd/php.socket-0\n\n###############################################################################\n# what's the web server configuration\n# NB: make sure you have compared it to:\n# https://github.com/inex/birdseye/blob/master/data/configs/lighttpd.conf\n$ cat /etc/lighttpd/lighttpd.conf\n\n<not included but linked two lines up>\n\n###############################################################################\n# provide the IXP Manager configuration of your router(s):\nmysql> SELECT * FROM routers\\G\n\n<not included - see example at start of this section>\nIXP Manager has the ability to allow users to subscribe / unsubscribe from Mailman mailing lists (it should be relatively easy to expand this to other mailing list managers as the functionality is based on Mailman but not Mailman specific).
The following sections explain the steps in how this is set up.
NB: This facility does not perform a 100% synchronisation. Any mailing list members that are added separately without a matching user in IXP Manager are not interfered with.
"},{"location":"features/mailing-lists/#configuring-available-mailing-lists","title":"Configuring Available Mailing Lists","text":"There is a sample configuration file which you need to copy as follows:
cd $IXPROOT\ncp config/mailinglists.php.dist config/mailinglists.php\nYou then need to edit this file as follows:
Enable the mailing list functionality by setting this to true:
// Set the following to 'true' to enable mailing list functionality:\n'enabled' => true,\nIf this is not set to true, the user will not be offered subscription options and the CLI/API commands will not execute.
Configure the available mailing list(s) in the lists array. Here is an example:
'lists' => [\n 'members' => [\n 'name' => \"Members' Mailing List\",\n 'desc' => \"A longer description as presented in IXP Manager.\",\n 'email' => \"members@example.com\",\n 'archive' => \"https://www.example.com/mailman/private/members/\",\n ],\n 'tech' => [\n 'name' => \"Tech/Operations Mailing List\",\n 'desc' => \"A longer description as presented in IXP Manager.\",\n 'email' => \"tech@example.com\",\n 'archive' => \"https://www.example.com/mailman/private/tech/\",\n ],\n],\nNote that the members and tech array keys above are the list handles that will be used by the API interfaces later. It is also important that they match the Mailman list key.
Historically, mailing list passwords were also sync'd from the IXP Manager user database unless syncpws is both defined and false for the given list. As we are now enforcing bcrypt as the standard password hashing mechanism, we no longer support this and suggest allowing Mailman to manage its own passwords.
Paths to Mailman commands. These will be used in the API/CLI elements later:
'mailman' => [\n 'cmds' => [\n 'list_members' => \"/usr/local/mailman/bin/list_members\",\n 'add_members' => \"/usr/local/mailman/bin/add_members -r - -w n -a n\",\n 'remove_members' => \"/usr/local/mailman/bin/remove_members -f - -n -N\",\n 'changepw' => \"/usr/local/mailman/bin/withlist -q -l -r changepw\"\n ]\n]\nThis mailing list synchronisation / integration code was written for existing Mailman lists we have at INEX where some lists are public with subscribers that will never have an account on INEX's IXP Manager. As such, these scripts are written so that email addresses in common between IXP Manager and Mailman can manage their subscriptions in IXP Manager but those other subscribers will be unaffected.
Users in IXP Manager will either be marked as being subscribed to a list, not subscribed to a list or neither (i.e. a new user). Subscriptions are managed by user preferences (in the database) of the format:
mailinglist.listname1.subscribed = 0/1\nThere are three steps to performing the synchronisation for each list which are done by either using the IXP Manager CLI script artisan mailing-list:... or the API interface.
NB: these relate to the CLI as implemented from IXP Manager >= v4.7.
The execution of the artisan mailing-list:init script which is really for new IXP Manager users (or initial set up of the mailing list feature). This script is piped the full subscribers list from Mailman (via list_members). This function will iterate through all users and, if they have no preference set for subscription to this list, will either add a \"not subscribed\" preference if their email address is not in the provided list of subscribers or a \"subscribed\" preference if it is.
The execution of the artisan mailing-list:get-subscribers action which lists all users who are subscribed to the given mailing list based on their user preferences. This is piped to the add_members Mailman script.
The execution of the artisan mailing-list:get-subscribers --unsubscribed action which lists all users who are unsubscribed to the given mailing list based on their user preferences. This is piped to the remove_members Mailman script.
The API v4 implementation was added in IXP Manager v4.7. See the end of this document for the API v1 implementation in previous versions of IXP Manager.
If you wish to use the API version, proceed as follows where:
$KEY is one of your SUPERUSER API keys (see here for details);https://ixp.example.com is your IXP Manager web interface;members is an example mailing list handle as defined above in $IXPROOT/config/mailinglists.php.Use the initialisation function for new IXP Manager users (or initial set up of the mailing list feature) which updates IXP Manager with all currently subscribed mailing list members:
/path/to/mailman/bin/list_members members >/tmp/ml-members.txt\ncurl -f --data-urlencode addresses@/tmp/ml-members.txt \\\n -H \"X-IXP-Manager-API-Key: $KEY\" -X POST\n \"https://ixp.example.co/api/v4/mailing-list/init/members\"\nrm /tmp/ml-members.txt\nPipe all subscribed users to the add_members Mailman script:
curl -f -H \"X-IXP-Manager-API-Key: $KEY\" -X GET \\\n \"https://ixp.example.co/api/v4/mailing-list/subscribers/members\" | \\\n /path/to/mailman/bin/add_members -r - -w n -a n members >/dev/null\nPipe all users who are unsubscribed to the remove_members Mailman script:
curl -f -H \"X-IXP-Manager-API-Key: $KEY\" -X GET \\\n \"https://ixp.example.co/api/v4/mailing-list/unsubscribed/members\" | \\\n /path/to/mailman/bin/remove_members -f - -n -N members >/dev/null\nYou can implement mailing list management by configuring IXP Manager as above.
IXP Manager will generate shell scripts to manage all of the above.
Execute the following command for the CLI version (and make sure to update the assignments at the top of the script):
artisan mailing-list:sync-script --sh\nOr the following for the API V4 version (and make sure to update the assignments at the top of the script):
artisan mailing-list:sync-script\nThis generates a script which performs each of the above four steps for each configured mailing list. If your mailing list configuration does not change, you will not need to rerun this.
You should now put this script into crontab on the appropriate server (same server for CLI!) and run as often as you feel is necessary. The current success message for a user updating their subscriptions says within 12 hours so we'd recommend at least running twice a day.
"},{"location":"features/mailing-lists/#todo","title":"Todo","text":"DEPRECATED and only available in IXP Manager <v4.7.
The CLI version of mailing list management was presented above. If you wish to use the API version, proceed as follows where:
$MyKey is one of your SUPERUSER API keys;https://www.example.com/ixp/ is your IXP Manager web interface;members is an example mailing list handle as defined above in $IXPROOT/config/mailinglists.php.Use the initialisation function for new IXP Manager users (or initial set up of the mailing list feature) which updates IXP Manager with all currently subscribed mailing list members:
/path/to/mailman/bin/list_members members >/tmp/ml-listname1.txt\ncurl -f --data-urlencode addresses@/tmp/ml-listname1.txt \\\n \"https://www.example.com/ixp/apiv1/mailing-list/init/key/$MyKey/list/members\"\nrm /tmp/ml-listname1.txt\nPipe all subscribed users to the add_members Mailman script:
curl -f \"https://www.example.com/ixp/apiv1/mailing-list/get-subscribed/key/$MyKey/list/members\" | \\\n /path/to/mailman/bin/add_members -r - -w n -a n members >/dev/null\nPipe all users who are unsubscribed to the remove_members Mailman script:
curl -f \"https://www.example.com/ixp/apiv1/mailing-list/get-unsubscribed/key/$MyKey/list/members\" | \\\n /path/to/mailman/bin/remove_members -f - -n -N members >/dev/null\nMANRS - Mutually Agreed Norms for Routing Security - is a global initiative, supported by the Internet Society, that provides crucial fixes to reduce the most common routing threats. \ufeff
IXP Manager >=v5.0 rewards networks that have joined the MANRS program by highlighting this on the customer's public and internal pages - for example:
This information is updated daily via the task scheduler. If you want to run it manually, run this Artisan command:
$ php artisan ixp-manager:update-in-manrs -vv\nMANRS membership updated - before/after/missing: 5/5/104\nAs you'll see from the output, it will show you the results. We will provide more tooling within IXP Manager to show this information in time.
"},{"location":"features/member-export/","title":"Member Export","text":"The recommended means of exporting member details from IXP Manager is to use the IX-F Member Export tool. We even provide examples of how to use this to create example tables.
However, you may sometimes require additional flexibility which necessitates rolling your own export templates. This Member Export feature will allow you to do this but it does require some PHP programming ability.
This Member Export feature is modeled after the static content tool and you are advised to read that page also.
This feature first appears in v4.8.0 and replaces the deprecated older way of handling this.
"},{"location":"features/member-export/#overview","title":"Overview","text":"In IXP Manager, there are four types of users as described in the users page. Member export templates can be added which requires a minimum user privilege to access (e.g. priv == 0 would be publicly accessible through to priv == 3 which would require a superadmin).
To create your own member export templte, you should first set up skinning for your installation. Let's assume you called your skin example in the following.
To create a publicly accessible member export page called lonap, you would first create a directory structure in your skin as follows:
cd ${IXPROOT}\nmkdir -p resources/skins/example/content/members/{0,1,2,3}\nwhere the directories 0, 1, 2, 3 represent the minimum required user privilege to access the template. You can now create your export template page by creating a file:
resources/skins/example/content/members/0/lonap.foil.php\nand then edit that page. In fact, we have bundled three examples in the following locations:
resources/skins/example/content/members/3/lonap.foil.php: a table that replicates how LONAP have traditionally listed their members (see here). It would be accessed via: https://ixp.example.com/content/members/3/lonapresources/skins/example/content/members/3/json-example.foil.php: a JSON example of the above. The HTTP response content type is set to JSON with .json is added to the URL. However you have to ensure your template outputs JSON also. This would be accessed via: https://ixp.example.com/content/members/3/json-example.jsonresources/skins/inex/content/members/0/list.foil.php: what we at INEX use to generate this members list. You can access the real data via: https://www.inex.ie/ixp/content/members/0/list.json (not that this is publicly accessible).The format of the URL to access these member export templates is:
https://ixp.example.com/content/members/{priv}/{page}[.json]\n{priv} is the minimum required user privilege required to access the page and is used first for testing the user's permissions and second as the directory to check for the file.{page} is the name of the file to load (less .foil.php) and please be aware that this is normalised as follows: preg_replace( '/[^a-z0-9\\-_]/', '', strtolower( $page ) )\n[a-z0-9\\-_] and all lower case.[.json] is an optional extension which tells IXP Manager to set the Content-Type: application/json header in the response.At INEX we use Nagios to monitor a number of production services including:
IXP Manager can generate configuration to monitor the above for you.
NB: IXP Manager will not install and configure Nagios from scratch. You need a working Nagios installation first and then IXP Manager will automate the above areas of the configuration.
"},{"location":"features/nagios/#historical-notes","title":"Historical Notes","text":"If you have used Nagios on IXP Manager <4.5, then how the configuration is generated has changed. The older documentation may be available here. In previous versions of IXP Manager, we generated entire / monolithic Nagios configuration files. We have found in practice that this does not scale well and creates a number of limitations.
IXP Manager >= v4.5 now simply creates the targets on a per VLAN and protocol basis.
"},{"location":"features/nagios/#sample-scripts","title":"Sample Scripts","text":"You will find sample scripts for pulling Nagios configuration from IXP Manager and reloading Nagios at:
https://github.com/inex/IXP-Manager/tree/master/tools/runtime/nagios
"},{"location":"features/nagios/#monitoring-member-reachability","title":"Monitoring Member Reachability","text":"We monitor all member router interfaces (unless asked not to) via ICMP[v6] pings with Nagios. This is all controlled by the Nagios configuration created with this feature.
To enable / disable these checks, edit the VLAN interface configuration and set IPvX Can Ping appropriately. Note that when IPvX Can Ping is disabled, the host definition is created anyway as this would be used for other Nagios checks such as route collector sessions.
There is an additional option when editing a member's VLAN interface called Busy Host. This changes the Nagios ping fidelity from 250.0,20%!500.0,60% to 1000.0,80%!2000.0,90% (using the default object definitions which are configurable). This is useful for routers with slow / rate limited control planes.
Members are added to a number of hostgroups also:
These hostgroups are very useful to single out issues and for post-maintenance checks.
You can use the IXP Manager API to get the Nagios configuration for a given VLAN and protocol using the following endpoint format (both GET and POST requests work):
https://ixp.example.com/api/v4/nagios/customers/{vlanid}/{protocol}\nwhere:
vlanid is the database ID (DB ID) of the VLAN. You can find the DB ID in IXP Manager in the VLAN table (select VLANs from the left hand side menu).protocol is either 4 for IPv4 or 6 for IPv6.If either of these are invalid, the API will return with a HTTP 404 response.
And example of a target in the response is:
###############################################################################################\n###\n### Packet Clearing House DNS\n###\n### Equinix DB2 (Kilcarbery) / Packet Clearing House DNS / swi1-kcp1-1.\n###\n\n### Host: 185.6.36.60 / inex.woodynet.net / Peering VLAN #1.\n\ndefine host {\n use ixp-manager-member-host\n host_name packet-clearing-house-dns-as42-ipv4-vlanid2-vliid109\n alias Packet Clearing House DNS / swi1-kcp1-1 / Peering VLAN #1.\n address 185.6.36.60\n}\n\n### Service: 185.6.36.60 / inex.woodynet.net / Peering VLAN #1.\n\ndefine service {\n use ixp-manager-member-ping-service\n host_name packet-clearing-house-dns-as42-ipv4-vlanid2-vliid109\n}\nYou will notice that the above configuration example is very light and is missing an awful lot of Nagios required configuration directives. This is intentional so that IXP Manager is not too prescriptive and allows you to define your own Nagios objects without having to resort to skinning IXP Manager.
Two of the most important elements of Nagios configuration which you need to understand are object definitions and object inheritance.
You can pass three optional parameters to Nagios via GET/POST and these are:
host_definition; defaults to: ixp-manager-member-host.service_definition; defaults to ixp-manager-member-service.ping_service_definition; defaults to: ixp-manager-member-ping-service.ping_busy_service_definition; defaults to: ixp-manager-member-ping-busy-service.An example of changing two of these parameters is:
curl --data \"host_definition=my-host-def&service_definition=my-service-def\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/nagios/customers/2/4\nAn example of the three objects that INEX use for this are:
define host {\n name ixp-manager-member-host\n check_command check-host-alive\n check_period 24x7\n max_check_attempts 10\n notification_interval 120\n notification_period 24x7\n notification_options d,u,r\n contact_groups admins\n register 0\n}\n\ndefine service {\n name ixp-manager-member-service\n check_period 24x7\n max_check_attempts 10\n check_interval 5\n retry_check_interval 1\n contact_groups admins\n notification_interval 120\n notification_period 24x7\n notification_options w,u,c,r\n register 0\n}\n\ndefine service {\n name ixp-manager-member-ping-service\n use ixp-manager-member-service\n service_description PING\n check_command check_ping!250.0,20%!500.0,60%\n register 0\n}\n\ndefine service {\n name ixp-manager-member-ping-busy-service\n use ixp-manager-member-service\n service_description PING-Busy\n check_command check_ping!1000.0,80%!2000.0,90%\n register 0\n}\nYou can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called mytemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/nagios/customers\ncp resources/views/api/v4/nagios/customers/default.foil.php resources/skins/myskin/api/v4/nagios/customers/mytemplate1.foil.php\nYou can now edit this template as required. The only constraint on the template name is it can only contain characters from the classes a-z, 0-9, -. NB: do not use uppercase characters.
You can then elect to use this template by tacking the name onto the API request:
https://ixp.example.com/api/v4/nagios/customers/{vlanid}/{protocol}/{template}\nwhere, in this example, {template} would be: mytemplate1.
As a policy, INEX tends to use the bundled templates and as such they should be fit for general purpose.
"},{"location":"features/nagios/#switch-monitoring","title":"Switch Monitoring","text":"We monitor all production peering LAN switches for a number of difference services (see below).
IXP Manager produces a host configuration for each production switch such as:
#\n# swi2-dc1-1 - DUB01.XX.YY.ZZ, Data Centre DUB1.\n#\n\ndefine host {\n use ixp-manager-production-switch\n host_name swi2-dc1-1.mgmt.inex.ie\n alias swi2-dc1-1\n address 192.0.2.4\n _DBID 74\n}\nMembers are added to a number of hostgroups also:
These hostgroups are very useful when defining service checks.
You can use the IXP Manager API to get the Nagios configuration for a given infrastructure using the following endpoint format (both GET and POST requests work):
https://ixp.example.com/api/v4/nagios/switches/{infraid}\nwhere:
infraid is the database ID (DB ID) of the infrastructure. You can find the DB ID in IXP Manager in the infrastructures table (select Infrastructures from the left hand side menu).You can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called myswtemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/nagios/switches\ncp resources/views/api/v4/nagios/switches/default.foil.php resources/skins/myskin/api/v4/nagios/switches/myswtemplate1.foil.php\nYou can then elect to use this template by tacking the name onto the API request:
https://ixp.example.com/api/v4/nagios/switches/{infraid}/{template}\nwhere, in this example, {template} would be: myswtemplate1.
You can pass one optional parameter to Nagios via GET/POST which is the host definition to inherit from (see customer reachability testing about for full details and examples):
curl --data \"host_definition=my-sw-host-def\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/nagios/switches/2\nThe recommended way to check various services on your production switches is to use the host groups created by the above switch API call. An example of the hostgroups produced include:
ixp-production-switches-infraid-2: all switches on an infrastructure with DB ID 2;ixp-switches-infraid-2-dc-dub1: all switches in location dc-dub1;ixp-switches-infraid-2-extreme: all Extreme switches on an infrastructure with DB ID 2; andixp-switches-infraid-2-extreme-x670g2-48x-4q: all Extreme switches of model X670G2-48x-4q on an infrastructure with DB ID 2.Using these, you can create generic service definitions to apply to all hosts such as:
define service{\n use my-ixp-production-switch-service\n hostgroup_name ixp-production-switches-infraid-1, ixp-production-switches-infraid-2\n service_description ping - IPv4\n check_command check_ping_ipv4!10!100.0,10%!200.0,20%\n}\n\ndefine service {\n use my-ixp-production-switch-service\n hostgroup_name ixp-production-switches-infraid-1, ixp-production-switches-infraid-2\n service_description SSH\n check_command check_ssh\n}\nYou can target vendor / model specific checks as appropriate:
define service{\n use my-ixp-production-switch-service\n hostgroup_name ixp-switches-infraid-1-extreme, ixp-switches-infraid-2-extreme\n service_description Chassis\n check_command check_extreme_chassis\n}\nThe one thing you'll need to keep an eye on is adding hostgroups to service checks as you create new infrastructures / add new switch vendors / models.
Hint: over the years, we at INEX have written a number of switch chassis check scripts and these can be found on Github at barryo/nagios-plugins.
For example the Extreme version checks and returns something like:
OK - CPU: 5sec - 10%. Uptime: 62.8 days. PSUs: 1 - presentOK: 2 - presentOK:. Overall system power state: redundant power available. Fans: [101 - OK (4311 RPM)]: [102 - OK (9273 RPM)]: [103 - OK (4468 RPM)]: [104 - OK (9637 RPM)]: [105 - OK (4165 RPM)]: [106 - OK (9273 RPM)]:. Temp: 34'C. Memory (slot:usage%): 1:29%.
"},{"location":"features/nagios/#birdseye-daemon-monitoring","title":"Birdseye Daemon Monitoring","text":"We monitor our Bird instances at INEX directly through Birdseye, the software we use for our looking glass. This means it is currently tightly coupled to Bird and Birdseye until such time as we look at a second router software.
IXP Manager produces a host and service configuration for each router such as:
define host {\n use ixp-manager-host-birdseye-daemon\n host_name bird-rc1q-cork-ipv4\n alias INEX Cork - Quarantine Route Collector - IPv4\n address 10.40.5.134\n _api_url http://rc1q-ipv4.cork.inex.ie/api\n}\n\ndefine service {\n use ixp-manager-service-birdseye-daemon\n host_name bird-rc1q-cork-ipv4\n}\nYou can use the IXP Manager API to get the Nagios configuration for all or a given VLAN using the following endpoint format (both GET and POST requests work):
https://ixp.example.com/api/v4/nagios/birdseye-daemons\nhttps://ixp.example.com/api/v4/nagios/birdseye-daemons/{template}\nhttps://ixp.example.com/api/v4/nagios/birdseye-daemons/default/{vlanid}\nhttps://ixp.example.com/api/v4/nagios/birdseye-daemons/{template}/{vlanid}\nwhere:
{template} is the optional skin (see below).{vlanid} is the VLAN id to limit the results to. If setting this, you need to provide a template also (or default for the standard template).You can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called mybetemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/nagios/birdseye-daemons\ncp resources/views/api/v4/nagios/birdseye-daemons/default.foil.php resources/skins/myskin/api/v4/nagios/birdseye-daemons/mybetemplate1.foil.php\nYou can then elect to use this template by tacking the name onto the API request:
https://ixp.example.com/api/v4/nagios/birdseye-daemons/{template}\nwhere, in this example, {template} would be: mybetemplate1.
You can pass two optional parameter to Nagios via GET/POST which is the host and service definition to inherit from (see customer reachability testing about for full details and examples):
curl --data \"host_definition=my-be-host-def&service_definition=my-be-srv-def\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/nagios/birdseye-daemons\nThe default values for the host and service definitions are ixp-manager-host-birdseye-daemon and ixp-manager-service-birdseye-daemon respectively.
You will need to create a parent host and service definition for the generated configuration such as:
define host {\n name ixp-manager-host-birdseye-daemon\n check_command check-host-alive\n check_period 24x7\n max_check_attempts 10\n notification_interval 120\n notification_period 24x7\n notification_options d,u,r\n contact_groups admins\n register 0\n}\n\ndefine service {\n name ixp-manager-service-birdseye-daemon\n service_description Bird BGP Service\n check_command check_birdseye_daemon!$_HOSTAPIURL$\n check_period 24x7\n max_check_attempts 10\n check_interval 5\n retry_check_interval 1\n contact_groups admins\n notification_interval 120\n notification_period 24x7\n notification_options w,u,c,r\n register 0\n}\n\ndefine command{\n command_name check_birdseye_daemon\n command_line /usr/local/nagios-plugins-other/nagios-check-birdseye.php -a $ARG1$\n}\nThe Nagios script we use is bundled with inex/birdseye and can be found here.
Typical Nagios state output:
OK: Bird 1.6.2. Bird's Eye 1.0.4. Router ID 192.0.2.126. Uptime: 235 days. Last Reconfigure: 2017-07-17 16:00:04.26 BGP sessions up of 28.
"},{"location":"features/nagios/#birdseye-bgp-session-monitoring","title":"Birdseye BGP Session Monitoring","text":"We monitor our Bird route collector, route server and AS112 Bird BGP sessions at INEX directly through Birdseye, the software we use for our looking glass. This means it is currently tightly coupled to Bird and Birdseye until such time as we look at a second router software.
IXP Manager produces a host and service configuration for each router type such as:
### Router: INEX LAN1 - Route Collector - IPv4 / 192.0.2.126.\n\ndefine service {\n use ixp-manager-member-bgp-session-service\n host_name as112-reverse-dns-as112-ipv4-vlanid2-vliid99\n service_description BGP session to rc1-lan1-ipv4 (INEX LAN1 - Route Collector - IPv4)\n _api_url http://www.example.com/api\n _protocol pb_0099_as112\n}\nThe configuration also includes hostgroups for the given VLAN, protocol and type for:
You can use the IXP Manager API to get the Nagios configuration for a given protocol, VLAN and router type using the following templates:
https://ixp.example.com/api/v4/nagios/birdseye-bgp-sessions/{vlanid}/{protocol}/{type}\nhttps://ixp.example.com/api/v4/nagios/birdseye-bgp-sessions/{vlanid}/{protocol}/{type}/{template}\nwhere:
{vlanid} is the VLAN id to generate the configuration for.{protocol} is either 4 (ipv4) or 6 (ipv6).{type} is one of (these are defined in Entities\\Router):1 for route servers;2 for route collectors;3 for AS112You can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called myrstemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/nagios/birdseye-bgp-sessions\ncp resources/views/api/v4/nagios/birdseye-bgp-sessions/default.foil.php resources/skins/myskin/api/v4/nagios/birdseye-bgp-sessions/myrstemplate1.foil.php\nYou can then elect to use this template by tacking the name onto the API request:
https://ixp.example.com/api/v4/nagios/birdseye-bgp-sessions/{vlanid}/{protocol}/{type}/{template}\nwhere, in this example, {template} would be: myrstemplate1.
You can pass one optional parameter to Nagios via GET/POST which is the service definition to inherit from (see customer reachability testing about for full details and examples):
curl --data \"service_definition=my-rs-srv-def\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/nagios/birdseye-bgpsessions/2/4/1\nThe default values for the service definition is ixp-manager-member-bgp-session-service respectively.
You will need to create a parent service definition and a check command for the generated configuration such as:
define service {\n name ixp-manager-member-bgp-session-service\n service_description Member Bird BGP Sessions\n check_period 24x7\n max_check_attempts 10\n check_interval 5\n retry_check_interval 1\n contact_groups admins\n notification_interval 120\n notification_period 24x7\n notification_options w,u,c,r\n register 0\n check_command check_birdseye_bgp_session!$_SERVICEAPI_URL!$_SERVICEPROTOCOL\n}\n\ndefine command{\n command_name check_birdseye_bgp_session\n command_line /path/to/nagios-check-birdseye-bgp-sessions.php -a $ARG1$ -p $ARG2$ -n\n}\nThe Nagios script we use is bundled with inex/birdseye and can be found here.
"},{"location":"features/patch-panels/","title":"Patch Panels / Cross Connects","text":"One of the more difficult things for an IXP to manage is the sheer volume of patch panels / cross connects they need to manage. We have approached the issue a number of times in IXP Manager but abandoned the attempt every time. Typically our original solutions were over-engineered where all we really needed was something which could replace a spreadsheet per panel.
We believe we have now developed a feature complete and useful means of managing patch panels and associated cross connects.
"},{"location":"features/patch-panels/#features","title":"Features","text":"We suggest adding fibre ports as two ports per duplex port. I.e. if your patch panel has 12 duplex ports, enter this as 24 ports. When allocating ports later, you can set it as a duplex port and select its partner / slave port. This will future proof your patch panels for the growing use of bidi optics and other simplex based xWDM fibre solutions.
From our experience, duplex fibre ports are often identified as their individual strands. For example, duplex port 5 would be referenced as F9/F10.
Your mileage may vary on this but we need to allow this flexibility to cover both use-cases. You always have options however:
The following image shows a typical add a new patch panel form (as of v4.3). You'll note that clicking Help provides detailed context aware help messages.
Most of this is self-explanatory but:
In addition to that, we will also use a cabinets U's are counted from top/bottom, and a patch panel's U position and mounted at front/rear to also create a location description. * When setting the Number of Ports, ensure you count duplex fibre ports as two ports. So 12 duplex fibre ports would be entered as 24. When editing a patch panel, this input field represents the number of additional ports you want to add to a patch panel and thus defaults to 0 in that situation. * Port Name Prefix: This is an optional field intended for use on fibre patch panels. As an example, you may wish to prefix individual fibre strands in a duplex port with F which would mean the name of a duplex port would be displayed as F1/F2. * Chargeable: Usually IXPs request their members to come to them and bear the costs of that. However, sometimes a co-location facility may charge the IXP for a half circuit or the IXP may need order and pay for the connection. Setting this only sets the default option when allocating ports to members later. The options are Yes / No / Half / Other.
"},{"location":"features/patch-panels/#filtering-patch-panel-ports","title":"Filtering Patch Panel Ports","text":"Quite often, all you are looking for is a free in a particular location (data centre) or cabinet of a particular cable type (UTP / SMF / etc.).
IXP Manager makes this easy from the Patch Panels page via the top right button labeled Filter Options. When clicked, this yields an advanced search as follows:
Cabinets auto-fills when you chose (or change) a location.
"},{"location":"features/patch-panels/#patch-panel-port-states","title":"Patch Panel Port States","text":"A patch panel port can have the following states:
IXP Manager will colour ports in the Available, Prewired and Awaiting Cease states are green allowing an easy visual indication of available ports.
"},{"location":"features/patch-panels/#patch-panel-port-lifecycle","title":"Patch Panel Port Lifecycle","text":"Patch panel ports start as either available or prewired. The context menu in these states is:
The main lifecycle option here is Allocate:
Description: A one line short description to be shown in the list of patch panel ports. Just enough to help explain the ports purpose. Detailed information should be placed in the notes section. Can also be used to explain a reserved / broken / other port. Note that this is parsed as Markdown. NB: A description is discouraged for customer ports connected to a switch. The customer name and switch port are the description.
Colocation Circuit Reference: this is the reference provided by the colocation provider to uniquely reference this cross connect.
Ticket Reference(s): This is a free text field to be used by IXPs as they wish. The intended use is to enter helpdesk ticket references that relate to this cross connect order.
Duplex connection?: Clicking this allows you to select the slave port for duplex connections.
Switch / Switch Port / Customer: You have a number of options when allocating a port:
If the port is pre-wired then the switch / switch port will be set here.
If you need to reset these fields, just click either of the Reset button.
Patch Panel Port Status: when allocating a port, this will allow you to set the state to Awaiting Xconnect or Connected.
Physical Interface Status: this is not depicted above. If the selected switch port has already been assigned to a customer by way of a physical interface, you will have the option to update this here also.
Public and Private Notes: Public notes are available to the customer. Both fields are interpreted as Markdown.
Chargeable: Usually IXPs request their members to come to them and bear the costs of that. However, sometimes a co-location facility may charge the IXP for a half circuit or the IXP may need order and pay for the connection. The options are Yes / No / Half / Other. How individual IXPs use this is up to them.
Internal Use: Marks the port as used by the IXP itself. E.g. metro connections.
Owned By: Useful indication for billing and cease requests. Should represent the contractural owner of the cross connect. One of: Customer, IXP, Service Provider, Data Centre, Other. Service Provider might be a metro provider where they ordered the cross connect.
Once a port is allocated, it enters the Awaiting XConnect / Connected state and there are additional context menu options available:
The three lifecycle actions are:
Over the lifetime of a cross connect - and particularly when it is being ordered, there may be files exchanges between you and your customers or the colocation provider. These can be added to the patch panel port via the Attach File... option.
The dialog will dynamically determine the maximum file upload size based on your PHP settings. To alter this, change the following in your server's appropriate php.ini:
; Maximum allowed size for uploaded files.\nupload_max_filesize = 40M\n\n; Must be greater than or equal to upload_max_filesize\npost_max_size = 40M\nPlease search the internet for further help as this is outside the scope of IXP Manager documentation.
The following features apply to file attachments:
$IXPROOT/storage/files/ppp.Many co-location providers will not accept a cross connect order without a LoA (Letter of Agency/Authority) from the party to whom the cross connect is to be delivered (typically the IXP).
IXP Manager will generate a PDF LoA to download or include in the emails it generates for you. Here is an example:
You will need to skin this yourself to change the legalese, address and contact details and potentially add a logo. See the version INEX uses here (which includes and embedded PNG logo).
Note that Dompdf is used to turn the HTML template into a PDF and it has some restrictions.
You have two options for generating LoAs (without having IXP Manager email them):
The stock LoA template (and INEX's version) includes a link that allows co-location browsers to click on to verify its veracity.
On successful verification, the end user sees:
"},{"location":"features/patch-panels/#email-generation","title":"Email Generation","text":"IXP Manager allows you to send four emails related to patch panels / cross connects (port status dependent). These are listed below. The Email editor looks as follows:
Note that:
The four email templates available are:
All email templates can be skinned for your own needs. See INEX's example skins here.
"},{"location":"features/patch-panels/#viewing-patch-panel-details-and-archives","title":"Viewing Patch Panel Details and Archives","text":"Each patch panel port row has the following button:
The number in the badge indicates how many historical records are available.
Clicking on the button yields the following view screen:
"},{"location":"features/patch-panels/#development-history","title":"Development History","text":"The Patch Panels functionality was developed during Q1 2017 and added in March 2017. This was made possible from sponsorship which enabled us to hire a new full time developer. We are especially grateful to our sponsors - please see them here.
"},{"location":"features/peering-manager/","title":"Peering Manager","text":"The Peering Manager is a fantastic tool that allows your members to view and track their peerings with other IXP members. The display is broken into four tabs for each member:
The mechanism for detecting bilateral peers is by by observing established TCP sessions between member peering IP addresses on port 179 using [sflow](sflow.md]. See the peering matrix documentation as setting up the peering matrix will provide all the data needed for the peering manager.
NB: You must check the Peering Manager option when editing VLANs for that VLAN to be included in the peering manager.
The features of the peering manager include:
This feature requires some settings in your .env which you may have already set:
;; the various identity settings\nIDENTITY_...\n\n;; the default VLAN's database ID (get this from the DB ID column in VLANs)\nIDENTITY_DEFAULT_VLAN=1\nThe default peering request email template can be found at resources/views/peering-manager/peering-message.foil.php. You can skin this if you wish but it is generic enough to use as is.
You can disable the peering manager by setting the following in .env:
IXP_FE_FRONTEND_DISABLED_PEERING_MANAGER=true\nFor testing / experimentation purposes, you can enable a test mode which, when enabled, will send all peering requests to the defined test email.
To enable test mode, just set the following in .env:
PEERING_MANAGER_TESTMODE=true\nPEERING_MANAGER_TESTEMAIL=user@example.com\nWhen test mode is enabled, there will be a clear alert displayed at the top of the peering manager page.
Normally, the peering manager adds a note to the peer's notes and sets a request last sent date when a peering request is sent. In test mode, this will not happen. If you want this to happen in test mode, set these to true:
PEERING_MANAGER_TESTNOTE=true\nPEERING_MANAGER_TESTDATE=true\nThe peering matrix system builds up a list of who is peering with whom over your IXP.
There are two primary data sources: route server clients and sflow. Currently, it is assumed that all IXP participants who connect to the route server have an open peering policy and do not filter prefixes.
NB: You must check the Peering Matrix option when editing VLANs for that VLAN to be included in the peering matrix on the frontend.
"},{"location":"features/peering-matrix/#data-source-route-server-clients","title":"Data Source: Route Server Clients","text":"Route server clients are automatically shown as peering with each other onm the peering matrix. No operator input is required for this.
"},{"location":"features/peering-matrix/#data-source-sflow-bgp-session-detection","title":"Data Source: sflow BGP session detection","text":"IXP Manager can pick out active BGP sessions from an sflow data feed. This is handled using the sflow-detect-ixp-bgp-sessions script. As this is a perl script, it is necessary to install all the perl modules listed in the check-perl-dependencies.pl script.
Sflow is a packet sampling mechanism, which means that it will take some while before the peering database is populated. After 24 hours of operation, the peering database should be relatively complete.
sflow-detect-ixp-bgp-sessions needs its own dedicated sflow data feed, so it is necessary to set up sflow data fan-out using the sflowtool as described in the sflow fan-out section here. INEX normally uses udp port 5501 for its bgp detection sflow feed.
For more information, see the sflow documentation.
Note that the peering matrix functionality depends on SQL triggers which are maintained in the tools/sql/views.sql file. This can be refreshed using the following command:
```sh\nmysql -u ixp -p ixp < $IXPROOT/tools/sql/views.sql\n```\nIn addition to the correct SQL configuration for the <sql> section, sflow-detect-ixp-bgp-sessions needs the following options set in the <ixp> section of ixpmanager.conf:
sflowtool: the location of the sflowtool binary.sflowtool_bgp_opts: command line arguments for sflowtool.<ixp>\n # location of sflow executable\n sflowtool = /usr/local/bin/sflowtool\n\n # sflow listener to p2p rrd exporter, listening on udp port 5500\n sflowtool_opts = -4 -p 5500 -l\n\n # sflow listener for BGP peering matrix, listening on udp port 5501\n sflowtool_bgp_opts = -4 -p 5501 -l\n</ixp>\nThe system can be tested using sflow-detect-ixp-bgp-sessions --debug. If it starts up correctly, the script should occasionally print out peering sessions like this:
DEBUG: [2001:db8::ff]:64979 - [2001:db8::7]:179 tcpflags 000010000: ack. database updated.\nDEBUG: [192.0.2.126]:30502 - [192.0.2.44]:179 tcpflags 000010000: ack. database updated.\nDEBUG: [2001:db8::5:0:1]:179 - [2001:db8::4:0:2]:32952 tcpflags 000011000: ack psh. database updated.\nThe script control-sflow-detect-ixp-bgp-sessions should be copied (and edited if necessary) to the operating system startup directory so that sflow-detect-ixp-bgp-sessions is started as a normal daemon.
The peering matrix is publicly available by default. However you can limit access to a minimum user privilege by setting PEERING_MATRIX_MIN_AUTH to an integer from 0 to 3 in your .env. See here for what these integers mean. For example, to limit access to any logged in user, set the following:
PEERING_MATRIX_MIN_AUTH=1\nYou can disable the peering matrix by setting the following in .env:
IXP_FE_FRONTEND_DISABLED_PEERING_MATRIX=true\nThis probably means that it's not getting an sflow feed. Check to ensure that sflowtool is feeding the script correctly by using the sflow-detect-ixp-bgp-sessions --insanedebug. This should print out what the script is reading from sflowtool. Under normal circumstances, this will be very noisy.
ignored - no address match in database when in debug modeIf the IP addresses match those on the IXP's peering LAN, then the IP address database is not populated correctly. This can be fixed by entering the IXP's addresses in the IP Addressing menu of the web UI.
Check that the tools/sql/views.sql file has been imported into the SQL database.
IXP Manager can authenticate users via their PeeringDB account and affiliations (from V5.2.0). This is hugely beneficial for your customers who are members of multiple IXPs which use IXP Manager - it means they only need their PeeringDB account to access their portal at each of those IXs.
NB: this feature is not set up by default as it requires some configuration on both PeeringDB and your IXP Manager installation.
"},{"location":"features/peeringdb-oauth/#security","title":"Security","text":"Is there a security risk?
Well, we at INEX do not think so and we have developed and enabled this feature for our members.
By enabling PeeringDB OAuth, you are creating a path that delegates authentication and authorization of users on your platform to PeeringDB. This is not a decision that was rushed into. It is particularly notable that PeeringDB is the industry-standard database for network operators and the PeeringDB team take the job of assessing whether someone should be affiliated with a network seriously.
We at INEX also discussed this functionality with a wide variety of people in our industry and the opinion was overwhelmingly in favor with no known dissenters.
Lastly, we have developed this in a security-conscious way. New users get read-only access by default. All information from PeeringDB is validated and a number of other confirmatory steps are taken. You can read all about this in the OAuth User Creation section below.
"},{"location":"features/peeringdb-oauth/#configuring-peeringdb-for-oauth","title":"Configuring PeeringDB for OAuth","text":"There are two steps to configuring OAuth for PeeringDB - first set it up on PeeringDB and then, using the tokens generated there, configure IXP Manager.
"},{"location":"features/peeringdb-oauth/#configuring-peeringdb","title":"Configuring PeeringDB","text":"The first step is to create your IXP Manager OAuth application through your PeeringDB account:
/auth/login/peeringdb/callback action on your IXP Manager installation. For example, if the base URL of your IXP Manager installation is https://www.example.com then set redirect URL to https://www.example.com/auth/login/peeringdb/callback. Note that for OAuth, it is mandatory to use https:// (encryption).Here is a sample form on PeeringDB:
"},{"location":"features/peeringdb-oauth/#configuring-ixp-manager","title":"Configuring IXP Manager","text":"To enable OAuth with PeeringDB on IXP Manager, set the following options in your .env file:
AUTH_PEERINGDB_ENABLED=true\n\nPEERINGDB_OAUTH_CLIENT_ID=\"xxx\"\nPEERINGDB_OAUTH_CLIENT_SECRET=\"xxx\"\nPEERINGDB_OAUTH_REDIRECT=\"https://www.example.com/auth/login/peeringdb/callback\"\nwhile replacing the configuration values for the those from the PeeringDB set-up above.
Once this is complete, you'll find a new option on IXP Manager's login form:
By default, new users are created on IXP Manager as read-only customer users. You can change this to read-write customer admin users by additionally setting the following option:
AUTH_PEERINGDB_PRIVS=2\nIf PeeringDB OAuth is configured and enabled (AUTH_PEERINGDB_ENABLED=true) then it is enabled for all customers. However you may encounter a customer who does not want OAuth access enabled on their account. In this situation, IXP Manager allows you to disabled OAuth on a per-customer basis when adding or editing customers.
Just uncheck the following option on the add / edit customer page:
"},{"location":"features/peeringdb-oauth/#oauth-user-creation","title":"OAuth User Creation","text":"When IXP Manager receives an OAuth login request from PeeringDB, it goes through a number of validation, creation and deletion steps:
unknownpdbuser) using s/[^a-z0-9\\._\\-]/./ with an incrementing integer concatenated as necessary for uniqueness.user.peeringdb_id set to PeeringDB's user ID.user.creator set to OAuth-PeeringDB.If AUTH_PEERINGDB_ENABLED is enabled in your .env, you will see a column called OAuth in the Users list table (accessed via the left hand side menu). This will indicate if the user was created by OAuth (Y) or not (N).
When viewing a user's details (eye button on the users list), it will show how the user was created and also how the user was affiliated with a particular customer. The same is also shown when editing users.
"},{"location":"features/peeringdb-oauth/#historical-notes","title":"Historical Notes","text":"PeeringDB OAuth with IXP Manager as an idea dates from early 2017 when Job Snijders proposed it in GitHub issue peeringdb/peeringdb#131. We recognized the benefits immediately and opened a parallel ticket at inex/IXP-Manager#322. The background discussions at this point were that PeeringDB would be prepared to invest developer time if IXP Manager committed to implementing it. We both did.
PeeringDB's OAuth documentation can be found here.
As part of the development process, we wrote a provider for the Laravel Socialite package which was merged into that package via the SocialiteProviders/Providers#310 pull request.
"},{"location":"features/peeringdb-oauth/#development-notes","title":"Development Notes","text":"Testing in development needs to be setup following the instructions above. While PeeringDB has a beta site, the actual OAuth URL is hard coded into Socialite. You can test against production or edit the two URLs in this file: data/SocialiteProviders/src/PeeringDB/Provider.php.
For local testing, you'll need both SSL and a way for PeeringDB to redirect back to you. valet share from Laravel Valet is perfect for this.
PeeringDB is a freely available, user-maintained, database of networks and interconnection data. The database facilitates the global interconnection of networks at Internet Exchange Points (IXPs), data centers, and other interconnection facilities. The database is a non-profit, community-driven initiative run and promoted by volunteers. It is a public tool for the growth and good of the internet.
IXP Manager uses PeeringDB in a number of current (and planned) ways.
"},{"location":"features/peeringdb/#oauth-user-authentication","title":"OAuth - User Authentication","text":"IXP Manager can authenticate users via their PeeringDB account and affiliations. Please see this page for full details and instructions.
"},{"location":"features/peeringdb/#population-of-data-when-adding-customers","title":"Population of Data When Adding Customers","text":"Much of the information required to add new customers to IXP Manager can be prepopulated from PeeringDB by entering the customer's ASN into the box provided on the add customer page:
For maximum benefit, you should configure a user on PeeringDB for your IXP Manager installation and set these details in the .env file:
#######################################################################################\n# PeeringDB Authentication\n#\n# PeeringDb's API is used, for example, to pre-populate new customer details. If you\n# provide a working PeeringDb username/password then these will be used to get more\n# complete information.\n#\nIXP_API_PEERING_DB_USERNAME=username\nIXP_API_PEERING_DB_PASSWORD=password\nPeeringDB can take data from your IXP Manager installation via the IX-F Export schema that is part of IXP Manager. PeeringDB requires two things for this to work:
First, you need to add your IX-F Export URL to your PeeringDB IX LAN entry:
Secondly, and unfortunately, each individual network must opt in to having their data updated by this mechanism (data meaning connection to the exchange, peering IPs and port speeds). They do this via this option on their network page:
"},{"location":"features/peeringdb/#asn-detail","title":"ASN Detail","text":"In most places in IXP Manager, you can click on an ASN number. This uses PeeringDB's whois service to provide a quick view of that network's PeeringDB record.
Here's a squashed screen shot just to illustrate the feature:
"},{"location":"features/peeringdb/#existence-of-peeringdb-records","title":"Existence of PeeringDB Records","text":"On the customer overview page from IXP Manager v5.0, we provide an indication (yes/no) as to whether a customer has a PeeringDB record. Generally it is important for IXPs to encourage their members to create PeeringDB entries to ensure your IXP is properly represented on their database.
Whether a customer has a PeeringDB entry is updated daily via the cronjobs.md. If you want to run it manually, run this Artisan command:
$ php artisan ixp-manager:update-in-peeringdb -vv\nPeeringDB membership updated - before/after/missing: 92/92/17\nAs you'll see from the output, it will show you the results. We will provide more tooling within IXP Manager to show this information in time.
"},{"location":"features/peeringdb/#facilities","title":"Facilities","text":"When you add facilities (locations / points of presence / data centers) to IXP Manager, it pulls a list of known facilities from PeeringDB. You should select the correct one from the list (or add a missing one to PeeringDB) when you add/edit your facilities.
Note that this list is cached for two hours.
"},{"location":"features/peeringdb/#infrastructures-and-peeringdb-ixp-entry","title":"Infrastructures and PeeringDB IXP Entry","text":"Similarly to adding facilities above, when you add an infrastructure (IXP) to IXP Manager, it pulls a list of known IXPs from PeeringDB. You should select the correct one from the list (or add a missing one to PeeringDB) when you add/edit your infrastructures.
Note that this list is cached for two hours.
"},{"location":"features/provisioning/","title":"Automated Provisioning","text":""},{"location":"features/provisioning/#introduction","title":"Introduction","text":"At INEX, we have been using IXP Manager for automated provisioning of our peering platform since 2017. We have published all the provisioning templates we use in production here.
InfoYou are welcome to have a look at what's here and contribute feedback via the issues page or the ixpmanager mailing list. Having said that, provisioning is complicated and very specific to individual IXPs. Even if your IXP is running with the same two network operating systems that are in this repo, it is unlikely that people have the resources freely available to be able to make this work for you.
This page has two sections:
The templates INEX has published at the above link provide configuration support for Arista EOS and Cumulus Linux 3.4+/4.0+ devices using SaltStack.
The Arista EOS implementation uses NAPALM and can be easily modified for any other operating system which supports either NAPALM or netmiko.
The Cumulus Linux template implementation uses native SaltStack support, and treats the Cumulus Linux switch like any other Linux device. For an IXP, you need CL >= 3.4.2.
At the bare minimum, in order to make these work, you will need to be completely fluent with NAPALM and advanced use of SaltStack, including how to configure and maintain salt proxies. If you have multiple IXP configurations (e.g. live / test environments), you will also need to be fluent with the idea of multiple salt environments.
A good starting point would be Mircea Ulinic's guides for integrating SaltStack and NAPALM. For a bigger-picture overview about how these templates hang together, we've done some presentations - see the 2017 and 2018 talks on automation on the IXP Manager website.
Note that there is no information in these presentations about the nitty gritty of getting all this stuff to work. The Apricot 2018 presentation involves lots of cheery handwaving and high level overview stuff, but very little detail other than some sample command-lines that we use.
In 2023/4 we hope to design a workshop / tutorial videos on this topic.
"},{"location":"features/provisioning/#api-endpoints","title":"API Endpoints","text":"The API endpoints documented below should provide everything you need to provision all aspects of an IXP fabric.
https://ixp.example.com/). {switchname} should be replaced with the name of your switch as entered in IXP Manager..yaml in the examples but you should be able to replace this with .json also.The INEX sample templates we reference below will get their dynamic information from two sources:
/api/v4/provisioner/switch/switch-name/{$switchname}.yamlSample output:
switch:\n name: swi1-exp1-1\n asn: 65000\n hostname: swi1-exp1-1.mgmt.example.com\n loopback_ip: 192.0.2.1\n loopback_name: Loopback0\n ipv4addr: 192.0.2.100\n model: DCS-7280SR-48C6\n active: true\n os: EOS\n id: 72\n macaddress: 11:22:33:44:55:66\n lastpolled: \"2023-04-21T09:31:11+01:00\"\n osversion: 4.25.4M\n snmpcommunity: supersecret\nAll of this data comes from the switch settings in IXP Manager. The ipv4addr is the management address.
As well as the base configuration shown the the template about, this information could also be used to provision:
/api/v4/provisioner/layer3interfaces/switch-name/{$switchname}.yamlSample output:
layer3interfaces:\n- ipv4: 192.0.2.21/31\n description: 'LAN1: swi1-exp1-3 - swi1-exp1-1'\n bfd: true\n speed: 100000\n name: Ethernet51/1\n autoneg: true\n shutdown: false\n- ipv4: 192.0.2.33/31\n description: 'LAN1: swi1-exp2-3 - swi1-exp1-1'\n bfd: true\n speed: 100000\n name: Ethernet53/1\n autoneg: true\n shutdown: false\n- description: Loopback interface\n loopback: true\n ipv4: 192.0.2.1/32\n name: Loopback0\n shutdown: false\nThis API is used to set up the basic layer3 interface elements that are required in future stages to create a VXLAN overlay. The data comes from two sources on IXP Manager:
/api/v4/provisioner/vlans/switch-name/{$switchname}.yamlSample output:
vlans:\n- name: IXP LAN1\n tag: 10\n private: false\n config_name: vl_peeringlan1\n- name: Quarantine LAN1\n tag: 11\n private: false\n config_name: vl_quarantinelan1\n- name: VoIP Peering LAN1\n tag: 12\n private: false\n config_name: VOIPPeeringLAN1\nThis information comes from the VLAN configuration on IXP Manager. The INEX sample template also configures VXLAN with this information.
"},{"location":"features/provisioning/#layer2-interfaces","title":"Layer2 Interfaces","text":"InfoDespite the template being called cust interfaces, this API endpoint is for both customer interfaces and layer2 core interfaces.
/api/v4/provisioner/layer2interfaces/switch-name/{$switchname}.yamlSample output:
layer2interfaces:\n- type: edge\n description: Sample Member - No LAG\n dot1q: false\n virtualinterfaceid: 26\n lagframing: false\n vlans:\n - number: 10\n macaddresses:\n - 22:33:44:55:66:77\n ipaddresses:\n ipv4: 198.51.100.23\n ipv6: 2001:db8::23\n shutdown: false\n status: connected\n name: \"1:3\"\n speed: 10000\n autoneg: true\n- type: edge\n description: Sample Member - LAG\n dot1q: false\n virtualinterfaceid: 251\n lagframing: true\n lagindex: 3\n vlans:\n - number: 10\n macaddresses:\n - 33:44:55:66:77:88\n ipaddresses:\n ipv4: 198.51.100.108\n ipv6: 2001:db8::108\n name: Port-Channel3\n lagmaster: true\n fastlacp: false\n lagmembers:\n - Ethernet5\n - Ethernet6\n shutdown: false\n status: connected\n- type: edge\n description: Sample Member - LAG\n dot1q: false\n virtualinterfaceid: 251\n lagframing: true\n lagindex: 3\n vlans:\n - number: 10\n macaddresses:\n - 33:44:55:66:77:88\n ipaddresses:\n ipv4: 198.51.100.108\n ipv6: 2001:db8::108\n name: Ethernet5\n lagmaster: false\n fastlacp: false\n shutdown: false\n status: connected\n autoneg: true\n speed: 10000\n rate_limit: ~\n- type: edge\n description: Sample Member - LAG\n dot1q: false\n virtualinterfaceid: 251\n lagframing: true\n lagindex: 3\n vlans:\n - number: 10\n macaddresses:\n - 33:44:55:66:77:88\n ipaddresses:\n ipv4: 198.51.100.108\n ipv6: 2001:db8::108\n name: Ethernet6\n lagmaster: false\n fastlacp: false\n shutdown: false\n status: connected\n autoneg: true\n speed: 10000\n rate_limit: ~\n- type: core\n description: 'LAN1: swi1-exp2-3 to swi1-exp1-1 - Sample Core L2 Link'\n dot1q: true\n stp: false\n cost: ~\n preference: ~\n virtualinterfaceid: 439\n corebundleid: 30\n lagframing: true\n lagindex: 1000\n vlans:\n - number: 10\n macaddresses: []\n - number: 11\n macaddresses: []\n - number: 12\n macaddresses: []\n name: Port-Channel1000\n lagmaster: true\n fastlacp: true\n lagmembers:\n - \"Ethernet48\"\n shutdown: false\n- type: core\n description: 'LAN1: swi1-exp2-3 to swi1-exp1-1 - Sample Core L2 Link'\n dot1q: true\n stp: false\n cost: ~\n preference: ~\n virtualinterfaceid: 439\n corebundleid: 30\n lagframing: true\n lagindex: 1000\n vlans:\n - number: 10\n macaddresses: []\n - number: 11\n macaddresses: []\n - number: 12\n macaddresses: []\n name: \"Ethernet48\"\n lagmaster: false\n fastlacp: true\n shutdown: false\n autoneg: true\n speed: 40000\nThe data comes from two sources on IXP Manager:
/api/v4/provisioner/routing/switch-name/{$switchname}.yamlSample output:
bgp:\n floodlist:\n - 192.0.2.2\n - 192.0.2.12\n - 192.0.2.10\n - 192.0.2.11\n - 192.0.2.40\n - 192.0.2.20\n - 192.0.2.0\n - 192.0.2.60\n - 192.0.2.22\n - 192.0.2.82\n - 192.0.2.23\n - 192.0.2.42\n - 192.0.2.15\n - 192.0.2.16\n - 192.0.2.17\n - 192.0.2.18\n adjacentasns:\n 65082:\n description: swi1-exp1-3\n asn: 65082\n cost: 100\n preference: ~\n 65002:\n description: swi1-exp2-3\n asn: 65002\n cost: 850\n preference: ~\n routerid: 192.0.2.1\n local_as: 65000\n out:\n pg-ebgp-ipv4-ixp:\n neighbors:\n 192.0.2.120:\n description: swi1-exp1-3\n remote_as: 65082\n cost: 100\n preference: ~\n 192.0.2.132:\n description: swi1-exp2-3\n remote_as: 65002\n cost: 850\n preference: ~\nThis completes the layer2 underlay for VXLAN. The sources of information for this are the switches and core bundles in IXP Manager.
"},{"location":"features/reseller/","title":"Reseller Functionality","text":"Reseller mode must be explicitly enabled with a .env option:
IXP_RESELLER_ENABLED=true\nIn our model, a resold member is still a fully fledged member, they just happen to reach the exchange via someone else's network. You / we would still have a relationship with the member independent of the reseller and would still be required to carry out the standard turn up (for us, this includes IP assignment, quarantine procedures, route collector session, route server sessions if appropriate, etc.).
IXP Manager's functionality is simply to:
For resellers, we need to enforce the one port - one mac - one address rule on the peering LAN.
Depending on switch technology, this can be done using
Currently the schema cannot adequately handle a virtual ethernet port.
Typically, we'd assign a dedicated switch (or bunch of switch ports) as a fanout switch with a reseller uplink port (or LAG). The reseller delivers their customer traffic in dedicated VLANs over this uplink port. We then break each individual customer's traffic into dedicated fanout ports. These physical fanout ports have a one to one relationship with peering ports for that customer (these can be single physical ports or LAGs).
The reseller functionality includes:
The following are set in .env:
To enable reseller functionality, set the following to true:
IXP_RESELLER_ENABLED=false\nIf your resold customers are billed directly by the reseller and not the IXP, set this to true to remove billing details from their admin and member areas.
IXP_RESELLER_RESOLD_BILLING=false\nIn the (older Zend Framework) controllers, you can execute reseller code via:
if( $this->resellerMode() ) {\n // your reseller specific code here\n}\nAnd in (the older Zend Framework) Smarty templates, you can add reseller only content via:
{if $resellerMode}\n <!-- Your reseller content -->\n{/if}\nIf you have a $customer entity, you can see if it is a reseller via:
if( $customer->isReseller() ) {}\nTo see if a customer is a resold customer or get the reseller customer entity:
if( $customer->getReseller() ) {} // returns false if not a resold customer\nFinally, to get all resold customer entities of a reseller:
$customer->getResoldCustomers()\nReseller functionality was added jointly by INEX and LONAP in June 2013.
"},{"location":"features/rir-objects/","title":"RIR Objects","text":"IXP Manager can generate (and email) your RIR objects - for example your AS-SETs, AS object, etc - to your RIR for automatic updates / maintenance.
As a concrete example of this, see how INEX do this with our RIPE objects as follows:
Some RIRs, such as RIPE, has a facility to update these objects by email.
"},{"location":"features/rir-objects/#configuration","title":"Configuration","text":"The general form of the Artisan command is:
$ php artisan rir:generate-object --send-email \\\n --to=test-dbm@ripe.net \\\n --from me@example.com autnum\nYou can see the options by using the standard -h help switch with Artisan:
$ php artisan rir:generate-object -h\nUsage:\n rir:generate-object [options] [--] <object>\n\nArguments:\n object The RIR object template to use\n\nOptions:\n --send-email Rather than printing to screen, sends and email for updating a RIR automatically\n --force Send email even if it matches the cached version\n --to[=TO] The email address to send the object to (if not specified then uses IXP_API_RIR_EMAIL_TO)\n --from[=FROM] The email address from which the email is sent (if not specified, tries IXP_API_RIR_EMAIL_FROM and then defaults to IDENTITY_EMAIL)\n -h, --help Display this help message\n -q, --quiet Do not output any message\n\nHelp:\n This command will generate and display a RIR object (and optionally send by email)\nYou will note that without the --send-email switch, the command will print to standard output allowing you to consume the object and use it on another way.
NB: the generated object is stored in the cache when it is generated with --send-email for the first time. Future runs with --send-email will only resend the email if the generated object differs from the cached version. You can force an email to be sent with --force. Secondly, the cache used is a file system based cache irrespective of the CACHE_DRIVER .env settings. To wipe it, run: artisan cache:clear file.
The following options are available for use in the .env file:
#######################################################################################\n# Options for updating RIR Objects - see https://docs.ixpmanager.org/features/rir-objects/\n\n# Your RIR password to allow the updating of a RIR object by email:\nIXP_API_RIR_PASSWORD=soopersecret\n\n# Rather than specifying the destination address on the command line, you can set it here\n# (useful for cronjobs and required for use with artisan schedule:run in >=v5.0)\nIXP_API_RIR_EMAIL_TO=test-dbm@ripe.net\n\n# Rather than specifying the from address on the command line, you can set it here\n# (useful for cronjobs and required for use with artisan schedule:run in >=v5.0)\nIXP_API_RIR_EMAIL_FROM=ixp@example.com\nThere are a number of predefined objects available under resources/views/api/v4/rir and skinning is the recommended way to add / edit these objects.
You can copy an existing template or create a new one. For example, if you wanted a template called my-as-set, you would create it under resources/skins/example/api/v4/rir/my-as-set.foil.php and then specify it to the Artisan command as:
$ php artisan rir:generate-object my-as-set\nThe template name must be lowercase, and contain only the characters: 0-9 a-z _ -.
$customers - complete Doctrine2 objects of all current external trafficking customers / members. You should be able to derive everything from this. Indexed by customer ID.$asns - an associative array for the generation of an IXP AS object indexed by ASN containing elements:['asmacro'] - the member's AS macro (or the ASN if no macro);['name'] - the member's name$rsclients - an associative array for the generation of an IXP's route server AS object. See the function definition for generateRouteServerClientDetails() in app/Tasks/Rir/Generator.php for details on the array structure.You'll find a standard template for an autnum: object at resources/views/api/v4/rir/autnum.foil.php; as well as INEX's own versions under resources/skins/inex/api/v4/rir/autnum-as2128.foil.phpandautnum-as43760.foil.php` for the IXP route collector and and route servers respectively.
Just copy one of these to your own skin directory and edit as appropriate.
"},{"location":"features/rir-objects/#as-set-connected-asns","title":"as-set: - Connected ASNs","text":"You can create an AS-SET of connected ASNs / AS macros (see INEX's AS-SET-INEX-CONNECTED as an example) via the example template as-set-ixp-connected.
You can create an AS-SET of ASNs / AS macros connected to the route servers (see AS-SET-INEX-RS as an example) via the example template as-set-ixp-rs.
There's also templates for v4 and v6 only versions: as-set-ixp-rs-v4 and as-set-ixp-rs-v6.
Prerequisite Reading: Ensure you first familiarize yourself with the generic documentation on managing and generating router configurations here.
Route collectors are an important member setup, diagnostic and metric tool for IXPs. Route collectors accept all routes and advertise none. IXP Manager will generate route collector configuration for you. You can see an example of this generated configuration here.
At INEX we use the Bird BGP daemon as our collector using the stock configuration as generated by IXP Manager. We also use this same setup for the quarantine LAN collectors. You can see our live looking glasses here for more information.
"},{"location":"features/route-collectors/#setting-up","title":"Setting Up","text":"You first need to add your route collector(s) to the IXP Manager routers database. See this page on how to do that.
Typically an IXP's route collector service will share the ASN of the IXP's own management network (but be different to the route server entry). You should also add the route collectors to your initial internal customer representing your IXP on to IXP Manager. Here's INEX's example from our peering LAN1 in Dublin:
"},{"location":"features/route-collectors/#other-information","title":"Other Information","text":""},{"location":"features/route-collectors/#quarantine","title":"Quarantine","text":"We also use a quarantine route collector when provisioning new member connections. This is a Bird BGP daemon running on a virtual machine on our quarantine LAN. For is, this quarantine LAN is:
When adding routers to IXP Manager, setting the quarantine flag means that the configuration will only contain interfaces that are on the quarantine VLAN.
"},{"location":"features/route-servers/","title":"Route Servers","text":"Prerequisite Reading: Ensure you first familiarize yourself with the generic documentation on managing and generating router configurations here.
Normally on a peering exchange, all connected parties will establish bilateral peering relationships with each other customer connected to the exchange. As the number of connected parties increases, it becomes increasingly more difficult to manage peering relationships with customers of the exchange. A typical peering exchange full-mesh eBGP configuration might look something similar to the diagram on the left hand side.
The full-mesh BGP session relationship scenario requires that each BGP speaker configure and manage BGP sessions to every other BGP speaker on the exchange. In this example, a full-mesh setup requires 7 BGP sessions per member router, and this increases every time a new member connects to the exchange.
However, by using a route servers for peering relationships, the number of BGP sessions per router stays at two: one for each route server (assuming a resilient set up). Clearly this is a more sustainable way of maintaining IXP peering relationships with a large number of participants.
"},{"location":"features/route-servers/#configuration-generation-features","title":"Configuration Generation Features","text":"Please review the generic router documentation to learn how to automatically generate route server configurations. This section goes into a bit more specific detail on INEX's route server configuration (as shipped with IXP Manager) and why it's safe to use.
You should also look at the following resources:
The features of the route server configurations that IXP Manager generates include:
With Bird v2 support in IXP Manager >= v5, we provide better looking glass integration and other tooling to show members which prefixes are filtered and why.
"},{"location":"features/route-servers/#filtering-algorithm","title":"Filtering Algorithm","text":"The Bird v2 filtering algorithm is as follows:
If a route fails at any point it is tagged (for looking glass) and rejected.
"},{"location":"features/route-servers/#setting-up","title":"Setting Up","text":"You first need to add your route servers to the IXP Manager routers database. See this page on how to do that.
Typically an IXP's route server service will have a dedicated ASN that is different to the IXP's own management / route collector ASN. As such, you need to add a new internal customer to IXP Manager.
WarningYou are strongly advised to use / request a dedicated 16-bit ASN from your RIR for route server use and in our experience, all RIRs understand this and accomodate it. The route server configurations will support an asn32 but to our knowledge, this has never been used in production. Also, withouot an asn16, you will be unable to offer your members standard community based filtering.
Here's an example from INEX for our route server #1:
You then need to create an interface for this route server on each peering LAN where the service will be offered. Here again is INEX's example from our peering LAN1 in Dublin:
There's a couple things to note in the above:
There are occasions where you may need to override the default filtering mechanism for some members. IXP Manager allows you to create custom Bird2 checks at the start of the standard import / export filters when using Bird2 (not supported on the older Bird v1 configuration).
To do this, you must create skinned files named after the ASN. For example, let's assume your skin name is example and the ASN of the member you want to apply custom filtering to is 64511; then you would an export and/or import filter in files named:
$IXPROOT/resources/skins/example/api/v4/router/server/bird2/f_import_as64511.foil.php$IXPROOT/resources/skins/example/api/v4/router/server/bird2/f_export_as64511.foil.phpYou'll see real examples from INEX here. Remember that these are placed at the beginning of the standard filters allowing you to explicitly accept or reject the prefix. However, remember that INEX accepts prefixes on import always but tags prefixes for filtering with large community routerasn:1101:x - please see the resources referenced above for details on this.
Using Bird v2 and internal large communities, we have completely overhauled how we show end users what prefixes are filtered by the route servers.
If you are running route servers using the Bird v2 configuration and if you have installed the looking glass then you should set the following in your .env file:
IXP_FE_FRONTEND_DISABLED_FILTERED_PREFIXES=false\nThis is a live view gathered from each Bird v2 route server with a looking glass.
Please see our presentations from 2019 for more information on this. Particularly the UKNOF one from September 2019 would be the most up to date.
For a route server to be polled for a customer by this tool, the following conditions must be met:
It is also critical that the looking glass for the route server works.
Caching: for large members with tens of thousands of routes, gathering filtered prefixes can be an expensive task for IXP Manager and the route server (expensive in terms of time and CPU cycles). As such, this feature of IXP Manager requires the use of a persistent cache. We recommend memcached for this which is installed and enabled by default with the automated installer.
"},{"location":"features/route-servers/#well-known-filtering-communities","title":"Well-Known Filtering Communities","text":"The route server configuration that IXP Manager generates by default provides well known communities to allow members to control the distribution of their prefixes.
NB: in the following, rs-asn is the AS number of the IXP's route server.
The standard communities are defined as follows:
Description Community Prevent announcement of a prefix to a peer0:peer-as Announce a route to a certain peer rs-asn:peer-as Prevent announcement of a prefix to all peers 0:rs-asn Announce a route to all peers rs-asn:rs-asn The community for announcing a route to all peers (rs-asn:rs-asn) is the default behaviour and so there is no need to tag routes with this.
Example #1: if a member wishes to instruct the IXP route server (with AS64500) to distribute a particular prefix only to AS64496 and AS64503, the prefix should be tagged with communities: 0:64500 64500:64496 64500:64503 (i.e. announce to no one except...).
Example #2: for a member to to announce a prefix to all IXP route server participants, excluding AS64497, the prefix should be tagged with only community 0:64497.
If you enabled support for BGP large communities, then the following large communities can be used:
Description Community Prevent announcement of a prefix to a peerrs-asn:0:peer-as Announce a route to a certain peer rs-asn:1:peer-as Prevent announcement of a prefix to all peers rs-asn:0:0 Announce a route to all peers rs-asn:1:0 If your route server is configured to support large communities, then you should advise your members to use these over standard 16-bit communities as a large number of networks now have a 32-bit ASN. You should also advise them not to mix standard 16-bit communities and large communities \u2013 please choose one or the other.
Lastly, with BGP large communities, AS path prepending control is also available by default using the following large BGP communities:
Description Community Prepend to peer AS oncers-asn:101:peer-as Prepend to peer AS twice rs-asn:102:peer-as Prepend to peer AS three times rs-asn:103:peer-as "},{"location":"features/route-servers/#rfc1997-passthru","title":"RFC1997 Passthru","text":"RFC1997 defines some well-known communities including NO_EXPORT (0xFFFFFF01 / 65535:65281) and NO_ADVERTISE and states that they have global significance and their operations shall be implemented in any community-attribute-aware BGP speaker.
According to RFC7947, it is a matter of local policy whether these well-known communities are interpreted or passed through. Historically, some IXP route servers interpret them and some pass them through. As such the behaviour of these well-known communities is not well-understood when it comes to route servers and this topic has been the subject of a good deal of debate in the IXP community over the years.
In 2017, INEX and LONAP published draft-hilliard-grow-no-export-via-rs-00 to try and create some consensus on this. While the draft was not accepted as a standard, the discussion drew a conclusion that these well-known communities should not be interpreted by the route server but passed through.
When creating a route server in IXP Manager, there is a checkbox option to control this behavior: Pass through RFC1997 well-known communities (recommended).
It is recommended that this be enabled on route servers.
"},{"location":"features/route-servers/#legacy-prefix-analysis-tool","title":"Legacy Prefix Analysis Tool","text":"The older but deprecated means of viewing filtered prefixes was the Route Server Prefix Analysis tool which allows your members to examine what routes they are advertising to the route servers, which are being accepted and which are being rejected.
"},{"location":"features/route-servers/#limitations-and-caveats","title":"Limitations and Caveats","text":"Implemented as a Perl script which accesses the database directly. The script can also only be used on one LAN and one route server. Thus, pick you most popular LAN and route server.
"},{"location":"features/route-servers/#setting-up_1","title":"Setting Up","text":"compare-route-server-prefixes.pl script and set the Bird configuration file and socket (you can find the position in the file by searching for XXX-SET-ME);compare-route-server-prefixes.pl script a few times a day as you think appropriate;.env file, ensure the following is set:IXP_FE_FRONTEND_DISABLED_RS_PREFIXES=false\nOnce you make the last change above, the prefix analysis tool will be available to administrators and members on IXP Manager.
"},{"location":"features/routers/","title":"Routers","text":"IXP Manager can generate router configuration for typical IXP services such as:
See the above pages for specific information on each of those use cases and below for instructions on how to generate configuration.
TipFor larger router configurations - especially when you have members with large prefix lists, you will need to increase PHP's memory_limit as the default of 128M will not be sufficient. Start with 512MB and watch the log (storage/logs/...) which reports the memory and time for configuration generation.
The basic elements of a router are configured in IXP Manager under the IXP Admin Actions - Routers option on the left hand menu.
When you goto add / edit a router, the green help button will provide explanatory details on each field of information required:
From the router management page, you can:
The simplest configuration to generate is the route collector configuration. A route collector is an IXP router which serves only to accept all routes and export no routes. It is used for problem diagnosis, to aid customer monitoring and for looking glasses (see INEX's here).
The original Bird v1 configuration simply pulls in a fairly standard header (sets up router ID, listening address and some filters) and creates a session for all customer routers on the given VLAN. The new Bird v2 configuration has more features and replicates the route server filtering mechanism but tags and accepts all routes for diagnosis.
When adding a router, you give it a handle. For example: rc1-lan1-ipv4 which, for INEX, would mean a route collector on peering LAN1 using IPv4. Then - for the given router handle - the configuration can be generated and pulled using the API as follows:
#! /bin/sh\n\n# The API Key.\n# This is generated in IXP Manager via the top right menu: *My Account -> API Keys*\nKEY=\"your-admin-ixp-manager-api-key\"\n\n# The base URL of your IXP Manager install plus: 'api/v4/router/gen-config'\nURL=\"https://ixp.example.com/api/v4/router/gen-config\"\n\n# The handle is as described above:\nHANDLE=\"rc1-lan1-ipv4\"\n\n# Then the configuration can be pulled as follows:\ncurl --fail -s -H \"X-IXP-Manager-API-Key: ${KEY}\" ${URL}/${HANDLE} >${HANDLE}.conf\nConfigurations for the route server and AS112 templates can be configured just as easily.
The stock templates for both are secure and well tested and can be used by setting the template element of the router to one of the following. NB: from May 2019, we recommend you use IXP Manager v5 and Bird2 templates.
'api/v4/router/as112/bird/standard''api/v4/router/as112/bird2/standard''api/v4/router/collector/bird/standard''api/v4/router/collector/bird2/standard''api/v4/router/server/bird/standard''api/v4/router/server/bird2/standard'We also provide sample scripts for automating the re-configuration of these services by cron:
All of these scripts have been written defensively such that if there is any issue getting the configuring or validating the configuration then the running router instance should be unaffected. This has worked in practice at INEX when IXP Manager was under maintenance, when there were management connectivity issues and when there were database issues. They also use the updated API (see below) to mark when the router configuration update script ran successfully.
"},{"location":"features/routers/#router-pairing-and-locking","title":"Router Pairing and Locking","text":"InfoPairing, locking and the more advanced update scripts were introduced with IXP Manager v6.4.0, and there is also a tutorial video linked from the release notes.
For IXPs, route servers are considered a critical production service and most IXPs deploy them in redundant pairs. This is usually implemented with dedicated hardware (servers with dual PSU, hardware RAID, and out-of-band management access) deployed in different points of presence.
When it comes to updating the configuration of these, the older scripts provided by IXP Manager suggested that this be done about four times per day with the timing of the cronjob set so that there is an offset so that each server will not update at the same time. The hope was that if there was an issue, only one server of the resilient pair would be affected, and engineers would have time to react and prevent updates on the other working server. Some IXPs added additional logic to the scripts to check if the other server was functional before performing a reconfiguration, but this was often limited to pings and a simple check to see if Bird was running.
The v6.4.0 release introduced a significant new resilience mechanism by pairing servers. In the IXP Manager router UI, you can now select another router to pair with the one you are editing:
You would select pairs as follows:
Once your pairs are set up, you need to deploy the new router update scripts as follows:
There is no need to use different scripts for route collectors and servers. Traditionally, at INEX, these scripts were developed slightly differently from each other (e.g., the collector script updates both IPv4 and IPv6 versions and provides more informative output, whereas the route server script takes a specific route server handle to update). We may merge these in the future.
You can use these scripts exactly as they are on an Ubuntu server changing only the configuration lines at the top:
APIKEY=\"your-api-key\"\nURLROOT=\"https://ixp.example.com\"\nBIRDBIN=\"/usr/sbin/bird\"\nThe collector script takes an additional configuration option for the handles of the servers to update - e.g.:
HANDLES=\"rc1-ipv4 rc1-ipv6\"\nThese new scripts now work as follows:
/api/v4/router/get-update-lock/$handle, which IXP Manager then processes and returns HTTP code 200 if the lock is acquired and the update can proceed./api/v4/router/updated/$handle to release the lock and update the last updated timestamp.Adding step (5) above (only reload on changes) now allows the update script to be safely run as frequently as every few minutes, which is necessary for the UI-based community filtering to be effective.
You should still offset the updates between router pairs, as the script will give up if a lock cannot be obtained. Future improvements could allow for some retries.
For additional information with UI images, see slides 25-30 in this presentation PDF.
"},{"location":"features/routers/#updated-api","title":"Updated API","text":"It can be useful to know that the scripts for updating the router configuration for AS112, route collector and route server BGP daemons run successfully. At INEX for example, we have three LANs and so 10 individual servers running a total of 30 Bird instances which is unwieldy to check and monitor manually.
When viewing routers in IXP Manager, you may have noticed the Last Updated column which will initially show (unknown). All our update scripts (see above) trigger the updated API call when a route configuration run has completed successfully. Note that this does not mean that a configuration has necessarily changed but rather that the update script ran and executed correctly. In other words: the configuration was successfully pulled from IXP Manager, compared to the running configuration and, if changed, successfully applied.
The API call to update the last updated field to now is a POST as follows:
curl -s -X POST -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixp.example.com/api/v4/router/updated/{handle}\nwhere {handle} should be replaced with the route handle as described above.
The result is a JSON object with the datetime as set and is equivalent to the result of the following API call which fetches the last updated field without setting it:
curl -s -X GET -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixp.example.com/api/v4/router/updated/{handle}\n\n{\"last_updated\":\"2017-05-21T19:14:43+00:00\",\"last_updated_unix\":1495394083}\nThere are two useful additional API endpoints. To get the last updated time of all routers, use:
curl -s -X GET -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixp.example.com/api/v4/router/updated\n\n{\"handle1\":{\"last_updated\":\"2017-05-21T19:14:43+00:00\",\"last_updated_unix\":1495394083},\n \"handle2\":{\"last_updated\":null,\"last_updated_unix\":null},\n ...}\nThe above output shows the format of the reply as well as the fact that routers without a last updated value set will be included as null values.
Lastly, you can request the last updated time of routers where that time exceeds a given number of seconds. In this call, routers without a last updated time will not be returned. This is useful for monitoring applications such as Nagios where you would want a warning / alert on any routers that have not updated in the last day for example:
curl -s -X GET -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixp.example.com/api/v4/router/updated-before/86400\n\n[]\nThis example also shows that an empty JSON object is returned for an empty result. Otherwise the format of the reply is the same as for the call above for all routers:
{\"handle1\":{\"last_updated\":\"2017-05-21T19:14:43+00:00\",\"last_updated_unix\":1495394083},...}\nWe use Travis CI to test IXP Manager before pushing new releases. The primary purpose of this is to ensure that the configuration for routers generated matches known good configurations from the same sample database.
These known good configurations also serve as useful examples of what the standard IXP Manager configuration generates.
See these known good configurations here and:
as112: AS112 router configurations conforming to rfc7534 (AS112 Nameserver Operations) and implementing rfc7535 (AS112 Redirection Using DNAME). There are configs to serve queries over both IPv4 and IPv6. See the AS112 documentation for more details.rc1: route collector configurations. Peering with the route collector is mandatory at many IXPs including INEX. These are incredibly useful for monitoring, diagnosing issues and providing looking glasses. We also use the quarantine version of these for turning up new member connections.rs1: route collector configurations. See below for full details of what these implement. See the route servers documentation for more details.The live status of any configured routers that have API access can be seen in IXP Manager via the Live Status sub-menu option of Routers on the left hand side menu.
Each router is queried twice via AJAX requests to provide:
We filter known transit networks as discussed here: https://bgpfilterguide.nlnog.net/guides/no_transit_leaks/.
There are three configuration options available (>v6.1.0) to allow you to change the default behaviour. These options exist to provide an easier path than skinning the template files directly.
Exclude one of more AS numbers from the default list (see this file on your own deployment of IXP Manager).
(1) Exclude Specific ASNs:
If you just want to exclude one or more ASNs from the default list, then using comma separation, set the following in your .env file:
IXP_NO_TRANSIT_ASNS_EXCLUDE=65501,65502\n(2) Disable This Feature Entirely:
Set an empty configuration option as follows in your .env file:
IXP_NO_TRANSIT_ASNS_OVERRIDE=\n(3) Use Your Own Custom List of ASNs:
Set the following configuration option with a comma separated list as follows in your .env file:
IXP_NO_TRANSIT_ASNS_OVERRIDE=65501,65502,65503\nIXP Manager supports RPKI validation on the router configuration generated for Bird v2. The best way to fully understand RPKI with IXP Manager is to watch our presentation from APRICOT 2019 or read this article on INEX's website.
"},{"location":"features/rpki/#rpki-validator-local-cache","title":"RPKI Validator / Local Cache","text":"IXP Manager uses the RPKI-RTR protocol to feed ROAs to the Bird router instances. We recommend you install two of these validators/local caches from different vendors.
Let IXP Manager know where they are by setting the following .env settings:
# IP address and port of the first RPKI local cache:\nIXP_RPKI_RTR1_HOST=192.0.2.11\nIXP_RPKI_RTR1_PORT=3323\n\n# While not required, we recommend you also install a second validator:\n# IXP_RPKI_RTR2_HOST=192.0.2.12\n# IXP_RPKI_RTR2_PORT=3323\nSee our installation notes for these:
As it stands, Bird v2.0.4 does not support revalidation of prefixes following ROA updates (i.e. a prefix that was accepted as ROA valid that subsequently becomes ROA unknown / invalid will remain learnt as ROA valid). The Bird developers are working on fixing this. In the interim, you need to schedule a revalidation via cron using a /etc/crontab entry such as:
20 11,23 * * * root /usr/sbin/birdc -s /var/run/bird/bird-rs1-ipv4.ctl reload in all >/dev/null\nThe outline procedure to enable RPKI is below. These notes are written from the perspective that you have existing IXP Manager Bird v1 route servers. If this is a green field site, these notes will work just as well by ignoring the upgrade bits. In either case, it's vital you already understand how to configure routers in IXP Manager.
At INEX we started with our route collector which is a non-service affecting administrative tool. Once we were happy with the stability and results of that, we upgraded our two route servers one week apart in planned announced maintenance windows. We also took the opportunity to perform a distribution upgrade from Ubuntu 16.04 to 18.04.
Start by installing two local caches / validator services as linked above. INEX uses Cloudflare's and Routinator 3000. You should also add these to your production monitoring service.
Once your maintenance window starts, stop the target route server you plan to upgrade. You'll then need to to remove the Bird v1 package (dpkg -r bird on Ubuntu). Once the Bird package is removed, you can perform a distribution upgrade if you wish.
Bird v2 is available as a prebuilt package with Ubuntu 20.04 LTS and can be installed with apt install bird2.
There are no Bird v2 packages for Ubuntu 18.04 LTS. As such, you need to install from source if using that older platform. Rather than installing a build environment and compiling on each server, you can do this on a single server (a dedicated build box / admin server / etc) and then distribute the package across your route servers / collector:
# Install Ubuntu build packages and libraries Bird requires:\napt install -y build-essential libssh-dev libreadline-dev \\\n libncurses-dev flex bison checkinstall\n\n# At time of writing, the latest release was v2.0.7.\n# Check for newer versions!\ncd /usr/src\nwget ftp://bird.network.cz/pub/bird/bird-2.0.7.tar.gz\ntar zxf bird-2.0.7.tar.gz\ncd bird-2.0.7/\n./configure --prefix=/usr --sysconfdir=/etc\nmake -j2\ncheckinstall -y\nThe checkinstall tool creates a deb package file: /usr/local/src/bird-2.0.7/bird_2.0.7-1_amd64.deb
NB: for this method to work, you must be running the same operating system and version on the target servers as the build box. For us, it was Ubuntu 18.04 LTS on all systems.
To install on a target machine:
# from build machine\nscp bird_2.0.7-1_amd64.deb target-machine:/tmp\n\n# on target machine\napt install -y libssh-dev libreadline-dev libncurses-dev\ndpkg -i /tmp/bird_2.0.7-1_amd64.deb\nYou now need to update your route server record in IXP Manager:
api/v4/router/server/bird2/standard.Note that the Bird v2 template uses large BGP communities extensively internally. The option Enable Large BGP Communities / RFC8092 only controls whether your members can use large communities for filtering. It's 2020 - you should really enable this.
As mentioned above, you need to let IXP Manager know where your local caching / validators are by setting the following .env settings:
# IP address and port of the first RPKI local cache:\nIXP_RPKI_RTR1_HOST=192.0.2.11\nIXP_RPKI_RTR1_PORT=3323\n\n# While not required, we recommend you also install a second validator:\nIXP_RPKI_RTR2_HOST=192.0.2.12\nIXP_RPKI_RTR2_PORT=3323\nTake a look at the generated configuration within IXP Manager now and sanity check it.
If you have been using our scripts to reload route server configurations, you will need to download the new one (and edit the lines at the top) or update your existing one. The main elements that need to be changed is that the daemon name is not longer named differently for IPv6 (Bird v1 had bird/birdc and bird6/bird6c where as Bird v2 only has bird/birdc).
You should now be able to run this script to pull a new configuration and start an instance of the route server. We would start with one and compare route numbers (just eyeball them) against the route server you have not upgraded.
You're nearly there! If you are using our Bird's Eye looking glass, you will need to upgrade this to >= v1.2.1 for Bird v2 support. At INEX, we tend to clone the repository and so a simple git pull is all that's required. If you're installing from release packages, get the latest one and copy over your configurations.
These notes are valid when using IXP Manager's Bird v2 with RPKI route server configuration.
You can see the status of the RPKI-RTR protocol with:
bird> show protocols \"rpki*\"\nName Proto Table State Since Info\nrpki1 RPKI --- up 2019-05-11 14:51:40 Established\nrpki2 RPKI --- up 2019-05-11 12:44:25 Established\nAnd you can see detailed information with:
bird> show protocols all rpki1\nName Proto Table State Since Info\nrpki1 RPKI --- up 2019-05-11 14:51:40 Established\n Cache server: 10.39.5.123:3323\n Status: Established\n Transport: Unprotected over TCP\n Protocol version: 1\n Session ID: 54059\n Serial number: 122\n Last update: before 459.194 s\n Refresh timer : 440.805/900\n Retry timer : ---\n Expire timer : 172340.805/172800\n Channel roa4\n State: UP\n Table: t_roa\n Preference: 100\n Input filter: ACCEPT\n Output filter: REJECT\n Routes: 72161 imported, 0 exported\n Route change stats: received rejected filtered ignored accepted\n Import updates: 141834 0 0 0 141834\n Import withdraws: 2519 0 --- 0 3367\n Export updates: 0 0 0 --- 0\n Export withdraws: 0 --- --- --- 0\n No roa6 channel\nYou can examine the ROA table with:
bird> show route table t_roa\nTable t_roa:\n58.69.253.0/24-24 AS36776 [rpki1 2019-05-11 14:51:40] * (100)\n [rpki2 2019-05-11 12:45:45] (100)\nNow, using INEX's route collector ASN (2128) as an example here - change for your own collector/server ASN - you can find RPKI invalid and filtered routes via:
bird> show route where bgp_large_community ~ [(2128,1101,13)]\nTable master4:\n136.146.52.0/22 unicast [pb_as15169_vli99_ipv4 2019-05-11 01:00:17] * (100) [AS396982e]\n via 185.6.36.57 on eth1\n...\nAt time of writing, the filtered reason communities are:
define IXP_LC_FILTERED_PREFIX_LEN_TOO_LONG = ( routeserverasn, 1101, 1 );\ndefine IXP_LC_FILTERED_PREFIX_LEN_TOO_SHORT = ( routeserverasn, 1101, 2 );\ndefine IXP_LC_FILTERED_BOGON = ( routeserverasn, 1101, 3 );\ndefine IXP_LC_FILTERED_BOGON_ASN = ( routeserverasn, 1101, 4 );\ndefine IXP_LC_FILTERED_AS_PATH_TOO_LONG = ( routeserverasn, 1101, 5 );\ndefine IXP_LC_FILTERED_AS_PATH_TOO_SHORT = ( routeserverasn, 1101, 6 );\ndefine IXP_LC_FILTERED_FIRST_AS_NOT_PEER_AS = ( routeserverasn, 1101, 7 );\ndefine IXP_LC_FILTERED_NEXT_HOP_NOT_PEER_IP = ( routeserverasn, 1101, 8 );\ndefine IXP_LC_FILTERED_IRRDB_PREFIX_FILTERED = ( routeserverasn, 1101, 9 );\ndefine IXP_LC_FILTERED_IRRDB_ORIGIN_AS_FILTERED = ( routeserverasn, 1101, 10 );\ndefine IXP_LC_FILTERED_PREFIX_NOT_IN_ORIGIN_AS = ( routeserverasn, 1101, 11 );\ndefine IXP_LC_FILTERED_RPKI_UNKNOWN = ( routeserverasn, 1101, 12 );\ndefine IXP_LC_FILTERED_RPKI_INVALID = ( routeserverasn, 1101, 13 );\ndefine IXP_LC_FILTERED_TRANSIT_FREE_ASN = ( routeserverasn, 1101, 14 );\ndefine IXP_LC_FILTERED_TOO_MANY_COMMUNITIES = ( routeserverasn, 1101, 15 );\nCheck the route server configuration as generated by IXP Manager for the current list if you are reading this on a version later than v5.0.
If you want to see if a specific IP is covered by a ROA, use:
bird> show route table t_roa where 45.114.234.0 ~ net\nTable t_roa:\n45.114.234.0/24-24 AS59347 [rpki1 2019-05-11 14:51:40] * (100)\n [rpki2 2019-05-11 12:45:45] (100)\n45.114.232.0/22-24 AS59347 [rpki1 2019-05-11 14:51:40] * (100)\n [rpki2 2019-05-11 12:45:45] (100)\n45.114.232.0/22-22 AS59347 [rpki1 2019-05-11 14:51:41] * (100)\n [rpki2 2019-05-11 12:45:45] (100)\nThe IXP Manager sflow peer-to-peer graphing system depends on the MAC address database system so that point to point traffic flows can be identified. Before proceeding further, this should be configured so that when you click on either the MAC Addresses | Discovered Addresses or MAC Addresses | Configured Addresses links from the admin portal, you should see a MAC address associated with each port. If you cannot see any MAC address in either database, then the sflow peer-to-peer graphing mechanism will not work. This needs to be working properly before any attempt is made to configure sflow peer-to-peer graphing. The sflow p2p graphing system can use either discovered MAC addresses or configured MAC addresses, but not both.
As sflow can put a reasonably high load on a server due to disk I/O for RRD file updates - it is recommended practice to use a separate server (or virtual server) to handle the IXP's sflow system. The sflow server will need:
noatime, nodiratime options, and which has enough disk space. You may also want to consider disabling filesystem journaling.pkg install apache24 sflowtool git databases/rrdtool mrtg\napt-get install apache2 git rrdtool rrdcached mrtg\nsflowtool is not part of the Ubuntu / Debian package archive and must be compiled from source if running on these systems. The source code can be found on Github: https://github.com/sflow/sflowtool.
Once the required packages are installed, the IXP Manager peer-to-peer graphing system can be configured as follows:
git clone https://github.com/inex/IXP-Manager /srv/ixpmanager.tools/runtime/check-perl-dependencies.pl command. These libraries will need to be manually installed.tools/perl-lib/IXPManager directory (perl Makefile.PL; make install)rrdcached. We recommend using journaled mode with the -P FLUSH,UPDATE -m 0666 -l unix:/var/run/rrdcached.sock options enabled. Note that these options allow uncontrolled write access to the RRD files from anyone on the sflow machine, so precautions should be taken to limit access to this server to ensure that this cannot be abused.On FreeBSD it is advisable to set net.inet.udp.blackhole=1 in /etc/sysctl.conf, to stop the kernel from replying to unknown sflow packets with an ICMP unreachable reply.
The following sflow parameters must be set in the <ixp> section:
sflow_rrdcached: set to 0 or 1, depending on whether you want to use rrdcached or not.sflowtool: the location of the sflowtool binary.sflowtool_opts: command-line options to pass to sflowtoolsflow_rrddir: the directory where all the sflow .rrd files will be stored.apikey: a valid API key. Instructions for configuring this can be found in the API configuration documentation.apibaseurl: the base URL of the IXP Manager API. E.g. if you log into IXP Manager using https://ixp.example.com/, then apibaseurl will be https://ixp.example.com/api/v4.macdbtype: configured|discovered - specifies whether the sflow p2p graphing system should pull MAC address information from the Configured MAC address database or the Discovered MAC address database. By default, it uses the Discovered MAC address database. If you wish to use the Configured MAC address database, then this should be set to configured.Note that the <sql> section of ixpmanager.conf will need to be configured either if you are running update-l2database.pl or the sflow BGP peering matrix system. The sflow-to-rrd-handler script uses API calls and does not need SQL access.
An example ixpmanager.conf might look like this:
<sql>\n dbase_type = mysql\n dbase_database = ixpmanager\n dbase_username = ixpmanager_user\n dbase_password = blahblah\n dbase_hostname = sql.example.com\n</sql>\n\n<ixp>\n sflowtool = /usr/bin/sflowtool\n sflowtool_opts = -4 -p 6343 -l\n sflow_rrdcached = 1\n sflow_rrddir = /data/ixpmatrix\n\n apikey = APIKeyFromIXPManager\n apibaseurl = http://www.example.com/ixp/api/v4\n macdbtype = configured\n</ixp>\nThis file should be placed in /usr/local/etc/ixpmanager.conf
The tools/runtime/sflow/sflow-to-rrd-handler command processes the output from sflowtool and injects it into the RRD archive. This command should be configured to start on system bootup.
If you are running on FreeBSD, this command can be started on system bootup by copying the tools/runtime/sflow/sflow_rrd_handler script into /usr/local/etc/rc.d and modifying the /etc/rc.conf command to include:
sflow_bgp_handler_enable=\"YES\"\nThe IXP Manager web GUI requires access to the sflow p2p .rrd files over http or https. This means that the sflow server must run a web server (e.g. Apache), and the IXP Manager GUI must be configured with the URL of the RRD archive on the sflow server.
Assuming that ixpmanager.conf is configured to use /data/ixpmatrix for the RRD directory, these files can be server over HTTP using the following Apache configuration (please consider appropriate access security - this example assumes an internal host on an internal network):
Alias /grapher-sflow /data/ixpmatrix\n<Directory \"/data/ixpmatrix\">\n Options None\n Require all granted \n</Directory>\nThe IXP Manager .env file must be configured with parameters both to enable sflow and to provide the front-end with the HTTP URL of the back-end server. Assuming that the sflow p2p server has IP address 10.0.0.1, then the following lines should be added to .env:
GRAPHER_BACKENDS=\"mrtg|sflow|smokeping\"\nGRAPHER_BACKEND_SFLOW_ENABLED=true\nGRAPHER_BACKEND_SFLOW_ROOT=\"http://10.0.0.1/grapher-sflow\"\nEach IXP edge port will have 4 separate RRD files for recording traffic to each other participant on the same VLAN on the IXP fabric: ipv4 bytes, ipv6 bytes, ipv4 packets and ipv6 packets. This means that the number of RRD files grows very quickly as the number of IXP participants increases. Roughly speaking, for every N participants at the IXP, there will be about 4*N^2 RRD files. As this number can create extremely high I/O requirements on even medium sized exchanges, IXP Manager requires that rrdcached is used.
There are plenty of things which could go wrong in a way which would stop the sflow mechanism from working properly.
update-l2database.pl script, if you are using discovered MAC addresses. If you're using configured MAC addresses, you can ignore update-l2database.pl script completed but you should make sure that there are valid MAC addresses associated with each port you're attempting to monitor.sflow-to-rrd-handler script crashes, this may indicate that the back-end filesystem is overloaded. Installing rrdcached is a first step here. If it crashes with rrdcached enabled, then you need more disk I/O (SSDs, etc).No. All of this runs perfectly well on Ubuntu (or your favourite Linux distribution).
INEX runs its sflow back-end on FreeBSD because we found that the UFS filesystem performs better than the Linux ext3 filesystem when handling large RRD archives. If you run rrdcached, it's unlikely that you will run into performance problems. If you do, you can engineer around them by running the RRD archive on a PCIe SSD.
The tools/runtime/sflow/sflow-to-rrd-handler script from IXP Manager referenced above uses an IXP Manager API endpoint to associate sflow samples (based on source and destination MAC addreesses) with VLAN interfaces.
As IXP Manager supports layer2 / MAC addresses in two ways (learned versus configured), there are two endpoints (using https://ixp.example.com as your IXP Manager installation):
https://ixp.example.com/api/v4/sflow-db-mapper/learned-macshttps://ixp.example.com/api/v4/sflow-db-mapper/configured-macsThe JSON output is structured as per the following example:
{\n \"infrastructure id\": {\n \"vlan tag\": {\n \"mac address\": \"vlan interface id\",\n ...\n },\n ...\n },\n ...\n}\nwhere:
\"macaddress\": \"vlaninterfaceid\"IXP Manager can use sflow data to:
The peer-to-peer traffic graphs show traffic aggregate analysis of bytes/packets, split by VLAN and protocol (IPv4 / IPv6), both for individual IXP peering ports and entire VLANs.
The peering matrix guesses who interconnects with whom on the basis of analysing bgp session flows.
"},{"location":"features/sflow/#helicopter-view","title":"Helicopter View","text":"Sflow needs to be configured with an \"accounting perimeter\". This means that ingress sflow accounting should be enabled on all edge ports, but should not be enabled on any of the core ports. This approach ensures that all packets entering or leaving the IXP are counted exactly once, when they enter the IXP fabric.
All the switches at the IXP should be configured to send sflow packets to the IP address of your sflow collector. This will probably be the same server that you use for your IXP Manager sflow peer-to-peer graphing.
If sflow is enabled on any of the core ports or sflow is enabled in both directions (ingress + egress), traffic will be double-counted and this will lead to incorrect graphs.
Each switch on the network sends sampled sflow packets to an sflow collector. These packets are processed by the \"sflowtool\" command, which converts into an easily-parseable ascii format. IXP Manager provides a script to read the output of the sflowtool command, correlate this against the IXP database and to use this to build up a matrix of traffic flows which are then exported to an RRD database.
The RRD files are stored on disk and can be accessed by using the sflow graphing system included in IXP Manager.
"},{"location":"features/sflow/#sflow-on-switches","title":"Sflow on Switches","text":"Many vendors support sflow, but some do not. There is a partial list on the sflow web site.
Most switches which support sflow will support ingress accounting, because this is what's required in RFC 3176. Some switches (e.g. Dell Force10 running older software) only support egress sflow. If you use these on your IXP alongside other switches which only support ingress sflow, then the sflow graphs will show twice the traffic in one direction for the p2p graphs and zero traffic in the other direction. There is no way for IXP Manager to work around this problem.
If not all of the IXP edge ports are sflow capable, then sflow traffic data will be lost for these ports. This means that some point-to-point traffic graphs will show up with zero traffic, and that the sflow aggregate graphs will be wrong.
Sflow uses data sampling. This means that the results it produces are estimated projections, but on largee data sets, these projections tend to be statistically accurate.
Each switch or switch port needs to be configured with an sflow sampling rate. The exact rate chosen will depend on the traffic levels on the switch, how powerful the switch management plane CPU is, and how much bandwidth is available for the switch management.
On a small setup with low levels of traffic (e.g. 100kpps), it would be sensible to leave the sampling rate low (e.g. 1:1024). Alternatively, a busy 100G port may need a sampling rate of 1:32768 may turn out to be too low if the port is seeing large numbers of packets. If the switch or the entire network is handling very large quantities of traffic, this figure should be high enough that IXP ports with low quantities of traffic will still get good quality graphs, but low enough that the switch management CPU isn't trashed, and that packets are not dropped on the management ethernet port.
Some switches have automatic rate-limiting built in for sflow data export. The sampling rate needs to be chosen so that sflow data export rate limiting doesn't kick in. If it does, samples will be lost and this will cause graph inaccuracies.
"},{"location":"features/sflow/#switch-implementation-limitations","title":"Switch Implementation Limitations","text":""},{"location":"features/sflow/#netflow","title":"Netflow","text":"IXP Manager does not support netflow and support is not on the roadmap. This is because most netflow implementations do not export mac address information, which means that they cannot provide workable mac layer peer-to-peer statistics.
"},{"location":"features/sflow/#cisco-switches","title":"Cisco Switches","text":"Of Cisco's entire product range, only the Nexus 3000 and Nexus 9000 product range support sflow. Also, the sflow support on the Cisco Nexus 3k range is crippled due to the NX-OS software implementation, which forces ingress+egress sflow to be configured on specified ports rather than ingress-only. Functional accounting requires ingress-only or egress-only sflow to be configured on a per-port basis: ingress + egress causes double-counting of packets. It may be possible to work around this limitation using the broadcom shell using something like the following untested configuration:
n3k# conf t\nn3k(config)# feature sflow\nn3k(config)# sflow data-source interface Ethernet1/1\nn3k(config)# ^Z\nn3k# test hardware internal bcm-usd bcm-diag-shell\nAvailable Unit Numbers: 0\nbcm-shell.0> PortSampRate xe0 4096 0\nbcm-shell.0> PortSampRate xe0\n xe0: ingress: 1 out of 4096 packets, egress: not sampling,\nbcm-shell.0> quit\nn3k#\nNote that this command is not reboot persistent, and any time the switch is rebooted, the command needs to be re-entered manually. Note also that this configuration is untested.
"},{"location":"features/sflow/#brocade-turboiron-24x","title":"Brocade TurboIron 24X","text":"By default a TIX24X will export 100 sflow records per second. This can be changed using the following command:
SSH@Switch# dm device-command 2762233\nSSH@Switch# tor modreg CPUPKTMAXBUCKETCONFIG(3) PKT_MAX_REFRESH=0xHHHH\n... where HHHH is the hex representation of the number of sflow records per second. INEX has done some very primitive usage profiling which suggests that going above ~3000 sflow records per second will trash the management CPU too hard, so we use PKT_MAX_REFRESH=0x0BB8. Note that this command is not reboot persistent, and any time a TIX24X is rebooted, the command needs to be re-entered manually.
"},{"location":"features/sflow/#dell-force10","title":"Dell Force10","text":"Earlier versions of FTOS only support egress sflow, but support for ingress sflow was added in 2014. If you intend to deploy IXP Manager sflow accounting on a Dell F10 switch, then you should upgrade to a software release which supports ingress sflow.
"},{"location":"features/sflow/#cumulus-linux","title":"Cumulus Linux","text":"Cumulus Linux uses hsflowd, which does not allow the operator to enable or disable sflow on a per-port basis, nor does it permit the operator to configure ports to use ingress-only sflow. This configuration needs to be handled using the /usr/lib/cumulus/portsamp command, which is not reboot persistent. It is strongly recommended to handle this configuration using orchestration, as it is not feasible to manually maintain this configuration.
The sflow data from all the IXP switches will normally be directed at a single sflow collector. Often it is useful to have multiple copies of this sflow data stream so that the sflow data can be processed in different ways.
IXP Manager uses sflow data for two separate components:
This means that IXP Manager needs two separate sflow feeds. This can be achieved by using the sflowtool fanout facility, which sends an exact copy of all incoming sflow records to a list of destinations. For example, the following command listens for incoming sflow data on port 6343 and send three copies out. Two copies are directed to different ports on the same server, on ports 5500 and 5501. The third copy is sent to 192.0.2.20, port 6343.
# sflowtool -4 -p 6343 -f 127.0.0.1/5500 -f 127.0.0.1/5501 -f 192.0.2.20/6343\nThis example could be used for handling P2P traffic graphs and BGP session detection on one machine, while sending a third sflow data feed to a separate server for IXP development or debugging. The two local sflow feeds can be read using sflowtool:
# sflowtool -4 -p 5500 -l\n# sflowtool -4 -p 5501 -l\nThe sflowtool fanout daemon should be started by the normal operating system daemon startup mechanism, e.g. script in a rc.d or init.d directory, or by a manual entry in /etc/rc.local.
If running sflowtool version 3.23 or greater, it is important to use the -4 command-line parameter in sflowtool because otherwise it will listen on both ipv4 and ipv6 sockets. If you have an sflowtool process attempting to listen on a wildcard socket, it will stop other sflowtool processes from starting.
Remember that v4 is a transition version of IXP Manager from Zend Framework / Smarty to Laravel and so much of the frontend / templating still uses v3 templates and code. As such, how to skin a page will depend on whether the template is found in resources/views (v4) or application/[modules/xxx/]views (v3). Both are covered here.
IXP Manager supports template/view skinning allowing users to substitute any of their own templates in place of the default ones shipped with IXP Manager.
"},{"location":"features/skinning/#skinning-in-version-v4","title":"Skinning in Version >=v4","text":"First, set the following parameter in .env:
VIEW_SKIN=\"example\"\nSkins should then be placed in the resources/skins/example directory (example should be substituted for whatever you want to call your own skin). The default templates can be found in resources/views directory. INEX bundles its own skinned templates in resources/skins/inex as an example.
Once a skin is enabled from .env, then any templates found in the skin directory (using the same directory structure as found under resouces/views) will take precedence over the default template file. This means you do not need to recreate / copy all the default files - just replace the ones you want.
In previous versions of IXP Manager, we used Smarty as the templating engine. This meant that if someone wanted to help improve IXP Manager then they would need to become familiar with PHP and Smarty. In v4 we dropped Smarty and, rather than using another compiled templating engine, we have decided to go with native PHP templates.
For this, we are using Foil - Foil brings all the flexibility and power of modern template engines to native PHP templates. Write simple, clean and concise templates with nothing more than PHP. Also, simulaneously supported are Lavael's own Blade templates which we sometimes use for simple pages.
"},{"location":"features/skinning/#example","title":"Example","text":"The graphing MRTG configuration generator allows for custom configuration content at the top and bottom of the file. In order to have your custom configuration enabled, you need to skin two files.
Here's an example:
# position ourselves in the IXP Manager root directory\ncd ${IXPROOT}\n\n# make the skin directory\nmkdir resources/skins/example\n\n# create the full path required for the MRTG configuration files:\nmkdir -p resources/skins/example/services/grapher/mrtg\n\n# copy over the customisation files:\ncp views/services/grapher/mrtg/custom-header.foil.php resources/skins/example/services/grapher/mrtg\ncp views/services/grapher/mrtg/custom-footer.foil.php resources/skins/example/services/grapher/mrtg\n\n# edit the above files as required\nvi resources/skins/example/services/grapher/mrtg/custom-header.plates.php\nvi resources/skins/example/services/grapher/mrtg/custom-footer.plates.php\nThen, finally, edit .env and set the skin to use:
VIEW_SKIN=\"example\"\nYou can of course skin any file including the non-custom MRTG files as suits your needs.
"},{"location":"features/skinning/#custom-variables-configuration-options","title":"Custom Variables / Configuration Options","text":"When you are skinning your own templates, you may find you need to create custom configuration options for values you do not want to store directly in your own templates. For this, we have a configuration file which is excluded from Git. Initiate it via::
cp config/custom.php.dist config/custom.php\nThis is Laravel's standard configuration file format (which is an associative PHP array). You can also use Laravel's dotenv variables here too.
As an example, if you were to create a configuration option:
<?php\n'example' => [\n 'key' => 'my own config value',\n],\nthen in code this would be accessible as:
<?php\nconfig( \"custom.example.key\", \"default value if not set|null\" )\nwhere the second parameter is a default option if the requested configuration setting has not been defined (which defaults to null). In templates, this can be accessed the same way or rendered in the template with::
<?= config( \"custom.example.key\", \"default\" ) ?>\nThis is still important as IXP Manager v4 still uses most of the previous templates.
To skin files found under application/[modules/xxx/]views, proceed as follows:
set a skin name in .env:
VIEW_SMARTY_SKIN=\"myskin\"\ncreate a directory with a matching name: application/views/_skins/myskin.
Once the above .env option is set, then any pages in its skin directory (using the same directory structure as application/views will take precedence over the default template files. This means you do not need to recreate / copy all the default files - just replace the ones you want.
Usually there is one of two places to find a template:
resources/views/$controller/$actionapplication/views/$controller/$actionIf you're skinning, then there's an extra two places:
resources/skins/$skin/$controller/$actionapplication/views/_skins/$skin/$controller/$actionThe indicated variables above mean:
$controller: typically the first part of the URL (after the main IXP Manager site) for the page you are looking at. Examples include: patch-panel, router but they may also be deeper API paths such as api/v4/router.$action: the last part of the URL such as edit.$skin: the name of your skin as defined above.Typically, following the URL path in the views directory will yield the template file you need.
To help identify if the page you are looking at is from the =v4 code base, we have added a HTML comment to the templates which appears just after the <head> tag as follows:
For >=v4 (new codebase):
<!-- IXP MANAGER - template directory: resources/[views|skins] -->\nFor <v4 (old codebase):
<!-- IXP MANAGER - template directory: application/views -->\nIXP Manager can serve some static pages for you if you wish. The typical use cases for this are:
In IXP Manager, there are four types of users as described in the users page. Static contact can be added which requires a minimum user privilege to access (e.g. priv == 0 would be publicly accessible through to priv == 3 which would require a superadmin).
To create static content, you should first set up skinning for your installation. Let's assume you called your skin example.
To create a publicly accessible static content page called misc-benefits, you would first create a content directory in your skin as follows:
cd $IXPROOT\nmkdir -p resources/skins/example/content/{0,1,2,3}\nwhere the directories 0, 1, 2, 3 represent the minimum required user privilege to access the content. You can now create your content page as follows:
cp resources/views/content/0/example.foil.php resources/skins/example/content/0/misc-benefits.foil.php\nand then edit that page.
It can be accessed using a URL such as: https://ixp.example.com/content/0/misc-benefits where the route template is: content/{priv}/{page}.
{priv} is the minimum required user privilege required to access the page and is used first for testing the user's permissions and second as the directory to check for the file.{page} is the name of the file to load (less .foil.php) and please be aware that this is normalised as follows: preg_replace( '/[^a-z0-9\\-_]/', '', strtolower( $page ) )\n[a-z0-9\\-_] and all lower case. Prior to v4.8.0 the strtolower() mistakenly occurred after the preg_replace().The example.foil.php template copied above should provide the necessary structure for you. Essentially just replace the title and the content.
For publicly accessible documents, there is an alias route:
/public-content/{page} -> treated as: /content/0/{page}\nIXP Manager ships with a link to Support in the main title menu. You should copy and adjust this as necessary via skinning:
cp resources/views/content/0/support.foil.php resources/skins/example/content/0/support.foil.php\nYou can link to your own static contact pages using the Documentation menu by skinning this file:
cp resources/views/layouts/header-documentation.foil.php resources/skins/example/layouts/header-documentation.foil.php\nThe stock version includes a link to the example page and a external link to the IXP Manager website (we would be much obliged if you left this in place!).
INEX's own version of this can be found in the shipped resources/skins/inex/header-documentation.foil.php file which shows how we use it.
IXP Manager can generate formatted lists of user information. The best example of this is for TACACS.
TACACS is used in most IXPs to manage access to switching and routing devices:
IXP Manager comes with a flexible template for generating the user section of a TACACS file.
"},{"location":"features/tacacs/#generating-tacacs-configuration","title":"Generating TACACS Configuration","text":"You can use the IXP Manager API to get the user section of a TACACS file using the following endpoint formats (both GET and POST requests work):
https://ixp.example.com/api/v4/user/formatted\nhttps://ixp.example.com/api/v4/user/formatted/{priv}\nhttps://ixp.example.com/api/v4/user/formatted/{priv}/{template}\nwhere:
priv is an optional user privilege to limit the user selection to. See the available integer values on the AUTH_ constants here. You typically want 3.template is an optional template (rather than $IXPROOT/resources/views/api/v4/user/formatted/default). See below.And example of a user in the response is:
user=joebloggs {\n member=admin\n login = des \"$2y$10$pHln5b4DrPj3uuhgfg45HeWEQLK/3ngRxYgYppbnYzleJ.9EpLAN.\"\n}\nYou can optionally POST any of the following to change elements of the default template:
template: only relevant when you want to specify a specific template without a privilege.priv: same as above.users: a comma-separated list of usernames to return rather than all / all based on privilege.bcrypt: IXP Manager stores bcrypt hashes with the prefix 2y. Some systems, such as TACACS+ on FreeBSD, require 2a. If you set bcrypt=2a, this substitution will be made before the data is returned.group: we put all users in the admin group in the default template. You can change that here.An example of changing these parameters is:
curl --data \"users=bob,alice&group=god&bcrypt=2a\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/user/formatted\nYou can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called mytemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/user/formatted\ncp resources/views/api/v4/user/formatted/default.foil.php resources/skins/myskin/api/v4/user/formatted/mytemplate1.foil.php\nYou can now edit this template as required. The only constraint on the template name is it can only contain characters from the classes a-z, 0-9, -. NB: do not use uppercase characters.
All variables available in the template can be seen in the default template.
"},{"location":"features/tacacs/#setting-up-tacacs","title":"Setting Up TACACS","text":"This section explains how to set up TACACS with IXP Manager. We assume you already have an understanding of TACACS.
"},{"location":"features/tacacs/#generating-updating-tacacs","title":"Generating / Updating TACACS","text":"At INEX, we use a script that:
You can find that script in this directory. Alter it to suit your own purposes.
"},{"location":"features/rpki/cloudflare/","title":"Cloudflare's RPKI Toolkit","text":"DangerCloudflare's RPKI toolkit has been deprecated and should not be used.
Cloudflare created their own RPKI toolkit which, similar to RIPE's, is split into two elements:
NB: Before you proceed further, you should read Cloudflare's own introduction to this toolkit.
We use a standard Ubuntu 20.04 installation (selecting the minimal virtual server option), 2 vCPUs, 2GB RAM, 20GB LVM hard drive.
Cloudflare provide pre-built packages for installation - visit the following URLs and download the appropriate packages for your operating system:
As of late November 2020, the following packages are available to install:
wget https://github.com/cloudflare/cfrpki/releases/download/v1.2.2/octorpki_1.2.2_amd64.deb\nwget https://github.com/cloudflare/gortr/releases/download/v0.14.7/gortr_0.14.7_amd64.deb\ndpkg -i octorpki_1.2.2_amd64.deb gortr_0.14.7_amd64.deb\nYou now need to install the ARIN file manually:
/usr/share/octorpki/tals/arin.talYou can now run the validator via the following command:
# start the service:\nsystemctl start octorpki\n\n# see and tail the logs\njournalctl -fu octorpki\n\n# enable to start on server boot:\nsystemctl enable octorpki.service\nNB: OctoRPKI listens as a web service by default on port 8081. It's possible to change this port by adding OCTORPKI_ARGS=-http.addr :8080 to /etc/default/octorpki if required.
As it starts up, there is some info available as JSON under http://[hostname/ip address]:8081/infos and the ROAs can be seen as JSON via http://[hostname/ip address]:8081/output.json after ~5mins.
To start GoRTR (once OctoRPKI is configured and running), we first edit /etc/default/gortr:
GORTR_ARGS=-bind :3323 -verify=false -cache http://localhost:8081/output.json -metrics.addr :8082\nYou can now run the GoRTR daemon via the following command:
# start the service:\nsystemctl start gortr\n\n# see and tail the logs\njournalctl -fu gortr\n\n# enable to start on server boot:\nsystemctl enable gortr.service\nOnce GoRTR starts up, metrics are available from http://[hostname/ip address]:8082/metrics.
"},{"location":"features/rpki/cloudflare/#monitoring","title":"Monitoring","text":"We add Nagios http checks for ports 8081 (OctoRPKI) and 8082 (GoRTR) to our monitoring platform. We also add a check_tcp test for GoRTR port 3323.
The RIPE NCC RPKI Validator 3 has been deprecated and should not be used.
The RIPE NCC RPKI Validator 3 is a RPKI relying party software (aka RPKI Validator). While RIPE's RPKI Validator 3 is a RPKI-RTR implementation we have tested and support, we found it buggy in production (as of April 2019 it consumed increasing amounts of disk space and crashed regularly). These instructions reflect INEX's production installation from early 2019.
RIPE provides CentOS7 RPMs for production builds but as we tend to use Ubuntu LTS for our servers, we will describe an installation using the generic builds here. You can read RIPE's CentOS7 installation details here and their own generic install details here (which are the ones we worked from for these Ubuntu 18.04 LTS instructions).
We use a standard Ubuntu 18.04 installation (selecting the minimal virtual server option), 2 vCPUs, 2GB RAM, 10GB LVM hard drive.
We will use a non-root user to run the daemons:
useradd -c 'RIPE NCC RPKI Validator' -d /srv/ripe-rpki-validator \\\n -m -s /bin/bash -u 1100 ripe\nDownload and extract the latest production releases from here:
cd /srv/ripe-rpki-validator\nwget https://ftp.ripe.net/tools/rpki/validator3/prod/generic/rpki-rtr-server-latest-dist.tar.gz\ntar zxf rpki-rtr-server-latest-dist.tar.gz\nwget https://ftp.ripe.net/tools/rpki/validator3/prod/generic/rpki-validator-3-latest-dist.tar.gz\ntar zxf rpki-validator-3-latest-dist.tar.gz\nWhen you extract these, you'll find they create directories named by their version. As we will reference these in various scripts, we will alias these directories so we do not need to update the scripts on an upgrade of the software. In our example case, the version was 3.0-255 so we do the following (and also ensure the permissions are correct):
ln -s rpki-rtr-server-3.0-355 rpki-rtr-server-3\nln -s rpki-validator-3.0-355 rpki-validator-3\nchown -R ripe: /srv/ripe-rpki-validator\nThe requirements for RPKI Validator 3 are OpenJDK and rsync. For Ubuntu 18.04 that means:
apt install -y openjdk-8-jre rsync curl\nWe will want to keep configuration changes and the database across upgrades. For this we:
# move the config and replace it with a link:\ncd /srv/ripe-rpki-validator\nmv rpki-validator-3/conf/application.properties rpki-validator-3.conf\nln -s /srv/ripe-rpki-validator/rpki-validator-3.conf \\\n /srv/ripe-rpki-validator/rpki-validator-3/conf/application.properties\n\n# And do the same for the datebase:\nmv rpki-validator-3/db .\nln -s /srv/ripe-rpki-validator/db /srv/ripe-rpki-validator/rpki-validator-3/db\n\n# And do the same for rpki-rtr-server-3:\nmv rpki-rtr-server-3/conf/application.properties rpki-rtr-server-3.conf\nln -s /srv/ripe-rpki-validator/rpki-rtr-server-3.conf \\\n /srv/ripe-rpki-validator/rpki-rtr-server-3/conf/application.properties\n\n# again, ensure file ownership is okay\nchown -R ripe: /srv/ripe-rpki-validator\nWe then edit /srv/ripe-rpki-validator/rpki-validator-3.conf and change the following configuration options:
server.port and server.address if you want to access the web interface directly. Commenting server.address out makes it listen on all interfaces.spring.datasource.url to /srv/ripe-rpki-validator/db/rpki-validator.h2.And we edit /srv/ripe-rpki-validator/rpki-rtr-server-3.conf and:
server.port and server.address as required (note this is for the API, not the RTR protocol). server.address= listens on all interfaces.rtr.server.address and rtr.server.port as required (this is the RTR protocol). rtr.server.address=:: listens on all interfaces.You should now be able to start the Validator and RTR daemons:
# as the RIPE user\nsu - ripe\n\ncd /srv/ripe-rpki-validator/rpki-validator-3\n./rpki-validator-3.sh\n\ncd /srv/ripe-rpki-validator/rpki-rtr-server-3\n./rpki-rtr-server.sh\nWe need to manually install the ARIN TAL by:
/srv/ripe-rpki-validator/rpki-validator-3/upload-tal.sh arin-ripevalidator.tal http://localhost:8080/\nWe use systemd to ensure both daemons start automatically:
cat <<ENDL >/etc/systemd/system/rpki-validator-3.service\n[Unit]\nDescription=RPKI Validator\nAfter=network.target\n\n[Service]\nEnvironment=JAVA_CMD=/usr/bin/java\nExecStart=/srv/ripe-rpki-validator/rpki-validator-3/rpki-validator-3.sh\n\n# prevent restart in case there's a problem\n# with the database or binding to socket\nRestartPreventExitStatus=7\n\nUser=ripe\n\n[Install]\nWantedBy=multi-user.target\nENDL\n\nsystemctl enable rpki-validator-3.service\nsystemctl start rpki-validator-3.service\n\n\ncat <<ENDL >/etc/systemd/system/rpki-rtr-server-3.service\n[Unit]\nDescription=RPKI RTR\nAfter=rpki-validator-3.service\n\n[Service]\nEnvironment=JAVA_CMD=/usr/bin/java\nExecStart=/srv/ripe-rpki-validator/rpki-rtr-server-3/rpki-rtr-server.sh\n\n# prevent restart in case there's a problem\n# with the database or binding to socket\nRestartPreventExitStatus=7\n\nUser=ripe\n\n[Install]\nWantedBy=multi-user.target\nENDL\n\nsystemctl enable rpki-rtr-server-3.service\nsystemctl start rpki-rtr-server-3.service\nYou can see log messages using:
cat /var/log/syslog | grep rpki-validator\ncat /var/log/syslog | grep rpki-rtr\nWe separately add the server and the RIPE daemons to our standard monitoring and alerting tools.
"},{"location":"features/rpki/routinator/","title":"Routinator 3000","text":"Routinator 3000 is a RPKI relying party software (aka RPKI Validator) written in Rust by the good folks at NLnet Labs. These instructions reflect Routinator 0.8.2 (on Ubuntu 20.04). This mostly follows their own GitHub instructions and documentation.
We use a standard Ubuntu 20.04 installation (selecting the minimal virtual server option), 2 vCPUs, 2GB RAM, 20GB LVM hard drive.
Add the apt repo to the system by creating a file called /etc/apt/sources.list.d/routinator.list with the following contents:
deb [arch=amd64] https://packages.nlnetlabs.nl/linux/debian/ stretch main\ndeb [arch=amd64] https://packages.nlnetlabs.nl/linux/debian/ buster main\ndeb [arch=amd64] https://packages.nlnetlabs.nl/linux/ubuntu/ xenial main\ndeb [arch=amd64] https://packages.nlnetlabs.nl/linux/ubuntu/ bionic main\ndeb [arch=amd64] https://packages.nlnetlabs.nl/linux/ubuntu/ focal main\nThen add the NLNetLabs package key to the system:
sudo apt update && apt-get install -y gnupg2\nwget -qO- https://packages.nlnetlabs.nl/aptkey.asc | sudo apt-key add -\nsudo apt update\nNote that the first apt update will return a bunch of errors. The second update should run without errors, once the key has been added.
We then install the required software:
sudo apt install routinator\nsudo routinator-init\nAlternatively, if you plan to agree with the ARIN RPA, run:
sudo routinator-init --accept-arin-rpa\nBy default, Routinator listens only on TCP sockets on 127.0.0.1. If you want other devices to be able to access the service, it needs to listen to the wildcard socket.
If you're running Linux, you can configure Routinator to listen to both ipv4 and ipv6 wildcard sockets using the following configuration lines in /etc/routinator/routinator.conf:
rtr-listen = [ \"[::]:3323\" ]\nhttp-listen = [ \"[::]:8080\" ]\nIf you're running an operating system other than Linux, you'll need separate entries for ipv4 and ipv6:
rtr-listen = [ \"127.0.0.1:3323\", \"[::]:3323\" ]\nhttp-listen = [ \"127.0.0.1:8080\", \"[::]:8080\" ]\nYou can then test by running the following command, which prints the validated ROA payloads and increases the log level to show the process in detail:
/usr/bin/routinator --config /etc/routinator/routinator.conf -v vrps\nTo have this service start at boot:
systemctl enable routinator\nsystemctl start routinator\nWe add Nagios http checks for port 8080 (HTTP) to our monitoring platform. We also add a check_tcp test for the RPKI-RTR port 3323.
The following is copied from Routinator's man page. As a future work fixme, this should be used for better monitoring that just check_tcp above.
HTTP SERVICE\n Routinator can provide an HTTP service allowing to fetch the Validated\n ROA Payload in various formats. The service does not support HTTPS and\n should only be used within the local network.\n\n The service only supports GET requests with the following paths:\n\n\n /metrics\n Returns a set of monitoring metrics in the format used by\n Prometheus.\n\n /status\n Returns the current status of the Routinator instance. This is\n similar to the output of the /metrics endpoint but in a more\n human friendly format.\n\n /version\n Returns the version of the Routinator instance.\n\n /api/v1/validity/as-number/prefix\n Returns a JSON object describing whether the route announcement\n given by its origin AS number and address prefix is RPKI valid,\n invalid, or not found. The returned object is compatible with\n that provided by the RIPE NCC RPKI Validator. For more informa-\n tion, see https://www.ripe.net/support/documentation/developer-\n documentation/rpki-validator-api\n\n /validity?asn=as-number&prefix=prefix\n Same as above but with a more form-friendly calling convention.\n\n\n In addition, the current set of VRPs is available for each output for-\n mat at a path with the same name as the output format. E.g., the CSV\n output is available at /csv.\n\n These paths accept filter expressions to limit the VRPs returned in the\n form of a query string. The field filter-asn can be used to filter for\n ASNs and the field filter-prefix can be used to filter for prefixes.\n The fields can be repeated multiple times.\n\n This works in the same way as the options of the same name to the vrps\n command.\nThe OpenBSD project created a free and easy-to-use RPKI validator named rpki-client.
Deployment is split into two elements:
We use a standard Debian Sid (unstable) installation, 2 vCPUs, 2GB RAM, 20GB LVM hard drive. Debian provides pre-built packages for installation.
As of early March 2024, the following packages can easily be installed:
$ sudo apt install rpki-client stayrtr\nYou'll need to confirm whether you'd like to install the ARIN TAL.
You can now run the validator via the following command:
"},{"location":"features/rpki/rpkiclient/#rpki-client","title":"rpki-client","text":"# start the service:\nsystemctl start rpki-client &\n\n# see and tail the logs\njournalctl -fu rpki-client\nRunning rpki-client the first time might take a few minutes.
"},{"location":"features/rpki/rpkiclient/#stayrtr","title":"StayRTR","text":"To start StayRTR (once rpki-client is configured and running), we first edit /etc/default/stayrtr:
STAYRTR_ARGS=-bind :3323 -cache /var/lib/rpki-client/json -metrics.addr :8082\nYou can now run the StayRTR daemon via the following command:
# start the service:\nsystemctl restart stayrtr\n\n# see and tail the logs\njournalctl -fu stayrtr\nOnce rpki-client completed its initial run, and StayRTR starts up, metrics are available from http://[hostname/ip address]:8082/metrics.
"},{"location":"features/rpki/rpkiclient/#monitoring","title":"Monitoring","text":"We add Nagios http checks for and 8082 (StayRTR) to our monitoring platform. We also add a check_tcp test for StayRTR port 3323.
Rpki-client produces a statistics file in OpenMetrics format in /var/lib/rpki-client/metrics for use with Grafana.
This page discusses default permissions required for accessing certain graphs and well as details on how to change that.
"},{"location":"grapher/api/#accessibility-of-aggregate-graphs","title":"Accessibility of Aggregate Graphs","text":"By default, the following graphs are publicly accessible in IXP Manager and available through the top menu under Statistics:
If you wish to limit access to these to a less than or equal user permission, set the following in .env appropriately:
GRAPHER_ACCESS_IXPGRAPHER_ACCESS_INFRASTRUCTUREGRAPHER_ACCESS_LOCATIONGRAPHER_ACCESS_VLANGRAPHER_ACCESS_SWITCHGRAPHER_ACCESS_TRUNK (this also applies to core bundles)For example to limit access to trunks / core bundles to logged in users, set:
GRAPHER_ACCESS_TRUNK=1\nIf you would like to make the aggregate graphs available to logged in users only, set the following .env options:
GRAPHER_ACCESS_IXP=1\nGRAPHER_ACCESS_INFRASTRUCTURE=1\nGRAPHER_ACCESS_VLAN=1\nGRAPHER_ACCESS_SWITCH=1\nGRAPHER_ACCESS_LOCATION=1\nGRAPHER_ACCESS_TRUNK=1\nIf you would prefer to restrict access to these to superusers / admins only, replace =1 above with =3.
Grapher allows API access to graphs via a base URL of the form:
https://ixp.example.com/grapher/{graph}[?id=x][&period=x][&type=x][&category=x] \\\n [&protocol=x][&backend=x]\nHere's two quick examples from INEX's production system:
id=1&type=png).A sample of the JSON output is:
{\n \"class\": \"ixp\",\n \"urls\": {\n \"png\": \"https:\\/\\/www.inex.ie\\/ixp\\/grapher\\/ixp?period=day&type=png&category=bits&protocol=all&id=1\",\n \"log\": \"https:\\/\\/www.inex.ie\\/ixp\\/grapher\\/ixp?period=day&type=log&category=bits&protocol=all&id=1\",\n \"json\": \"https:\\/\\/www.inex.ie\\/ixp\\/grapher\\/ixp?period=day&type=json&category=bits&protocol=all&id=1\"\n },\n \"base_url\": \"https:\\/\\/www.inex.ie\\/ixp\\/grapher\\/ixp\",\n \"statistics\": {\n \"totalin\": 15013439801606864,\n \"totalout\": 15013959560329200,\n \"curin\": 158715231920,\n \"curout\": 158713872624,\n \"averagein\": 125566129180.59367,\n \"averageout\": 125570476225.09074,\n \"maxin\": 222438012592,\n \"maxout\": 222348641336\n },\n \"params\": {\n \"type\": \"json\",\n \"category\": \"bits\",\n \"period\": \"day\",\n \"protocol\": \"all\",\n \"id\": 1\n },\n \"supports\": {\n \"protocols\": {\n \"all\": \"all\"\n },\n \"categories\": {\n \"bits\": \"bits\",\n \"pkts\": \"pkts\"\n },\n \"periods\": {\n \"day\": \"day\",\n \"week\": \"week\",\n \"month\": \"month\",\n \"year\": \"year\"\n },\n \"types\": {\n \"png\": \"png\",\n \"log\": \"log\",\n \"json\": \"json\"\n }\n },\n \"backends\": {\n \"mrtg\": \"mrtg\"\n },\n \"backend\": \"mrtg\"\n}\nYou can see from the above what params were used to create the statistics (and would be used for the image if type=png), what parameters are supported (supports), what backends are available for the given graph type and mix of parameters, etc.
Notes:
json type to see what's supported but remember that IXP Manager will, when configured correctly, chose the appropriate backend;Let's first look at supported graphs:
ixp: aggregate graph for an IXP's overall traffic. id, which defaults to 1, is the primary key of the IXP from the ixp database table. As IXP Manager does not support multiple IXPs, this defaults to id=1. [Currently only supported via MRTG for protocol=all]
infrastructure: aggregate graph for the overall traffic on a specific IXP infrastructure. For many IXPs, they'll just have a single infrastructure and this will go unused as it would be the equivalent of ixp above. id, which is mandatory, is the primary key of the infrastructure from the infrastructure database table. [Currently only supported via MRTG for protocol=all]
vlan: aggregate graph for a specific VLAN. id, which is mandatory, is the primary key of the VLAN from the vlan database table. [Currently only supported via sflow for protocol=ipv4|ipv6 and category=bits|pkts]
location: aggregate graph of all peering traffic being switched by a specific facility (sum of all customer ports not including core ports). id, which is mandatory, is the primary key of the location / facility from the location database table. [Currently only supported via MRTG for protocol=all]. *Note that we are looking at all traffic originating and/or terminating at a location rather than traffic passing through it.
switch: aggregate graph of all peering traffic being switched by a specific switch (sum of all customer ports plus core ports). id, which is mandatory, is the primary key of the switch from the switch database table. [Currently only supported via MRTG for protocol=all]
core-bundle: inter-switch / trunk graphs configured in IXP Manager using the Core Bundles tool. The id is mandatory and is the database ID of the core bundle. An additional parameter is supported also: &side=a or &side=b which determines which side of the core bundle you want to graph. This parameter is optional and defaults to a. Each side of the graph will be about identical (only differing by MRTG polling time) but with tx/rx reversed. Access is determined using the GRAPHER_ACCESS_TRUNK.
trunk: a legacy hold over from Inter-Switch / Trunk Graphs above to be replaced with core bundles.
physicalinterface: traffic for an individual member port - a single physical switch port. id, which is mandatory, is the primary key of the physical interface from the physicalinterface database table. [Currently only supported via MRTG for protocol=all]
virtualinterface: if a member has a single connection (one switch port) then this is the same as physicalinterface above. However, if they have a LAG port then it's the aggregate traffic for all physical ports in the LAG. id, which is mandatory, is the primary key of the virtual interface from the virtualinterface database table. [Currently only supported via MRTG for protocol=all]
customer: the aggregate traffic for all ports belonging to a customer across all infrastructures. id, which is mandatory, is the primary key of the customer from the cust database table. [Currently only supported via MRTG for protocol=all]
vlaninterface: aggregate traffic flowing through a members VLAN interface for a specific protocol. id, which is mandatory, is the primary key of the VLAN interface from the vlaninterface database table. [Currently only supported via sflow for protocol=ipv4|ipv6]
latency: latency graphs (e.g. Smokeping). id, which is mandatory, is the primary key of the VLAN interface from the vlaninterface database table. protocol=ipv4|ipv6 is also mandatory. Periods for Smokeping are different to the default periods and should be one of 3hours|30hours|10days|1year.
p2p: peer to peer traffic between two member VLAN interfaces. The source (svli) and destination (dvli) VLAN interface IDs are required. svli and dvli, which are mandatory, are primary keys of the VLAN interfaces from the vlaninterface database table. [Currently only supported via sflow for protocol=ipv4|ipv6]
For additional options, it's always best to manually or programmatically examine the output for type=json to see what is supported. The following is a general list.
type: one of:
json - as demonstrated and described above;log - MRTG log file type output formatted as a JSON array;rrd - the RRD file for the requested graph type;png - the graph image itself (default).period: one of day, week, month, year (except for latency graphs as described above).
category: one of bits, pkts (packets), errs (errors), discs (discards), bcasts (broadcasts). Bits is measured in bits per second, the rest in packets per second.
protocol: one of all, ipv4 or ipv6.
backend: default is to let IXP Manager decide.
The grapher API can be accessed using the standard API access mechanisms.
Each graph (ixp, infrastructure, etc.) has an authorise() method which determines who is allowed view a graph. For example, see IXP\\Services\\Grapher\\Graph\\VlanInterface::authorise(). The general logic is:
For the supported graph types, default access control is:
Graph Default Access Controlixp public but respects GRAPHER_ACCESS_IXP (see above) infrastructure public but respects GRAPHER_ACCESS_INFRASTRUCTURE (see above) vlan public but respects GRAPHER_ACCESS_VLAN (see above), unless it's a private VLAN (in which case only superuser is supported currently) location public but respects GRAPHER_ACCESS_LOCATION (see above) switch public but respects GRAPHER_ACCESS_SWITCH (see above) core-bundle public but respects GRAPHER_ACCESS_TRUNK (see above) trunk public but respects GRAPHER_ACCESS_TRUNK (see above) physicalinterface superuser or user of the owning customer but respects GRAPHER_ACCESS_CUSTOMER (see Access to Member Graphs below) vlaninterface superuser or user of the owning customer but respects GRAPHER_ACCESS_CUSTOMER (see Access to Member Graphs below) virtualinterface superuser or user of the owning customer but respects GRAPHER_ACCESS_CUSTOMER (see Access to Member Graphs below) customer superuser or user of the owning customer but respects GRAPHER_ACCESS_CUSTOMER (see Access to Member Graphs below) latency superuser or user of the owning customer but respects GRAPHER_ACCESS_LATENCY (see Access to Member Graphs below) p2p superuser or user of the source (svli) owning customer but respects GRAPHER_ACCESS_P2P (see Access to Member Graphs below)"},{"location":"grapher/api/#access-to-member-graphs","title":"Access to Member Graphs","text":"NB: before you read this section, please first read and be familiar with the Accessibility of Aggregate Graphs section above.
A number of IXPs have requested a feature to allow public access to member / customer graphs. To support this we have added the following .env options (beginning in v4.8) with the default value as shown:
GRAPHER_ACCESS_CUSTOMER=\"own_graphs_only\"\nGRAPHER_ACCESS_P2P=\"own_graphs_only\"\nGRAPHER_ACCESS_LATENCY=\"own_graphs_only\"\nThe own_graphs_only setting just means perform the default access checks which are: access is granted to a superuser or a user who belongs to the customer which owns the respective graph. I.e. no one but the customer or a superadmin can access the respective graph.
If you wish to allow access to these to a less than or equal user permission, set the above in .env appropriately.
For example:
then set the following in .env:
GRAPHER_ACCESS_CUSTOMER=0\nGRAPHER_ACCESS_P2P=1\nNote that GRAPHER_ACCESS_LATENCY is omitted as we are not changing the default.
Please note the following:
GRAPHER_ACCESS_CUSTOMER applies to customer aggregate graphs, customer LAG graphs (virtualinterface), customer ports (physicalinterface) and customer vlaninterface. T individually limit these makes little sense and drastically increases complexity (from a UI perspectve).GRAPHER_ACCESS_P2P or GRAPHER_ACCESS_LATENCY without enabling equivalent or less restrictive access to GRAPHER_ACCESS_CUSTOMER. This is because most of the user interface (UI) pathways to access these is via GRAPHER_ACCESS_CUSTOMER pages.IXP Manager generates all of its graphs using its own graphing system called Grapher. This was introduced in v4.
Grapher is a complete rewrite of all previous graphing code and includes:
To date, we have developed the following reference backend implementations:
dummy - a dummy grapher that just provides a placeholder graph for all possible graph types;mrtg - MRTG graphing using either the log or rrd backend. Use cases for MRTG are L2 interface statistics for bits / packets / errors / discards / broadcasts per second. Aggregate graphs for customer LAGs, overall customer traffic, all traffic over a switch / infrastructure / the entire IXP are all supported;sflow - while the MRTG backend looks at layer 2 statistics, sflow is used to provide layer 3 statistics such as per protocol (IPv4/6) graphs and peer to peer graphs;smokeping - (available from v4.8.0) which creates latency graphs and this replaces the previous way we used to access Smokeping graphs.In a typical production environment, you would implement MRTG, Smokeping and sflow to provide the complete set of features.
"},{"location":"grapher/introduction/#configuration","title":"Configuration","text":"There are only a handful of configuration options required and a typical and complete $IXPROOT/.env would look like the following:
GRAPHER_BACKENDS=\"mrtg|sflow|smokeping\"\nGRAPHER_CACHE_ENABLED=true\n\nGRAPHER_BACKEND_MRTG_DBTYPE=\"rrd\"\nGRAPHER_BACKEND_MRTG_WORKDIR=\"/srv/mrtg\"\nGRAPHER_BACKEND_MRTG_LOGDIR=\"/srv/mrtg\"\n\nGRAPHER_BACKEND_SFLOW_ENABLED=true\nGRAPHER_BACKEND_SFLOW_ROOT=\"http://sflow-server.example.com/grapher-sflow\"\n\nGRAPHER_BACKEND_SMOKEPING_ENABLED=true\nGRAPHER_BACKEND_SMOKEPING_URL=\"http://smokeping-server.example.com/smokeping\"\nFor those interested, the complete Grapher configuration file can be seen in $IXPROOT/config/grapher.php. Remember: put your own local changes in .env rather than editing this file directly.
The global (non-backend specific) options are:
GRAPHER_BACKENDS - in a typical production environment this would be \"mrtg|sflow|smokeping\" which means try the MRTG backend first, then sflow and then smokeping. We ship with this set as \"dummy\" so you can see sample graphs working out of the box.GRAPHER_CACHE_ENABLED - the IXP industry standard for graphing is to graph at 5min intervals. With the cache enabled, IXP Manager does not have to regenerate / reload / reprocess log / rrd / image files if we have cached them and they are less than 5mins old. This is enabled by default which is the recommended setting.Backend specific configuration and set-up instructions can be found in their own sections below.
"},{"location":"grapher/mrtg/","title":"Backend: MRTG","text":"MRTG is used to generate interface graphs. MRTG is a particularly efficient SNMP poller as, irrespective of how many times an interface is referenced for different graphs, it is only polled once per run. If you want to understand MRTG related options in this section, please refer to MRTG's own documentation.
Per-second graphs are generated for bits, packets, errors, discards and broadcasts at 5min intervals. IXP Manager's Grapher system can use MRTG to poll switches and create traffic graphs for:
Aggregate IXP and Infrastructure Graphs
The MRTG script creates aggregate graphs for the entire IXP as well as per-infrastructure graphs. These graphs are available from the Statistics menu under Overall Peering Graphs. Also, the graphs on the admin dashboard are versions of these.
IXP and infrastructure graphs are aggregate graphs of edge / member ports only. It is the aggregate of traffic exchanged between the members of the IXP and thus does not include core / trunk ports between switches.
You'll find examples of IXP graphs and infrastructure graphs on INEX's own IXP Manager where they are public be default.
Per-Facility Aggregate Graphs
These are defined and built automatically from the locations / facilities you have defined and the switches you have assigned to them. These graphs are available from the Statistics menu under Facility Aggregate Graphs.
These graphs are the aggregate of all peering ports excluding core/trunk ports in a given location / facility. It is the aggregate of traffic originating and/or terminating in a location rather than traffic simply passing through a location.
You'll find examples of facility graphs on INEX's own IXP Manager where they are public be default.
Switch Aggregate Graphs
These are defined and built automatically from the switches you have defined. These graphs are available from the Statistics menu under Switch Aggregate Graphs.
These graphs are the aggregate of all peering ports and core/trunk ports on a given switch. It is the aggregate of traffic being exchanged across a given switch.
You'll find examples of switch graphs on INEX's own IXP Manager where they are public be default.
Inter-Switch / Trunk Graphs
From IXP Manager v6, this is now handled via Core Bundles. Please see the graphing section of the core bundles page for details.
For older versions of IXP Manager, it can be done manually via the config/grapher_trunks.php.dist file. This is now deprecated and will be removed during the lifetime of the v6 release.
In either case, these graphs will be available in the Statistics menu. You can see examples from INEX here.
Customer Graphs
MRTG creates: per port (physical interface); per LAG (virtual interface); and per customer aggregate graphs for each member / customer.
You need to install some basic packages for MRTG to work - on Ubuntu for example, install:
apt install rrdtool mrtg\nYou also need a folder to store all MRTG files. For example:
mkdir -p /srv/mrtg\nIn your `.env, you need to set the following options:
# The MRTG database type to use - either log or rrd:\nGRAPHER_BACKEND_MRTG_DBTYPE=\"rrd\"\n\n# Where to store log/rrd/png files. This is from the perspective\n# of the mrtg daemon and it is only used when generating the mrtg configuration\n# file so this should be a local path on whatever server mrtg will run:\nGRAPHER_BACKEND_MRTG_WORKDIR=\"/srv/mrtg\"\n\n# Where IXP Manager can fine the GRAPHER_BACKEND_MRTG_WORKDIR above. If mrtg is\n# running on the same server as IXP Manager, this this would just be the same:\nGRAPHER_BACKEND_MRTG_LOGDIR=\"/srv/mrtg\"\n# Note that if you wish to run MRTG on another server, you can expose the\n# WORKDIR on a HTTP server and provide a URL to this option:\n# GRAPHER_BACKEND_MRTG_LOGDIR=\"http://collector.example.com/mrtg\"\nYou can now generate a MRTG configuration by executing a command such as:
# Move to the directory where you have installed IXP Manager (typically: /srv/ixpmanager)\ncd $IXPROOT\n\n# Generate MRTG configuration and output to stdout:\nphp artisan grapher:generate-configuration -B mrtg\n\n# Generate MRTG configuration and output to a named file:\nphp artisan grapher:generate-configuration -B mrtg -O /tmp/mrtg.cfg.candidate\nYou could also combine a syntax check before putting the resultant file live. Here's a complete example that could be run via cron:
#! /usr/bin/env bash\n\n# Set this to the directory where you have installed IXP Manager (typically: /srv/ixpmanager)\nIXPROOT=/srv/ixpmanager\n\n# Temporary configuration file:\nTMPCONF=/tmp/mrtg.cfg.$$\n\n# Synchronize configuration files\n${IXPROOT}/artisan grapher:generate-configuration -B mrtg -O $TMPCONF\n\n# Remove comments and date/time stamps for before comparing for differences\ncat /etc/mrtg.cfg | egrep -v '^#.*$' | \\\n egrep -v '^[ ]+Based on configuration last generated by.*$' >/tmp/mrtg.cfg.filtered\ncat $TMPCONF | egrep -v '^#.*$' | \\\n egrep -v '^[ ]+Based on configuration last generated by.*$' >${TMPCONF}.filtered\ndiff /tmp/mrtg.cfg.filtered ${TMPCONF}.filtered >/dev/null\nDIFF=$?\n\nrm /tmp/mrtg.cfg.filtered\nrm ${TMPCONF}.filtered\n\nif [[ $DIFF -eq 0 ]]; then\n rm ${TMPCONF}\n exit 0\nfi\n\n/usr/bin/mrtg --check ${TMPCONF} \\\n && /bin/mv ${TMPCONF} /etc/mrtg.cfg \\\n && /etc/rc.d/mrtg_daemon restart > /dev/null\nIf your MRTG collector is on a different server, you could use a script such as the following to safely update MRTG via IXP Manager's API.
#! /usr/bin/env bash\n\n# Temporary configuration file:\nTMPCONF=/etc/mrtg.cfg.$$\n\n# Download the configuration via the API. Be sure to replace 'your_api_key'\n# with your actual API key (see API documentation).\ncurl --fail -s -H \"X-IXP-Manager-API-Key: your_api_key\" \\\n https://ixp.example.com/api/v4/grapher/mrtg-config >${TMPCONF}\n\nif [[ $? -ne 0 ]]; then\n echo \"WARNING: COULD NOT FETCH UP TO DATE MRTG CONFIGURATION!\"\n exit -1\nfi\n\ncd /etc\n\n# Remove comments and date/time stamps for before comparing for differences\ncat mrtg.cfg | egrep -v '^#.*$' | \\\n egrep -v '^[ ]+Based on configuration last generated by.*$' >mrtg.cfg.filtered\ncat ${TMPCONF} | egrep -v '^#.*$' | \\\n egrep -v '^[ ]+Based on configuration last generated by.*$' >${TMPCONF}.filtered\ndiff mrtg.cfg.filtered ${TMPCONF}.filtered >/dev/null\nDIFF=$?\n\nrm mrtg.cfg.filtered\nrm ${TMPCONF}.filtered\n\nif [[ $DIFF -eq 0 ]]; then\n rm ${TMPCONF}\n exit 0\nfi\n\n/usr/bin/mrtg --check ${TMPCONF} && /bin/mv ${TMPCONF} /etc/mrtg.cfg\n\n\n\n/usr/bin/mrtg --check ${TMPCONF} \\\n && /bin/mv ${TMPCONF} /etc/mrtg.cfg \\\n && /etc/rc.d/mrtg_daemon restart > /dev/null\nNote that the MRTG configuration that IXP Manager generates instructs MRTG to run as a daemon. On FreeBSD, MRTG comes with an initd script by default and you can kick it off on boot with something like the following in /etc/rc.conf:
mrtg_daemon_enable=\"YES\"\nmrtg_daemon_config=\"/etc/mrtg.cfg\"\nOn Ubuntu it does not but it comes with a /etc/cron.d/mrtg file which kicks it off every five minutes (it will daemonize the first time and further cron jobs will have no effect).
Marco d'Itri provided Ubuntu / Debian compatible systemd configurations for mrtg which you can find detailed in this Github issue.
To start and stop it via the older initd scripts on Ubuntu, use an initd script such as this: ubuntu-mrtg-initd (source):
cp ${IXPROOT}/tools/runtime/mrtg/ubuntu-mrtg-initd /etc/init.d/mrtg\nchmod +x /etc/init.d/mrtg\nupdate-rc.d mrtg defaults\n/etc/init.d/mrtg start\nAnd disable the default cron job for MRTG on Ubuntu (/etc/cron.d/mrtg).
Generally speaking, you should not customize the way IXP Manager generates MRTG configuration as the naming conventions are tightly coupled to how IXP Manager fetches the graphs. However, if there are bits of the MRTG configuration you need to alter, you can do it via skinning. The skinning documentation actually uses MRTG as an example.
"},{"location":"grapher/mrtg/#inserting-traffic-data-into-the-database-reporting-emails","title":"Inserting Traffic Data Into the Database / Reporting Emails","text":"The MRTG backend inserts daily summaries into MySQL for reporting. See the traffic_daily and traffic_daily_phys_ints database tables for this. Essentially, there is a row per day per customer in the first and a row per physical interface in the second for traffic types bits, discards, errors, broadcasts and packets. Each row has a daily, weekly, monthly and yearly value for average, max and total.
From IXP Manager >= v5.0, the task scheduler handles collecting and storing yesterday's data. If you are using an older version, create a cron job such as:
0 2 * * * www-data /srv/ixpmanager/artisan grapher:upload-stats-to-db\n5 2 * * * www-data /srv/ixpmanager/artisan grapher:upload-pi-stats-to-db\nIn the IXP Manager application, the traffic_daily data powers the League Table function and the traffic_daily_phys_int data powers the Utilisation (since v5.5.0) function - both on the left hand menu.
This data is also used to send email reports / notifications of various traffic events. A sample crontab for this would look like the following:
0 4 * * * www-data /srv/ixpmanager/artisan grapher:email-traffic-deltas \\\n --stddev=1.5 -v user1@example.com,user2@example.com\n\n30 10 * * tue www-data /srv/ixpmanager/artisan grapher:email-port-utilisations \\\n --threshold=80 user1@example.com,user2@example.com\n\n31 10 * * * www-data /srv/ixpmanager/artisan grapher:email-ports-with-counts \\\n --discards user1@example.com,user2@example.com\n\n32 10 * * * www-data /srv/ixpmanager/artisan grapher:email-ports-with-counts \\\n --errors user1@example.com,user2@example.com\nWhich, in the order above, do:
traffic_daily_phys_ints table).This generated emails are HTML formatted with embedded graph images.
"},{"location":"grapher/mrtg/#port-utilisation","title":"Port Utilisation","text":"In IXP Manager v5.5.0, we introduced a port utilisation reporting function into IXP Manager's frontend UI. You will find it in the IXP STATISTICS section of the left hand side menu.
The purpose of this tool is to easily identify ports that are nearing or exceeding 80% utilisation. In its default configuration, IXP Manager will iterate over all the physical interface (switch ports) MRTG log files for every member and insert that information into the database at 02:10 (AM).
In the UI, when you select a specific date and period (day/week/month/year), you are shown the maximum port utilisation (in and out) for the given period up to 02:10 on that day.
This feature was introduced in March 2020 during the Coronavirus outbreak. After observing as much as 50% routine traffic increases across IXPs in areas under lock down, we needed a tool that would allow us to rapidly and easily view port utilisations across all members rather than looking at member graphs individually.
"},{"location":"grapher/mrtg/#troubleshooting","title":"Troubleshooting","text":""},{"location":"grapher/mrtg/#general-notes","title":"General Notes","text":"A common issue raised on the mailing list is missing customer graphs. The code which generates MRTG configuration is in the MRTG backend file (see the function getPeeringPorts()).
The conditions for a physical interface allocated to a customer to make the configuration file are:
If you are not sure about how ports are configured in IXP Manager, please see the interfaces document.
You can check the physical interface state by:
You can ensure a switch is active by:
Instructions for configuring the IXP Manager sflow integration can be found on the Sflow Introduction and Sflow peer-to-peer pages.
"},{"location":"grapher/smokeping/","title":"Backend: Smokeping","text":"Latency graphs are a tool for monitoring latency / packet loss to the routers of IXP partipants and they can be an invaluable asset when diagnosing many IXP issues.
While they should never be used as a tool for monitoring IXP latency or packet loss (as routers de-prioritise ICMP requests and/or may not have a suitably powerful management plane), they can act as an extremely useful tool for identifying and diagnosing customer / member issues. What we really look for here is recent changes over time.
IXP Manager can configure Smokeping to monitor member routers and display those graphs in member statistic pages. Presuming it is installed.
"},{"location":"grapher/smokeping/#historical-notes","title":"Historical Notes","text":"If you have used Smokeping on IXP Manager <v4.5 or between v4.5 and v4.7.3, then how the configuration is generated has changed.
This section explains the rules on how a member router (target) is selected to be included in the generated Smokeping configuration.
When generating a list of targets per VLAN and protocol, the API call to IXP Manager will select all VLAN interfaces (member routers) where:
You can use the IXP Manager API to get the Smokeping target configurations for a given VLAN and protocol using the following endpoint format (both GET and POST requests work):
https://ixp.example.com/api/v4/grapher/config?backend=smokeping&vlanid=10&protocol=ipv4\nNote that in versions of IXP Manager between v4.5 and v4.7.3, this was: https://ixp.example.com/api/v4/vlan/smokeping/{vlanid}/{protocol}.
In the above, the parameters are:
vlanid is the database ID (DB ID) of the VLAN. You can find the DB ID in IXP Manager in the VLAN table (select VLANs from the left hand side menu).protocol is either ipv4 or ipv6 (while in versions between v4.5 and v4.7.3, these were just 4 and 6 respectfully).If either of these are invalid, the API will return with a HTTP 404 response.
And example of a Smokeping target in the response is:
# AS112 Reverse DNS / 185.6.36.6\n+++ vlanint_86_ipv4\nmenu = AS112 Reverse DNS (IPv4)\ntitle = Peering VLAN #1 :: AS112 Reverse DNS via 185.6.36.6\nprobe = FPing\nhost = 185.6.36.6\nYou can optionally POST any of the above parameters and none, one or both of the following to change elements of the default template:
level: the Smokeping level / hierarchy of the target. Defaults to +++.probe: the probe to use when measuring latency to the target. Defaults for FPing for IPv4 and FPing6 for IPv6.An example of changing these parameters is:
curl --data \"backend=smokeping&protocol=ipv4&vlanid=10&level=%2B%2B&probe=MyPing\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/grapher/config\nYou can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called mytemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/services/grapher/smokeping\ncp resources/views/services/grapher/smokeping/default.foil.php \\\n resources/skins/myskin/services/grapher/smokeping/mytemplate1.foil.php\nYou can now edit this template as required. The only constraint on the template name is it can only contain characters from the classes a-z, 0-9, -. NB: do not use uppercase characters.
The following variables are available in the template:
$t->vlis: array of the VLAN interfaces/targets - it is generated by the Repositories\\VlanInterface::getForProto() function.$t->vlan: instance of the Vlan entity object.$t->protocol: either 4 or 6.$t->probe and $t->level as defined above / passed via a post request.This section explains how to set up Smokeping with IXP Manager. We assume you already have a base install of Smokeping.
"},{"location":"grapher/smokeping/#generating-updating-targets","title":"Generating / Updating Targets","text":"At INEX, we would use a script such as this one which is bundled with IXP Manager to (re)generate our targets by cron and update Smokeping if necessary.
To use this script yourself, you just need to copy it to the appropriate Smokeping server and edit the first few lines:
KEY=\"my-ixp-manager-api-key\"\nURL=\"https://ixp.example.com/api/v4/grapher/config?backend=smokeping\"\nETCPATH=\"/etc/smokeping\"\nSMOKEPING=\"/usr/bin/smokeping\"\nSMOKEPING_RELOAD=\"/etc/rc.d/smokeping reload\"\nVLANS=\"1 2\"\nPROTOCOLS=\"ipv4 ipv6\"\nwhere:
KEY is your IXP Manager API key.URL is the API endpoint as described above.ETCPATH is where the script puts the target files (named $ETCPATH/targets-vlan${vlanid}-${proto}.cfg)SMOKEPING is the Smokeping binary command. Just used to validate the config with --check before reloading.SMOKEPING_RELOAD - the command to reload Smokeping.VLANS - space separated list of VLAN DB IDs as described above. You probably only have one of these typically.PROTOCOLS - the protocols to generate the configuration for.The script iterates over the VLAN IDs and protocols to create the individual configuration files.
"},{"location":"grapher/smokeping/#using-targets-in-smokeping","title":"Using Targets in Smokeping","text":"Once the above target file(s) are created, we can use them in our standard Smokeping configuration file as follows:
+ infra_1\nmenu = IXP Infrastructure 1\ntitle = IXP Infrastructure 1\n\n\n++ vlan_1\nmenu = Peering VLAN 1\ntitle = IXP Infra 1 :: Peering VLAN 1\n\n\n@include targets-vlan1-ipv4.cfg\n@include targets-vlan1-ipv6.cfg\nYou need to be able to configure IXP Manager with the base Smokeping URL such as http://www.example.com/smokeping. This should be the URL to the standard entry page to Smokeping.
IXP Manager will add the trailing slash and assume the directory index is configured for the CGI script. Thus you need an Apache configuration such as:
ScriptAlias /smokeping/smokeping.cgi /usr/lib/cgi-bin/smokeping.cgi\nAlias /smokeping /usr/share/smokeping/www\n\n<Directory \"/usr/share/smokeping/www\">\n Options FollowSymLinks\n DirectoryIndex smokeping.cgi\n</Directory>\nOnce you have configured Smokeping and Apache/web server as above, you really just need to set the following in your IXP Manager .env file:
# Add smokeping to the grapher backends:\nGRAPHER_BACKENDS=\"...|smokeping|...\"\n\n# Mark it as enabled (this just affects whether certain UI elements are shown):\nGRAPHER_BACKEND_SMOKEPING_ENABLED=true\n\n# And set the default location to fetch the Smokeping graphs from:\nGRAPHER_BACKEND_SMOKEPING_URL=\"http://www.example.com/smokeping\"\nwhere the URL is as you set up in Apache above.
There may be instances where you have multiple VLANs where it is not possible to have a single Smokeping instance graph latency for all of them. Particularly as the Smokeping daemon for a given VLAN needs to have an interface / IP address on that VLAN.
INEX has such a situation where we have a regional exchange, INEX Cork, that is located in a different city to the main INEX LANs and IXP Manager. In this situation, you can configure Smokeping URL overrides on a per VLAN basis by creating a file called $IXPROOT/config/grapher_smokeping_overrides.php which returns an array as follows:
<?php\n\nreturn [\n\n 'per_vlan_urls' => [\n 2 => 'http://www.example.com/smokeping',\n 4 => 'http://www.example2.com/smokeping',\n ],\n\n];\nwhere the array index (2 and 4 in the above example) is the VLAN DB ID as explained above.
Any VLANs without a specific override configured in this way will fall back to the GRAPHER_BACKEND_SMOKEPING_URL setting.
When configured correctly, there will be a latency button available (clock icon) in the member graphs in both the member and admin sections.
"},{"location":"grapher/smokeping/#troubleshooting","title":"Troubleshooting","text":"See issue #122 for a discussion on Ubuntu installation and diagnosing issues in general (relates to IXP Manager v3 but may still be useful).
IXP Manager will call something like the following to fetch graphs from Smokeping:
file_get_contents( 'https://www.example.com/smokeping/?.....' )\nYou should see these requests to Smokeping in your Smokeping web server log files. Find these and compare them to the URLs that Smokeping itself generates for its own display of the images to ensure you have everything - and especially the Smokeping URL in IXP configuration set up correctly.
Also, try testing these URLs directly on the IXP Manager server via:
php -r 'echo file_get_contents( \"https://...\" );'\nWe've tried our best to make installing IXP Manager as easy as possible via the install script(s) we provide. These scripts are opinionated about what version of Linux is used and how IXP Manager is installed. It's targeted at people who don't have a huge amount of system administration skills or want to take a quick look to evaluate the product.
If you want to install on your own preferred platform or with your own tweaks, we provide detailed instructions below also but we only offer whatever support you'll find on the public mailing list.
The installation of IXP Manager doesn't end when you have the web interface up and running (which is mostly what we cover in this section and the installation script) - that's really just the beginning. Completing the installation is about all the features that work around and via IXP Manager such as route server configurations, graphing, peer to peer graphs via sflow, etc. Each of these require different amounts of effort and are covered in their individual feature pages.
"},{"location":"install/automated-script/","title":"Automated Installation Script","text":"The available installation script(s) can be found at: https://github.com/inex/IXP-Manager/tree/master/tools/installers.
Even if you choose not to use these, the scripts under the above link show the accurate and complete installation process and should be used as a reference guide.
What next? See our post-install / next steps document here.
"},{"location":"install/automated-script/#video-tutorial","title":"Video Tutorial","text":"We created a video tutorial demonstrating the installation process using the automated script for IXP Manager v5.5.0 (April 2020) on Ubuntu LTS 20.04.
The procedure is similar for v6.0 - just be sure to use the ubuntu-lts-2004-ixp-manager-v6.sh script.
You can find the video here in our YouTube channel. As always, the full catalog of video tutorials is here.
"},{"location":"install/considerations/","title":"Technical Considerations","text":"While most updates of IXP Manager are quick, some may be more involved with schema updates or complicated migration steps. In these cases it's useful and advisable to put IXP Manager in maintenance mode.
Maintenance mode is now handled by Laravel's built in tool for this. You can review their own documentation for this which us copied here.
When your application is in maintenance mode, a custom view will be displayed for all requests into your application. This makes it easy to \"disable\" your application while it is updating or when you are performing maintenance. A maintenance mode check is included in the default middleware stack for your application. If the application is in maintenance mode, a MaintenanceModeException will be thrown with a status code of 503.
To enable maintenance mode, simply execute the down Artisan command:
php artisan down\nYou may also provide message and retry options to the down command. The message value may be used to display or log a custom message, while the retry value will be set as the Retry-After HTTP header's value::
php artisan down --message='Upgrading Database' --retry=60\nTo disable maintenance mode, use the up command::
php artisan up\nWe created a video tutorial demonstrating the manual installation process for IXP Manager v6.0.0 (July 2021) on Ubuntu LTS 20.04. You can find the latest installation videos. As always, the full catalog of video tutorials is here.
"},{"location":"install/manually/#requirements","title":"Requirements","text":"IXP Manager tries to stay current in terms of technology. Typically, this means some element of framework refresh(es) every couple of years and other more incremental package upgrades with minor version upgrades. As well as the obvious reasons for this, there is also the requirement to prevent developer apathy - insisting on legacy frameworks and packages that have been EOL'd provides a major stumbling block for bringing on new developers and contributors.
The current requirements for the web application are:
To complete the installation using the included config/scripts, you will also need to have installed git (apt install git) and a number of PHP extensions (see the example apt install below).
Regrettably the potential combinations of operating systems, versions of same and then versions of PHP are too numerous to provide individual support. As such, we recommend installing IXP Manager on Ubuntu LTS 20.04 and we officially support this platform.
In fact, we provide a complete installation script for this - see the automated installation page for details. If you have any issues with the manual installation, the automated script should be your first reference to compare what you are doing to what we recommend.
For completeness, the IXP Manager installation script for Ubuntu 20.04 LTS installs:
apt install -qy apache2 php8.0 php8.0-intl php8.0-rrd php8.0-cgi php8.0-cli \\\n php8.0-snmp php8.0-curl php8.0-memcached libapache2-mod-php8.0 mysql-server \\\n mysql-client php8.0-mysql memcached snmp php8.0-mbstring php8.0-xml php8.0-gd \\\n php8.0-bcmath bgpq3 php8.0-memcache unzip php8.0-zip git php8.0-yaml \\\n php8.0-ds libconfig-general-perl libnetaddr-ip-perl mrtg libconfig-general-perl \\\n libnetaddr-ip-perl rrdtool librrds-perl curl composer \nDo note that Ubuntu 20.04 LTS comes with PHP 7.4 so you must enable Ond\u0159ej Sur\u00fd's excellent Ubuntu PHP PPA (and maybe buy him a pint). This can be enabled with:
apt-get install -yq software-properties-common\nadd-apt-repository -y ppa:ondrej/php\nIf you are using a different platform, you will need to replicate the above as appropriate for your chosen platform.
"},{"location":"install/manually/#get-the-ixp-manager-source","title":"Get the IXP Manager Source","text":"The code for IXP Manager is maintained on GitHub and the canonical repository is inex/IXP-Manager.
Log into the server where you wish to install IXP Manager. Move to the directory where you wish to store the source (the automated script, our documentation and our examples use /srv/ixpmanager which we refer to as $IXPROOT). Note that it should not be cloned into any web exposed directory (e.g. do not clone to /var/www).
IXPROOT=/srv/ixpmanager\ncd /srv\ngit clone https://github.com/inex/IXP-Manager.git ixpmanager\ncd $IXPROOT # /srv/ixpmanager\ngit checkout release-v6\nchown -R www-data: bootstrap/cache storage\nInstall the required PHP libraries:
First you will need Composer v2 but v1 ships with Ubuntu 20.04. Composer is PHP's package manager and you can download and install it per the copy and paste instructions here (always satisfy yourself with the trustworthiness of the source when downloading and executing scripts).
We assume you downloaded it to $IXPROOT as composer.phar in the following:
cd $IXPROOT\nphp composer.phar install --no-dev --prefer-dist\ncp .env.example .env\nphp artisan key:generate\nUse whatever means you like to create a database and user for IXP Manager. For example:
CREATE DATABASE `ixpmanager` CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_unicode_ci';\nCREATE USER `ixpmanager`@`localhost` IDENTIFIED BY '<pick a password!>';\nGRANT SUPER ON *.* TO `ixpmanager`@`localhost`;\nGRANT ALL ON `ixpmanager`.* TO `ixpmanager`@`localhost`;\nGRANT SUPER ON *.* TO `ixpmanager`@`localhost`;\nFLUSH PRIVILEGES;\nThen edit $IXPROOT/.env and set the database options:
DB_HOST=localhost\nDB_DATABASE=ixpmanager\nDB_USERNAME=ixpmanager\nDB_PASSWORD=<the password you picked above!>\nNow create the database schema:
php artisan migrate\n# Run it twice for completeness\nphp artisan migrate\nSome older scripts still rely on MySQL view tables. Create these with:
# We use root here as the views.sql also contain triggers\nmysql -u root ixpmanager < $IXPROOT/tools/sql/views.sql\nEdit $IXPROOT/.env and review and set/change all parameters. Hopefully this is mostly documented or clear but please start a discussion on the mailing list if you have difficultly and we'll update this and the example file's documentation as appropriate.
Using the settings you edited in .env we'll create some database objects. [Yes, a setup wizard needs to be built!].
First let's create the password for the admin user. The following will create a secure random password and hash it with bcrypt:
cd $IXPROOT\nsource .env\nUSERNAME=admin\nUSEREMAIL=your@email.address\nIXPM_ADMIN_PW=\"$( openssl rand -base64 12 )\"\nADMIN_PW_SALT=\"$( openssl rand -base64 16 )\"\nHASH_PW=$( php -r \"echo escapeshellarg( crypt( '${IXPM_ADMIN_PW}', sprintf( '\\$2a\\$%02d\\$%s', 10, substr( '${ADMIN_PW_SALT}', 0, 22 ) ) ) );\" )\necho Your password is: $IXPM_ADMIN_PW\n\nNAME=\"Joe\"\nIXPNAME=SCIX\nIXPSNAME=SCIX\nIXPASN=65500\nIXPPEEREMAIL=peering@example.com\nIXPNOCPHONE=12345678\nIXPNOCEMAIL=noc@example.com\nIXPWWW=\"http://www.example.com\"\nThe following is taken from the IXP Manager installation script:
mysql -h $DB_HOST -u $DB_USERNAME \"-p${DB_PASSWORD}\" $DB_DATABASE <<END_SQL\nINSERT INTO infrastructure ( name, shortname, isPrimary, created_at, updated_at )\n VALUES ( 'Infrastructure #1', '#1', 1, NOW(), NOW() );\nSET @infraid = LAST_INSERT_ID();\n\nINSERT INTO company_registration_detail ( registeredName, created_at, updated_at ) VALUES ( '${IXPNAME}', NOW(), NOW() );\nSET @crdid = LAST_INSERT_ID();\n\nINSERT INTO company_billing_detail ( billingContactName, invoiceMethod, billingFrequency, created_at, updated_at )\n VALUES ( '${NAME}', 'EMAIL', 'NOBILLING', NOW(), NOW() );\nSET @cbdid = LAST_INSERT_ID();\n\nINSERT INTO cust ( name, shortname, type, abbreviatedName, autsys, maxprefixes, peeringemail, nocphone, noc24hphone,\n nocemail, nochours, nocwww, peeringpolicy, corpwww, datejoin, status, activepeeringmatrix, isReseller,\n company_registered_detail_id, company_billing_details_id, created_at, updated_at )\n VALUES ( '${IXPNAME}', '${IXPSNAME}', 3, '${IXPSNAME}', ${IXPASN}, 100, '${IXPPEEREMAIL}', '${IXPNOCPHONE}',\n '${IXPNOCPHONE}', '${IXPNOCEMAIL}', '24x7', '', 'mandatory', '${IXPWWW}', NOW(), 1, 1, 0, @crdid, @cbdid, NOW(), NOW() );\nSET @custid = LAST_INSERT_ID();\n\nINSERT INTO user ( custid, name, username, password, email, privs, disabled, created_at, updated_at )\n VALUES ( @custid, '${NAME}', '${USERNAME}', ${HASH_PW}, '${USEREMAIL}', 3, 0, NOW(), NOW() );\nSET @userid = LAST_INSERT_ID();\n\nINSERT INTO customer_to_users ( customer_id, user_id, privs, created_at, updated_at )\n VALUES ( @custid, @userid, 3, NOW(), NOW() );\n\nINSERT INTO contact ( custid, name, email, created_at, updated_at )\n VALUES ( @custid, '${NAME}', '${USEREMAIL}', NOW(), NOW() );\nEND_SQL\nAnd finally seed the database:
cd $IXPROOT\nphp artisan db:seed --force --class=IRRDBs\nphp artisan db:seed --force --class=Vendors\nphp artisan db:seed --force --class=ContactGroups\nThe web server needs write access to some directories:
cd $IXPROOT\nchown -R www-data: storage/ bootstrap/cache/\nchmod -R u+rwX storage/ bootstrap/cache/\nHere is a sample virtual hosts file for IXP Manager (replace {$IXPROOT} as appropriate!):
<VirtualHost *:80>\n ServerAdmin webmaster@localhost\n DocumentRoot ${IXPROOT}/public\n <Directory ${IXPROOT}/public>\n Options FollowSymLinks\n AllowOverride None\n Require all granted\n RewriteEngine On\n RewriteCond %{REQUEST_FILENAME} -s [OR]\n RewriteCond %{REQUEST_FILENAME} -l [OR]\n RewriteCond %{REQUEST_FILENAME} -d\n RewriteRule ^.*$ - [NC,L]\n RewriteRule ^.*$ /index.php [NC,L]\n </Directory>\n ErrorLog \\${APACHE_LOG_DIR}/error.log\n CustomLog \\${APACHE_LOG_DIR}/access.log combined\n</VirtualHost>\nYou also need to enable rewrite:
a2enmod rewrite\nservice apache2 restart\nYour new IXP Manager installation should be accessible via your server's IP address using the username ($USERNAME) and password ($IXPM_ADMIN_PW) you set above.
If you plan to use this in production, you should:
operations <at> inex <dot> ie.What next? See our post-install / next steps document here.
"},{"location":"install/next-steps/","title":"Post-Install / Next Steps","text":"So you have installed IXP Manager, congratulations! But now you are wondering what to do next?
Hopefully this document will point you in the right direction to help you start using IXP Manager. Note that we assume you have used the automated installer and so you have a single customer already in the database - the IXP's own customer.
"},{"location":"install/next-steps/#essential-steps-set-up-the-ixp","title":"Essential Steps - Set Up the IXP","text":"We created a video tutorial demonstrating these steps. You can find the video here in our YouTube channel. As always, the full catalog of video tutorials is here.
There are basic elements you need to add to IXP Manager which describe your IXP and are required for standard usage. Most of these actions can be found under the IXP ADMIN ACTIONS on the left hand side menu.
Remember: most of the forms for adding and editing the following entities have context help on each input field via the green Help button.
create your infrastructures. Generally, an infrastructure represents a collection of switches which form an IXP's peering LAN. The best way to think of an infrastructure is to think of it as an IXP.
For example, INEX runs three infrastructures - INEX LAN1, INEX LAN2 and INEX Cork. Each of these consist of a unique set of switches and these infrastructures are not interconnected. They also have unique PeeringDB entries (INEX LAN1, INEX LAN2, INEX Cork) and IX-F entries (INEX LAN1, INEX LAN2, INEX Cork) for each infrastructure.
If you do not have a PeeringDB entry yet, then register and create one. Similarly, if you do not have an IX-F entry, email the IXPDB admins via ixpdb-admin <at> euro-ix.net with your IX's full name, short name, city / region / country, GPS coordinates and website URL.
Add your facilities (points of presence - the data centres where networks can connect to one of your IX switches).
Add your racks. You will need this later to add patch panels and switches for example.
You can now add switches. We have good documentation for this here. It is important to note that the IXP Manager server will need SNMP (v2) access to your switches and your switches should have a domain name registered in DNS. Avoid using IP addresses here.
IXP Manager will query your switch via SNMP and discover its details as well as setting up all the switch ports in the database.
Add your VLAN(s). We would recommend two VLANs per infrastructure for peering purposes:
When adding your production peering VLAN, you will want to check the Include VLAN in the peering matrix (see help) option and the Include VLAN in the peering manager (see help) option.
Add Network Information for the peering LAN also. The Network Information is a submenu under the VLANs menu option.
Add your peering IP addresses. IXP Manager will let you add complete ranges (e.g. /24) and more sensible ranges of IPv6 (i.e. not an entire /64!).
Ensure email is correctly configured.
Now, a very important next step: let us know you are using IXP Manager so we can add you to the community map. You can complete the online form or get more details here.
The above constitutes the basic elements that are required to provision a customer.
For documentation on adding and managing customers, see here. And for details on provisioning interfaces for your customers, see here.
"},{"location":"install/next-steps/#feature-checklist","title":"Feature Checklist","text":"The above section lists the essential set-up elements. Beyond those, IXP Manager has many features that require a little extra effort to set up as there is a manual element to many of them. What follows is a check list of these features:
Graphing (documentation) - at a minimum you will want to set up interface graphs via mrtg. You should also look at peer to peer graphing via sflow and latency graphing via Smokeping.
Routers - see the generic documentation here. Then remember that no IX is complete without route servers with IRRDB and RPKI filtering. We would highly recommend a route collector on each infrastructure.
And while we're talking routers - consider an AS112 service.
You should also set-up the looking glass functionality on these servers. This is used to provide a looking glass to IX operators and members, for monitoring, for prefix filtering tools, etc.
Make sure you have set up IXP Manager's cron job.
Use the cross connect / patch panel management features. As your IX grows and you end up with tens or hundreds of these you will profoundly regret it if you haven't used this feature from day one.
Use IXP Manager to automate your PTR ARPA records for member assigned IP addresses on the peering LAN.
Set-up your IX-F export and let ixpdb-admin (at) euro-ix (dot) net know about it.
If you are not statically configuring / using static l2acls for MAC addresses, then set up MAC address discover.
Configure Nagios monitoring.
Enable the member facing Peering Manager.
Consider setting up BGP session discovery via sflow for the peering matrix.
Set up your PeeringDB account in IXP Manager to enable all features including ease of adding customers.
Allow IXP Manager to maintain your RIR objects automatically.
You may want to skin some of the templates. However, in the main, we would advise keeping this to a minimum or upgrades will become more complicated. Especially if you skin complex / core templates around functionality. There are some templates we do recommend you skin immediately:
the support details page.
Add any static content you require.
Automation - if you're so inclined to look at switch automation, see INEX's templates here (Arista and Cumulus).
As you look through the above, do please note that we have given a lot of presentations over the years and many are linked here with video.
Happy peering!
"},{"location":"install/register/","title":"Join the Community","text":"It really helps the core IXP Manager team at INEX to know that the community is growing. Every new user builds our momentum to keep developing and supporting the platform.
We maintain a a community map and statistics that are updated nightly.
To join our community and get on the map, you can complete this online form.
If you don't have an IX-F ID or a PeeringDB ID that's fine, just leave those blank. You can register with PeeringDB yourself and we'll help out with an IX-F ID when you register with us.
If you have any questions about this, please reach out to us by email to operations <at> inex.ie.
If you are running IXP Manager behind a load balancer / proxy that terminates TLS / SSL connections, you may notice your application sometimes does not generate HTTPS links. Typically this is because your application is being forwarded traffic from your load balancer on port 80 and does not know it should generate secure links.
From v4.7.2, IXP Manager supports trusted proxies via Laravel's support for fideloper/TrustedProxy.
See the above links for complete documentation. To just get it working, you need to:
Publish the default trusted proxies configuration file:
cd $IXPROOT\n./artisan vendor:publish --provider=\"Fideloper\\Proxy\\TrustedProxyServiceProvider\"\nThe above will create a file ${IXPROOT}/config/trustedproxy.php. For the most part, you now just need to change the IP address(es) in the array proxies to those of your own proxy/proxies.
NB: as well as the above, it is also critical that your have correctly set APP_URL in the .env file for URL generation to correctly work.
Controllers can be disabled by setting the following config item in config/ixp_fe.php:
<?php\n[\n // ...,\n\n 'frontend' => [\n 'disabled' => [\n 'xxx' => true,\n ],\n ],\n];\nwhere xxx is the controller name. This name is in kebab-case format including any non-IXP\\Http\\Controllers namespace. Here are some controller - xxx examples:
This action is controlled by the IXP\\Http\\Middleware\\ControllerEnabled middleware.
Note that in the configuration file, we have some pre-defined dotenv settings for commonly disabled controllers. It is a bad idea to manually edit the configuration files. If you find a controller than should be disabled and there there is no dotenv option, please open an issue.
"},{"location":"install/upgrade-v3/","title":"Upgrade From v3","text":"Due to the significant changes between IXP Manager v3 and v4, there is no in place upgrade process. The advised way to handle this is to install v4 in parallel and then switch over (by adjusting your DNS or Apache configuration for example) to the new v4 directory/server.
This documentation was compiled while performing an upgrade on three separate IXP Manager installations.
Before you proceed, please check the requirements listed in the official installation instructions.
If you need help, please contact us via the public mailing list.
If you find that this guide is insufficient, please contribute back to this documentation.
"},{"location":"install/upgrade-v3/#overview","title":"Overview","text":"The upgrade process is quite involved and, depending how many IXP Manager features you use, may take the best part of a day.
The general steps are:
You will note from the above that a number of features have been deprecated in favor of doing it in new ways. Our advice is to keep both v3 and v4 live in parallel and then migrate services piece meal. That way your route server configuration can continue pulling from v3 until you have set-up the v4 method. Just ensure that people do not make customer changes in either IXP Manager during this period (or, if they do, do it in both!).
"},{"location":"install/upgrade-v3/#deprecations-removed-features","title":"Deprecations / Removed Features","text":"As of IXP Manager v4 (certainly >=v4.5), the following are no longer available:
As we're installing in parallel, we want to duplicate the database.
When granting permissions on the new database, use your existing IXP Manager database credentials for ease of configuration.
mysql -u root -pXXX -e 'CREATE DATABASE ixp4 CHARACTER SET = \"utf8mb4\" COLLATE = \"utf8mb4_unicode_ci\";'\n\nmysqldump -u root -pXXX ixp | mysql -u root -pXXX ixp4\n\nmysql -u root -pXXX -e 'GRANT ALL ON ixp4.* TO `ixp`@`localhost` IDENTIFIED BY \"YYY\";'\n\n# and test:\nmysql -u ixp -pYYY -h localhost ixp4\nThis is very much a tl;dr version of the official installation instructions which you should review if you need additional help.
Critically, these upgrade instructions were designed and tested against IXP Manager v4.5.0. You need to upgrade to this version first and then follow the v4 upgrade instructions from there.
The code for IXP Manager is maintained on GitHub and the canonical repository is inex/IXP-Manager.
Log into the server where you wish to install IXP Manager and move to the directory where you wish to install (we use /srv/ixpmanager here as an example and which will be referred to as $IXPROOT below).
Note that it should not be checked out into any web exposed directory (e.g. do not checkout to /var/www).
IXPROOT=/srv/ixpmanager\n\n# get the source / application\ngit clone https://github.com/inex/IXP-Manager.git $IXPROOT\ncd $IXPROOT\ngit checkout v4.5.0\n\n# Using https://getcomposer.org/\ncomposer.phar install\n\n# Using https://bower.io/\nbower install\n\n# Start with the example configuration and edit.\n# Read the official documentation for help.\n# Ensure you configure the database.\n# More notes on this follow below.\ncp .env.example .env\nphp artisan key:generate\njoe .env\n\n# File system permissions\nchown -R www-data: var/ storage/ bootstrap/cache database/Proxies\nIXP Manager v4 uses a new PHP framework (Zend Framework swapped for Laravel). As such, all the older configuration options (from application/configs/application.ini) need to be ported to .env.
The php dotenv file (.env) is where all the new configuration options go. These in turn are used by the configuration files under config/.
NB: Where possible, place local changes into .env rather than changing the config files as these files are under version control. See Laravel's documentation on this and email the mailing list for help.
Once you have worked your way through .env, move into the $IXPROOT/config directory and - as appropriate for your own installation - examine each config file that ends in .dist. If you use / need any features in these files, copy then such as:
cd $IXPROOT/config\ncp xxxx.php.dist xxxx.php\nThen edit the resultant .php file (or, better, where config() options exist, add them to .env).
These .dist files represent v3 functionality that has not yet been fully ported to v4/Laravel.
There's about 50 schema changed between the end of v3 and v4.4.
View the required changes with:
./artisan doctrine:schema:update --sql\nAnd apply with:
./artisan doctrine:schema:update --force\nSince v4.5, we no longer allow plaintext passwords. If you were using plaintext passwords, you need to convert them to bcrypt as follows:
cd $IXPROOT\n\n# dummy run to see what happens:\nphp artisan utils:convert-plaintext-password\n\n# really convert passwords and save to database:\nphp artisan utils:convert-plaintext-password --force\nYou should be able to point Apache / your web server at the new IXP Manager installation and log in.
"},{"location":"install/upgrade-v3/#mrtg-graphing-migration","title":"MRTG Graphing Migration","text":"We've implemented a new graphing backend called Grapher. One of the changes is that the graphing directory structure and file-naming conventions have changed. Primarily, we've replaced non-static handles (such as database fields like customer.shortname, physicalinterface.monitorindex and switcher.name with immutable primary keys).
As such, you need to both rename the statistics directory structure and regenerate the configuration.
It is strongly recommended you copy your existing files and do this in parallel or, at least keep a backup. Also, stop the MRTG daemon before starting.
"},{"location":"install/upgrade-v3/#performing-the-migration","title":"Performing the Migration","text":"First, you'll need to update your local configuration in .env by setting something like:
GRAPHER_BACKENDS=\"mrtg\"\nGRAPHER_BACKEND_MRTG_LOGDIR=\"/path/to/new/mrtg/data\"\nGRAPHER_BACKEND_MRTG_WORKDIR=\"/path/to/new/mrtg/data\"\nGRAPHER_CACHE_ENABLED=true\nSee the Grapher documentation for full details of what these mean.
You'll then need to migrate all your MRTG files to the new naming scheme. Run the commands below twice. Once to verify the output and a second time piped to sh (| sh) to actually execute the commands.
# set a variable for what will become the 'old' files for convenience\nOLDMRTG=/srv/old-mrtg\n\n# position ourselves in the IXP Manager root directory\ncd $IXPROOT\n\n# stop mrtg\nservice mrtg stop # or as appropriate for your platform\n\n# Migrate IXP graphs.\n#\n# In v3 of IXP Manager, the name of this was set by a database\n# parameter in the IXP table called 'aggregate graph name'.\n# You will be able to spot it in the old MRTG files where the\n# old IXP file is named something like: 'ixp_peering-XXXXX-bits.log'.\n# The 'XXXXXX' bit is the aggregate name you need to replace in the below:\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -X --agg-name=XXXXXX\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -X --agg-name=XXXXXX | sh\n\n# Migrate infrastructure graphs.\n#\n# In v3 of IXP Manager, the name of this was set by a database\n# parameter in the infrastructure table called 'aggregate graph name'.\n# You will be able to spot it in the old MRTG files where the\n# old IXP file is named something like: 'ixp_peering-XXXXX-bits.log'.\n# The 'XXXXXX' bit is the aggregate name you need to replace in the below:\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -I\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -I | sh\n\n# Migrate switch graphs\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -S\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -S | sh\n\n# Migrate trunk graphs and configuration.\n# If you had not configured trunk graphs you can skip this. We are\n# planning to (very soon - Q2/3 2017) fully integrate this into IXP\n# Manager.\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -T\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -T | sh\nphp artisan grapher:backend:mrtg:upgrade migrate-trunk-config\n\n# Create member directories\nphp artisan grapher:backend:mrtg:upgrade mkdir -L $OLDMRTG -M\nphp artisan grapher:backend:mrtg:upgrade mkdir -L $OLDMRTG -M | sh\n\n# Migrate member physical interface graphs\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -P\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -P | sh\n\n# Migrate member LAG graphs\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -Q\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -Q | sh\n\n# Migrate member aggregate graphs\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -C\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -C | sh\n\n# Regenerate mrtg configuration\nphp artisan grapher:generate-configuration -B mrtg > path/to/mrtg.conf\n\n# Start mrtg\nservice mrtg start # or as appropriate for your platform\nThe previous version of IXP Manager used a script called sflow-graph.php which was installed on the sflow server to create graphs on demand. IXP Manager v4 does not use this but pulls the required RRD files directly.
If you have this on the same server or can expose it using NFS for example, then set the path accordingly in .env:
GRAPHER_BACKEND_SFLOW_ROOT=\"/srv/ixpmatrix\"\nIf you have implemented this via a web server on the sflow server (as we typically do at INEX), then you need to expose the RRD data directory to IXP Manager using an Apache config such as:
Alias /grapher-sflow /srv/ixpmatrix\n\n<Directory \"/srv/ixpmatrix\">\n Options None\n AllowOverride None\n <RequireAny>\n Require ip 192.0.2.0/24\n Require ip 2001:db8::/32\n </RequireAny>\n</Directory>\nand update .env for this with something like:
GRAPHER_BACKEND_SFLOW_ROOT=\"http://www.example.com/grapher-sflow\"\nThese upgrade instructions relate to upgrading when you are already using IXP Manager v4.x.
We track releases on GitHub.
You will find standard instructions for upgrading IXP Manager below. Note that the release notes for each version may contain specific upgrade instructions including schema changes.
If you have missed some versions, the most sensible approach is to upgrade to each minor release in sequence (4.5.0 -> 4.6.0 -> 4.7.0 -> ...) and then to the latest patch version in the latest minor version.
In the below, we assume the following installation directory - alter this to suit your own situation:
IXPROOT=/srv/ixpmanager\nThe general process is:
Set up some variables and ensure directory permissions are okay:
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\n# fix as appropriate to your operating system\nMY_WWW_USER=www-data\n\n# ensure the web server daemon user can write to necessary directories:\nchown -R $MY_WWW_USER: $IXPROOT/public/bower_components ${IXPROOT}/bower.json \\\n ${IXPROOT}/storage $IXPROOT/vendor\nchmod -R u+rwX $IXPROOT/public/bower_components ${IXPROOT}/bower.json \\\n ${IXPROOT}/storage $IXPROOT/vendor\nEnable maintenance mode:
cd $IXPROOT\n./artisan down\nUsing Git, checkout the next minor / latest patch version up from yours. For IXP Manager v4.
# (assuming we're still in $IXPROOT)\n# pull the latest code\ngit fetch\n# check out the version you are upgrading to\ngit checkout v4.x.y\nInstall latest required libraries from composer (see notes below):
# this assumes composer.phar is in the IXP Manager install directory. YMMV - see notes below.\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && php ./composer.phar install --no-dev --prefer-dist\"\nInstall latest frontend dependencies (see notes below):
# if asked to chose a jquery version, chose the latest / highest version offered\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && \\\n bower --config.interactive=false -f prune\"\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && \\\n bower --config.interactive=false -f update\"\nRestart Memcached and clear the cache. Do not forget / skip this step!
# (assuming we're still in $IXPROOT)\nsystemctl restart memcached.service\n./artisan cache:clear\nUpdate the database schema:
# (assuming we're still in $IXPROOT)\n# review / sanity check first:\n./artisan doctrine:schema:update --sql\n# If in doubt, take a mysqldump of your database first.\n# migrate:\n./artisan doctrine:schema:update --force\nRestart Memcached (yes, again). Do not forget / skip this step!
systemctl restart memcached.service\nEnsure there are no version specific changes required in the release notes.
Ensure file permissions are correct.
chown -R $MY_WWW_USER: $IXPROOT/public/bower_components ${IXPROOT}/bower.json \\\n ${IXPROOT}/storage $IXPROOT/vendor $IXPROOT/var $IXPROOT/bootstrap/cache\nchmod -R u+rwX $IXPROOT/public/bower_components ${IXPROOT}/bower.json \\\n ${IXPROOT}/storage $IXPROOT/vendor $IXPROOT/var $IXPROOT/bootstrap/cache\nFor IXP Manager v4.9 (including upgrading to v4.9) and later:
${IXPROOT}/artisan migrate\nClear out all caches:
${IXPROOT}/artisan cache:clear\n${IXPROOT}/artisan config:clear\n${IXPROOT}/artisan doctrine:clear:metadata:cache\n${IXPROOT}/artisan doctrine:clear:query:cache\n${IXPROOT}/artisan doctrine:clear:result:cache\n${IXPROOT}/artisan route:clear\n${IXPROOT}/artisan view:clear\nDisable maintenance mode:
# (assuming we're still in $IXPROOT)\n./artisan up\nSome older scripts, including the sflow modules, rely on MySQL view tables that may be affected by SQL updates. You can safely run this to recreate them:
mysql -u ixp -p ixp < $IXPROOT/tools/sql/views.sql\nIt is not advisable to run bower as root but how you run it will depend on your own installation. The following options would work on Ubuntu (run these as root and the bower commands themselves will be run as $MY_WWW_USER):
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\nMY_WWW_USER=www-data # fix as appropriate to your operating system\n\n# ensure www-data can write to bower:\nchown -R $MY_WWW_USER: $IXPROOT/public/bower_components ${IXPROOT}/bower.json ${IXPROOT}/storage\nchmod -R u+rwX $IXPROOT/public/bower_components ${IXPROOT}/bower.json ${IXPROOT}/storage\n\n# update bower\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && bower --config.interactive=false -f update\"\nThe above command is structured as it is because typically the www-data user has a nologin shell specified.
This is similar to the bower section above so please read that if you have not already.
Note that we assume here what you have installed Composer (see: https://getcomposer.org/ ) in the ${IXPROOT} directory as composer.phar. This is where and how the IXP Manager installation scripts and documentation instructions install it.
The following options would work on Ubuntu (run these as root and the composer commands themselves will be run as $MY_WWW_USER):
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\nMY_WWW_USER=www-data # fix as appropriate to your operating system\n\n# ensure www-data can write to vendor:\nchown -R $MY_WWW_USER: $IXPROOT/vendor ${IXPROOT}/storage\nchmod -R u+rwX $IXPROOT/vendor ${IXPROOT}/storage\n\n# update composer\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && php ./composer.phar install\"\nNB: If composer is not managed by your package management system, you should keep it up to date via the following (using the same definitions from the composer update example above):
chown -R $MY_WWW_USER: ${IXPROOT}/composer.phar\nchmod -R u+rwx ${IXPROOT}/composer.phar\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && php ./composer.phar selfupdate\"\nBecause of the manual process of database updates, it is possible your database schema may fall out of sync.
If you are having issues, first and foremost, restart Memcached. Doctrine2 caches entities and schema information in Memcached so, after an upgrade, you must restart Memcached.
You can verify and update your schema using the artisan script. The first action should be validation - here is a working example with no database issues:
cd $IXPROOT\n./artisan doctrine:schema:validate\n\nValidating for default entity manager...\n[Mapping] OK - The mapping files are correct.\n[Database] OK - The database schema is in sync with the mapping files.\nIf there are issues, you can use the following to show what SQL commands are required to bring your schema into line:
./artisan doctrine:schema:update --sql\nAnd you can let Doctrine make the changes for you via:
./artisan doctrine:schema:update --force\nDoctrine2 maintains the entities, proxies and repository classes. Ideally you should never need to do the following on a production installation - as we maintain these files with Git - but if you're developing / testing IXP Manager, you may need to.
The process for updating these files with schema changes / updates is:
cd $IXPROOT\nsystemctl restart memcached.service # (or as appropriate for your system)\n./artisan doctrine:generate:entities database\n./artisan doctrine:generate:proxies\nWe created a video tutorial demonstrating the upgrade process for IXP Manager. You can find the video here in our YouTube channel. We also have a video on upgrading a legacy version (v4.9.3 to v5.7.0) - see the video here and some further details in this blog post. As always, the full catalog of video tutorials is here.
"},{"location":"install/upgrade-v5/#instructions","title":"Instructions","text":"We track releases on GitHub.
You will find standard instructions for upgrading IXP Manager below. Note that the release notes for each version may contain specific upgrade instructions including schema changes.
If you have missed some versions, the most sensible approach is to upgrade to each minor release in sequence (5.0.0 -> 5.1.0 -> 5.2.0 -> ...) and then to the latest patch version in the latest minor version.
In the below, we assume the following installation directory - alter this to suit your own situation:
IXPROOT=/srv/ixpmanager\nBefore you start, consider if you need to make a backup. We would expect that most IXP's would have a nightly backup of all their servers at a minimum. If not, or for belt-and-braces, you may want to make a local temporary backup. See our operational notes on backups for an idea on how to do this.
The general process is:
Set up some variables and ensure directory permissions are okay:
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\n# fix as appropriate to your operating system\nMY_WWW_USER=www-data\n\n# ensure the web server daemon user can write to necessary directories:\nchown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nEnable maintenance mode:
php $IXPROOT/artisan down --message='Please wait, currently upgrading...'\nUsing Git, checkout the next minor / latest patch version up from yours. For IXP Manager v4.
cd $IXPROOT\n# pull the latest code\ngit fetch --all\n# check out the version you are upgrading to\ngit checkout v5.x.y\nInstall latest required libraries from composer (see notes below). Note that composer may be in different locations.
# This assumes composer is in the IXP Manager install directory.\n# (Typical for IXP Manager on Ubtuntu 18.04):\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} \\\n && php ./composer.phar install --no-dev --prefer-dist\"\n\n# OR:\n\n# This assumes composer is installed globally.\n# (Typical for IXP Manager on Ubtuntu 20.04):\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} \\\n && composer install --no-dev --prefer-dist\"\nRestart Memcached and clear the cache. Do not forget / skip this step!
systemctl restart memcached.service\nphp $IXPROOT/artisan cache:clear\nUpdate the database schema:
# (you really should take a mysqldump of your database first)\n\n# (optional) see what changes will be made:\nphp $IXPROOT/artisan doctrine:schema:update --sql\nphp $IXPROOT/artisan migrate:status\n\n# migrate:\nphp $IXPROOT/artisan doctrine:schema:update --force\nphp $IXPROOT/artisan migrate\nRestart Memcached (yes, again). Do not forget / skip this step!
systemctl restart memcached.service\nEnsure there are no version specific changes required in the release notes.
Ensure file permissions are still correct.
chown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nClear out all caches:
php ${IXPROOT}/artisan cache:clear\nphp ${IXPROOT}/artisan config:clear\nphp ${IXPROOT}/artisan doctrine:clear:metadata:cache\nphp ${IXPROOT}/artisan doctrine:clear:query:cache\nphp ${IXPROOT}/artisan doctrine:clear:result:cache\nphp ${IXPROOT}/artisan route:clear\nphp ${IXPROOT}/artisan view:clear\nDisable maintenance mode:
php ${IXPROOT}/artisan up\nRecreate SQL views
Some older scripts, including the sflow modules, rely on MySQL view tables that may be affected by SQL updates. You can safely run this to recreate them on versions > v5.5.0:
php ${IXPROOT}/artisan update:reset-mysql-views\nIf you are running <= v5.4.0 then do this as follows using the appropriate MySQL username and password:
mysql -u ixp -p ixp < $IXPROOT/tools/sql/views.sql\nIt is not advisable to run composer as root but how you run it will depend on your own installation. The following options would work on Ubuntu (run these as root and the composer commands themselves will be run as $MY_WWW_USER). Note that we assume here what you have installed Composer (see: https://getcomposer.org/ ) in the ${IXPROOT} directory as composer.phar. This is where and how the IXP Manager installation scripts and documentation instructions install it.
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\nMY_WWW_USER=www-data # fix as appropriate to your operating system\n\n# ensure the web server daemon user can write to necessary directories:\nchown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\n\n# update composer packages\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} \\\n && php ./composer.phar install --prefer-dist --no-dev\"\nNB: If composer is not managed by your package management system, you should keep it up to date via the following (using the same definitions from the composer update example above):
chown -R $MY_WWW_USER: ${IXPROOT}/composer.phar\nchmod -R u+rwx ${IXPROOT}/composer.phar\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && php ./composer.phar selfupdate\"\nBecause of the manual process of database updates, it is possible your database schema may fall out of sync.
If you are having issues, first and foremost, restart Memcached / clear your cache (see upgrade instructions above). Doctrine2 caches entities and schema information in Memcached so, after an upgrade, you must restart Memcached.
You can verify and update your schema using the artisan script. The first action should be validation - here is a working example with no database issues:
cd $IXPROOT\n./artisan doctrine:schema:validate\n\nValidating for default entity manager...\n[Mapping] OK - The mapping files are correct.\n[Database] OK - The database schema is in sync with the mapping files.\nIf there are issues, you can use the following to show what SQL commands are required to bring your schema into line:
./artisan doctrine:schema:update --sql\nAnd you can let Doctrine make the changes for you via:
./artisan doctrine:schema:update --force\nDoctrine2 maintains the entities, proxies and repository classes. Ideally you should never need to do the following on a production installation - as we maintain these files with Git - but if you're developing / testing IXP Manager, you may need to.
The process for updating these files with schema changes / updates is:
cd $IXPROOT\nsystemctl restart memcached.service # (or as appropriate for your system)\n./artisan doctrine:generate:entities database\n./artisan doctrine:generate:proxies\nFor instructions on how to upgrade from v5.8.0 to v6.0.0, please see the release notes for v6.
For instructions on how to upgrade within the v5.x releases, please see this page.
For instructions on how to upgrade within the v4.x releases, please see this page.
For instructions on how to upgrade from v3.x to v4, please see this page.
For instructions on how to upgrade from v4.9.x to v5.0, please see the v5.0 release notes.
We created a video tutorial demonstrating the upgrade process for IXP Manager within the v5.x branch which is not dissimilar to this. You can find the video here in our YouTube channel. We also have a video on upgrading a legacy version (v4.9.3 to v5.7.0) - see the video here and some further details in this blog post. As always, the full catalog of video tutorials is here.
"},{"location":"install/upgrading/#instructions","title":"Instructions","text":"We track releases on GitHub.
You will find standard instructions for upgrading IXP Manager below. Note that the release notes for each version may contain specific upgrade instructions including schema changes.
If you have missed some versions, the most sensible approach is to upgrade to each minor release in sequence (6.0.0 -> 6.1.0 -> 6.2.0 -> ...) and then to the latest patch version in the latest minor version.
In the below, we assume the following installation directory - alter this to suit your own situation:
IXPROOT=/srv/ixpmanager\nBefore you start, consider if you need to make a backup. We would expect that most IXP's would have a nightly backup of all their servers at a minimum. If not, or for belt-and-braces, you may want to make a local temporary backup. See our operational notes on backups for an idea on how to do this.
The general process is:
Set up some variables and ensure directory permissions are okay:
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\n# fix as appropriate to your operating system\nMY_WWW_USER=www-data\n\n# ensure the web server daemon user can write to necessary directories:\nchown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nEnable maintenance mode:
php $IXPROOT/artisan down --message='Please wait, currently upgrading...'\nUsing Git, checkout the next minor / latest patch version up from yours. For IXP Manager v6:
cd $IXPROOT\n# pull the latest code\ngit fetch --all\n# check out the version you are upgrading to\ngit checkout v6.x.y\nInstall latest required libraries from composer (see notes below). Note that composer may be in different locations.
# This assumes composer is installed globally.\n# (Typical for IXP Manager on Ubtuntu 20.04):\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} \\\n && composer install --no-dev --prefer-dist\"\nRestart Memcached and clear the cache.
systemctl restart memcached.service\nphp $IXPROOT/artisan cache:clear\nUpdate the database schema:
# (you really should take a mysqldump of your database first)\n\n# (optional) see what changes will be made:\nphp $IXPROOT/artisan migrate:status\n\n# migrate:\nphp $IXPROOT/artisan migrate\nEnsure there are no version specific changes required in the release notes.
Ensure file permissions are still correct.
chown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nClear out all caches (cache is there twice which is intended):
php ${IXPROOT}/artisan cache:clear\nphp ${IXPROOT}/artisan cache:clear file\nphp ${IXPROOT}/artisan config:clear\nphp ${IXPROOT}/artisan route:clear\nphp ${IXPROOT}/artisan view:clear\nDisable maintenance mode:
php ${IXPROOT}/artisan up\nRecreate SQL views
Some older scripts, including the sflow modules, rely on MySQL view tables that may be affected by SQL updates.
cd ${IXPROOT}\nsource .env\nmysql -h $DB_HOST -u $DB_USERNAME -p$DB_PASSWORD $DB_DATABASE < $IXPROOT/tools/sql/views.sql\nIt is not advisable to run composer as root but how you run it will depend on your own installation. The following options would work on Ubuntu (run these as root and the composer commands themselves will be run as $MY_WWW_USER). Note that we assume here what you have installed Composer (see: https://getcomposer.org/ ) in the ${IXPROOT} directory as composer.phar.
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\nMY_WWW_USER=www-data # fix as appropriate to your operating system\n\n# ensure the web server daemon user can write to necessary directories:\nchown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\n\n# update composer packages\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} \\\n && php ./composer.phar install --prefer-dist --no-dev\"\nNB: If composer is not managed by your package management system, you should keep it up to date via the following (using the same definitions from the composer update example above):
chown -R $MY_WWW_USER: ${IXPROOT}/composer.phar\nchmod -R u+rwx ${IXPROOT}/composer.phar\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && php ./composer.phar selfupdate\"\nIXP Manager allows users to login and remain logged in for up to 30 days (by default). Users may also have and maintain multiple login sessions from different browsers.
To enable such a long-lived session, the user must check the Remember me checkbox when logging in.
Active sessions can be seen (and deleted) via the Active Sessions option in the user's My Account menu (top right of screen).
"},{"location":"usage/authentication/#session-lifetimes","title":"Session Lifetimes","text":"There are two configurable options here - both in minutes. The first is the session lifetime which is how long a browser session will stay valid since the last activity. The default value is defined in .env as:
SESSION_LIFETIME=120\nIn other words, your login session (when you do not check remember me) will stay valid for 120 minutes / 2 hours by default. This is two hours since the last request - i.e. the session expiry time updates on each request. If you are curious, the browser cookie managing this is called laravel_session by default.
If the user checks remember me, then a second cookie is sent to and stored on your browser (called remember_web_xxx where xxx is a random string). This references an entry in the user's user_remember_tokens database table.
The default lifetime of this remember me session is defined in .env as:
AUTH_TOKEN_EXPIRE=43200\nSo, your remember me session will last 30 days before you will be forced to login again from a particular browser.
You may notice that the cookie sent to the browser for this has an indefinite lifetime - the expiry is actually controlled by the user_remember_tokens.expires database column.
Two factor authentication (2fa) strengthens access security by requiring two methods (also referred to as factors) to verify your identity. Two factor authentication protects against phishing, social engineering and password brute force attacks and secures your logins from attackers exploiting weak or stolen credentials.
For the avoidance of doubt, 2fa does not apply to API keys or API requests. Treat your API keys with extreme care.
IXP Manager supports a Google Authenticator compatible HMAC-Based One-time Password (HOTP) algorithm as specified in RFC 4226 and the Time-based One-time Password (TOTP) algorithm specified in RFC 6238. In other words, the standard 2fa system that is supported by most apps such as Authy, Google Authenticator, LastPass, 1Password, etc.
User's can enable, view (and test) and disable 2fa via the My Account -> Profile page.
2FA support in IXP Manager is enabled by default from v5.3. To globally disable it set the following .env option:
2FA_ENABLED=false\nYou can enforce the use of 2fa for some (or all) categories of users. Set the following configuration option:
2FA_ENFORCE_FOR_USERS=n\nwhere n is the privilege level of the user (see privs= here). For example to force 2fa for:
3;2; or1.If a user without 2fa enabled tries to login from a privilege category that has been configured to enforce 2fa, they will be required to configure 2fa immediately before being granted access to IXP Manager.
"},{"location":"usage/authentication/#lifetime","title":"Lifetime","text":"A user will not be asked to revalidate their 2fa code during the lifetime of a standard browser session or remember me session (see above).
"},{"location":"usage/authentication/#removing-2fa-restoring-user-access","title":"Removing 2FA / Restoring User Access","text":"We have opted not to implement recovery / backup codes as they are not particularly appropriate to the scope of IXP Manager.
If a user needs to have their 2fa removed (indefinitely or so they can reconfigure it), superadmins can do this via the standard user listing (the Users option in the left hand menu).
Identify the user you wish to remove 2fa from, dropdown the additional actions menu on the far right of the table row and select Remove 2FA.
Once you confirm this action, that user's 2fa configuration will be deleted. The next time they log in, they will either be granted access without 2fa or forced to reconfigure 2fa if you have enforced 2fa for the user's category.
"},{"location":"usage/contacts/","title":"Contacts","text":"The IXP Manager Contacts feature allows you to record and manage contacts on a per customer basis including:
If the roles are not shown when you are editing / adding contacts, ensure you copy the following file to a local version:
cp ${IXPROOT}/config/contact_group.php.dist ${IXPROOT}/config/contact_group.php\nThe latest version of the automatic installation script takes care of this but older versions did not.
"},{"location":"usage/contacts/#contact-groups","title":"Contact Groups","text":"INTRODUCED: 20130410 - V3.0.9 (sponsored by LONAP)
Contacts can be assigned to multiple arbitrary groups. A group is defined by:
You define the group types in config/contact_group.php such as:
return [\n 'types' => [\n 'ROLE' => 'Role',\n 'MARKETING_PREFERENCES' => 'Marketing Preferences',\n ],\n];\nTo activate this feature, you just need to create the configuration file. From the root directory of IXP Manager just:
cp config/contact_group.php.dist config/contact_group.php\nNote that Role is a default option and should not be removed.
In these examples, ROLE will be entered in the database column and Role will be displayed in the interface.
Group options can then be added / edited / deleted via the web interface. This can be reached by clicking Contacts in the left-hand side menu and then the sub-menu option that appears called Contact Groups.
"},{"location":"usage/contacts/#creating-editing-deleting-groups","title":"Creating / Editing / Deleting Groups","text":"A group is defined by:
You define the group types in config/contact_group.php.
In these examples, ROLE will be entered in the database column and Role will be displayed in the interface.
Groups can then be added / edited / deleted via https://www.example/com/ixp-manager/contact-group. This can be reached by clicking Contacts and then Contact Groups in the left menu.
Assigning contacts to groups is done in the contact add / edit page.
"},{"location":"usage/contacts/#exporting-contact-groups","title":"Exporting Contact Groups","text":"Contact groups can be exported using the artisan command, for example:
./artisan contact:export-group --type=ROLE --cid=1 --format=csv\nwhere the possible options are (from ./artisan contact:export-group --help:
$ ./artisan contact:export-group --help\nUsage:\n contact:export-group [options]\n\nOptions:\n --type[=TYPE] Contact group type (e.g. ROLE)\n --name[=NAME] Contact group name (e.g. beer)\n --format[=FORMAT] Output format - one of json (default) or csv [default: \"json\"]\n --cid[=CID] Optionally limit results to given customer id\n\nHelp:\n Export contacts based on group information\nThe default sample configuration file (config/contact_group.php) and the database seeds create a ROLE group type populated with groups Admin, Billing, Technical and Marketing. There is a dedicated form element when editing contacts for any groups defined in the Role type.
If the role type is removed from the configuration, the form element for the contact's roles will not be shown.
"},{"location":"usage/contacts/#historical-perspective","title":"Historical Perspective","text":"IXP Manager of pre-April 2013 had separate contacts and users which - at the time - we felt was quite confusing. LONAP sponsored a rework of this in 2013 to merge the concept of users and contacts with login privileges. Strangely, this actually caused more confusion and also was a developer nightmare with hacked in code to handle the database tables in multiple places. As such, in 2019 with release v4.9, this was undone and contacts and users are now separate entities again.
"},{"location":"usage/cookies/","title":"Cookies and Privacy","text":"IXP Manager is open-source and free software. Any individual or organisation who installs IXP Manager and/or makes it available for use must ensure that they are complying with all appropriate data protection legislation in their jurisdiction as the data controller.
This page details what the developers consider appropriate information to the best of their knowledge for helping such organisations with such compliance. Note also that the information herein is based on IXP Manager's default configuration.
"},{"location":"usage/cookies/#cookies","title":"Cookies","text":"Cookies are small text files that websites place on your device as you are browsing. They are processed and stored by your web browser. Cookies can generally be easily viewed and deleted via your browser's functionality. Each cookie is unique to your web browser and will usually contain information such as the cookie name, a unique identifier, and the website's host name or domain name.
IXP Manager uses a PHP web application framework called Laravel and it generates two encrypted cookies which are required to use the application:
Cookie Name Purpose and Description Classification Lifetimelaravel_session Session management - since HTTP driven applications are stateless, sessions provide a way to store information about the user across multiple requests. These cookies are encrypted by the server and the client browser only receives and stores the encrypted version. Strictly Necessary 120 minutes XSRF-TOKEN Cross-site request forgeries are a type of malicious exploit whereby unauthorized commands are performed on behalf of an authenticated user. Laravel stores the current CSRF token in an encrypted XSRF-TOKEN cookie that is included with each response generated by the framework. Strictly Necessary 120 minutes A third cookie is generated if a user optionally invokes the Remember Me functionality during login / authentication:
Cookie Name Purpose and Description Classification Lifetimeremember_web_xxx Session management cookie to facilitate longer sessions and multiple session functionality. These cookies are encrypted by the server and only the encrypted version exists on the client side browser. These only contain a session ID. The server records the user's IP address and a browser identifier (e.g. Macintosh 10 / Firefox 109.0) so that users can identify and optionally delete long-lived sessions in the user interface. Strictly Necessary 30 days IXP Manager does not generate any other cookies.
"},{"location":"usage/cookies/#strictly-necessary-cookies","title":"Strictly Necessary cookies","text":"Strictly Necessary cookies are essential for you to browse the website and use its features, such as accessing secure areas of the site. For example, these cookies let us recognise that you have an account and you have logged into that account. These necessary cookies also allow the portal to remember you and avoid having to log you in on each site visit, or to prevent cross-site scripting security issues.
IXP Manager uses only first-party strictly necessary cookies. IXP Manager does not use third-party cookies.
"},{"location":"usage/cookies/#cookies-and-eu-eprivacy-and-gdpr-law","title":"Cookies and EU ePrivacy and GDPR Law","text":"As IXP Manager generates only Strictly Necessary cookies, it does not need to receive users' consent for the use of these cookies.
"},{"location":"usage/cookies/#data-protection-and-privacy","title":"Data Protection and Privacy","text":"The following table is a summary of personal data collected by IXP Manager and for what purpose / activity:
Data Collected Purpose / Activity Contact details including name, position and role, phone number, email address, etc. These are stored on a per member basis and customer admins can also add, edit and remove these. To manage and facilitate customers / members of an exchange; usually in the performance of a contract. Usernames and passwords To provide members / customers with access to secure areas of IXP Manager; usually in the performance of a contract. Login history (IP address, date and time) To provide an auditable record of when users logged into IXP Manager; usually in compliance with ISMS policies. Login IP address and browser identifier To enable users to identify and optionally delete long-lived sessions that they opt into. Generic note fields Many records on IXP Manager allow admins to enter free text notes. You should ensure you have appropriate policies for this. Their use would be to manage and facilitate customers / members of an exchange; usually in the performance of a contract. Document store - file uploads Admins can upload files to a central store or to a per customer / member store. You should ensure you have appropriate policies for this. The suggested use case is copies of contracts; service order forms; etc."},{"location":"usage/cookies/#correctness-and-disclaimer","title":"Correctness and Disclaimer","text":"This information is correct as of November 2023 for the IXP Manager application as distributed and unaltered from its official source code repository at inex/IXP-Manager. Some IXPs may install it on domains hosting other web sites / applications which may generate their own domain-scoped cookies.
The cookie lifetimes provided above are the defaults but are configurable.
"},{"location":"usage/core-bundles/","title":"Core Bundles","text":"DRAFT: THIS IS A WORK IN PROGRESS AND NOT READY FOR PRODUCTION USE - BARRYO Dec 2017
This section explains how to manage core bundles - a core bundle is sometimes called an ISL (Inter-Switch Link). It is a link that connects two IXP switches together to carry production IXP traffic.
Before reading this, it is expected that you have read and have a good understanding of the concepts from Customer Connections. Virtual Interfaces (VIs), Physical Interfaces (PIs) and how they relate to Switch Ports (SPs) also apply here.
"},{"location":"usage/core-bundles/#core-bundles-types-and-database-overview","title":"Core Bundles Types and Database Overview","text":"IXP Manager supports three types of core bundles:
From IXP Manager's database perspective, these all are represented as follows:
From this, please note the following terminology, relationships and abbreviations which will be used throughout this document:
The only way to provision a new core bundle is to use the wizard. This can be accessed by:
When you open the wizard, you will see something like the following (note this example represents the options for ECMP):
This can be used to provision a single port standard customer connection. If they customer needs a LAG or other non-standard options, these can be added afterwards.
"},{"location":"usage/core-bundles/#general-interface-settings","title":"General Interface Settings","text":"The customer should be prefilled and read-only as you enter the wizard from a specific customer overview page.
You would normally just select your main / primary peering VLAN from the VLAN dropdown. There are some notable exceptions:
Use 802.1q framing checkbox if the port should be tagged facing the customer. If you are not using any automation tools, this will be informational for you rather than production affecting.This section allows you to select the physical interface / switch port for the connection.
Switch: a dropdown list of all switches. Be careful as at present this list is all active switches rather than switches on the same infrastructure as the selected VLAN from General Interface Settings.Port: the switch port to use. This is dynamically populated when the switch is selected and will only show ports of type Peering or type Unset / Unknown (these are set on a per port basis when adding / editing switches).Status: the port status currently has one of five options. They effectively work as a boolean where Connected means on/enabled and the rest mean disabled as explained below. In practice, we tend to just use three states:
Connected: this is the most important. When a virtual interface has any port with the Connected state, then IXP Manager will consider this connection active and will generate router configuration, monitoring configuration, etc.
Awaiting X-Connect: the customer has requested an upgrade / new port and we are awaiting for the co-location provider / customer to get the cross connect organised.Quarantine: the port is connected and is under going quarantine prior to being moved onto the production peering LAN. During quarantine, INEX checks the port to ensure only ARP, IPv4 and IPv6 packets are received (no *-discovery, STP, etc. as well as a number of other things).The Not Connected and Disabled states have the same effect as (2) and (3) above and can be used as informational settings where (2) and (3) do not apply.
Speed and duplex are self explanatory. These settings in the physical interface entity are informational unless you are doing automation. They also have knock on effects to (for example) graphing - where the MRTG max value on an interface is set to this to prevent weird excessive spikes on counter rollovers.
"},{"location":"usage/core-bundles/#general-vlan-settings","title":"General VLAN Settings","text":"These settings apply to the VLAN interface.
The Max BGP Prefixes is a setting used to determine max prefixes on router BGP peers - please see the global version of this as explained in the customer section for details.
If Apply IRRDB Filtering is not set, then the route servers will accept any prefixes advertised by the customer (note that the default templates will filter martians and apply a max prefix limit). Generally speaking this is a very bad idea and should only be used in exceptional cases. INEX never uses this setting - but demand from other IX's had it added.
Multicast Enabled is informational only. INEX used to support multicast on the peering LAN but removed support in 2015 due to lack of interest and added complexity / cost when purchasing new switches.
If Route Server Client is checked, then IXP Manager will configure a BGP peer for this connection when generating route server configurations. It is also used in other areas to show if a member uses the route servers or not, by the Peering Manager to calculate missing BGP sessions, etc.
Similarly, if AS112 Client is checked, then IXP Manager will configure a BGP peer for this connection when generating AS112 router configurations.
When IPv4 / IPv6 Enabled is checked under General Interface Settings above, these two sections will be available.
The same details apply to IPv4 and IPv6 options so we will document them together.
IP Address: the IP address to assign to this customer. This is taken from available IP addresses for the VLAN selected in General Interface Settings.Hostname: if you use IXP Manager to configure your DNS ARPA entries, the hostname entered here will be returned when a PTR request is made for the assigned IP address. Enter a complete hostname without trailing period such as: www.example.com.BGP MD5 Secret: The will be used for generating router configurations.Can Ping: IXP Manager generates configuration for a number of other tools such as Smokeping and Nagios which ping customer routers. These are invaluable tools for problem solving, monitoring and graphing long term trends. We enable this by default unless a customer specifically asks us not to.Can Monitor RC BGP: this is more of a legacy option for configuration builders that used to check for established route collector BGP sessions and warn if not present. This is deprecated and will be removed.Once an interface has been added as per the above wizard instructions, you can view and edit the interface by selecting the edit icon against the connection you are interested in from the Ports tab on the customer overview page. When you do that, you will see a screen such as the following:
You can see from the layout of this screen how it ties in with the schema explained above.
"},{"location":"usage/core-bundles/#virtual-interface-details","title":"Virtual Interface Details","text":"The screenshot above shows the virtual interface details with the Advanced Options shown. The additional fields here that were not in the wizard are described below.
Link aggregation / LAG framing is mostly informational unless you are doing automation. There are some restrictions. Namely / specifically:
The Virtual Interface Name is again mostly informational unless you are doing automation. It should be the start of the LAG name without the number. On an IOS device this would be Port-channel for example. Matched with this is the Channel Group Number with is tacked onto the end of the Virtual Interface Name. Leave it as 0 and when you check Link aggregation / LAG framing and save the changes, IXP Manager will set this to the next available unused port channel / bundle / LAG number on that switch.
Both Description and MTU are informational.
You can add additional physical interfaces to a connection / virtual interface. This effectively means you are creating a LAG. The form for adding additional physical interfaces is identical to that in the wizard.
"},{"location":"usage/core-bundles/#vlan-interfaces","title":"VLAN Interfaces","text":"The most common use case of more than one VLAN Interface is when your customer may also have private VLANs on their connection.
Other than that, the VLAN interface add / edit form has all the same elements as the wizard with one addition:
Busy host: this flag indicates that the customer's router is unusually slow to reply to ICMP echo requests and that when monitoring, the configuration should allow for warnings after a 5sec RTT rather than 1sec.IXP Manager allows administrators to add notes to customer records via the customer overview page.
Some of the features currently supported include:
The following image shows the standard customer overview page (as per v4.8.0) with the Notes tab selected and two sample notes:
The first note, Sample Private Note, is a note that is only visible to administrators. The second note, Test Public Note, is visible to any user logged in for this customer.
The next image shows the dialog for adding a customer note.
By default, notes are private and you are required to check the Makee note visible to customer to make it a public note.
The Preview table allows you to see what the note will look like when formatted via Markdown:
Existing notes can be edited, deleted and viewed:
"},{"location":"usage/customer-notes/#notifications","title":"Notifications","text":"As mentioned above, administrators can choose to be alerted by email to new / edited / deleted notes in one of four ways:
On an administrator's My Account -> Profile page, you will find the following:
The first of these radio options, Disable all email notifications, corresponds to (1) never above. The last of these radio options, Email me on any change to any customer note corresponds to (2) all notes for all customers above.
The middle option, Email me on changes to only watched customers and notes, is controlled via the bell icon on the customer overview notes tab. If a user had requested notifications as follows:
then all changes to any customer note for AS112 Reverse DNS [AS112] will be emailed to the user because the customer bell (the one on the top right) has been selected.
If the user had not selected the customer bell then:
The order of precedence for determining if a note change should be notified by email is:
If neither (1) nor (2) hold above, then the user has selected the radio option Email me on changes to only watched customers and notes. In which case a notification is sent for the customer whose note is being added / edited / deleted:
a. if the customer bell is selected for the customer in question b. if the note bell is selected for the note in question
Otherwise no notification is sent.
IXP Manager allows administrators to tag customers to indicate specific properties that are not built into IXP Manager by default. Some examples might include:
Tags can be added / edited / deleted by clicking on the Customers option in the left hand side menu and then clicking on the Tags sub-option which appears. The form for adding tags is pretty straight-forward:
While the help text should be self-explanatory, here is some more detail and examples:
Tag: should be something like: commercial, member, 100mb-upgrade-program. Note that these are always lowercase alphanumeric characters and optional dashes.
Display AS: allows you to provide something prettier when displaying the tag within IXP Manager. Examples following from the above might include: Commercial, Member, 100Mb Upgrade Program.
Description: allows you to add some text that may help you remember the specific use-case of a tag in five years time!
Internal Only: if not set, then tags can be optionally including in various public / non-superadmin accessible APIs / pages / exports.
When at least one tag has been created, the customer overview masthead will now provide the option to add tags to customers:
Once one or more tags have been added, they are shown in the masthead such as:
You will also find an option in the Edit menu of the customer overview page to Manage Tags....
"},{"location":"usage/customer-tags/#exporting-tags","title":"Exporting Tags","text":"Tags can be exported as part of the IX-F Member Export process by adding ?withtags=1 to the API URL. For example:
https://ixp.example.com/api/v4/member-export/ixf/0.7?withtags=1\nYou have to specify ?withtags=1 as this is not part of the official IX-F Member Export specification.
When you request this, you will find an empty object with each customer that does not have tags in an ixp_manager namespace of the form:
\"ixp_manager\": {\n \"tags\": []\n}\nAnd for those that do have tags, it will be of the form:
\"ixp_manager\": {\n \"tags\": {\n \"test-tag1\": \"Test Tag1\",\n \"test-tag2\": \"Test Tag2\"\n }\n}\nwhere test-tag2 is the tag and Test Tag2 is the display name.
We created a video tutorial demonstrating these steps. You can find the video here in our YouTube channel. As always, the full catalog of video tutorials is here.
"},{"location":"usage/customers/#adding-customers","title":"Adding Customers","text":"To add a new customer in IXP Manager, select the Customers option from the left hand side admin menu and then click the [+] icon on the top right. You'll find yourself with a form such as (may vary over time):
What follows is an explanation of each section.
"},{"location":"usage/customers/#customer-details","title":"Customer Details","text":"The Name field is the customer's name as you/they typically want it to appear in IXP Manager. It is not necessarily their full legal entity name (that goes elsewhere). The Abbreviated Name is a shorter version of the name that is used in space constrained areas such as graph labels.
The Type field is a dropdown with the following meanings:
Full: this is what you will use most of the time. This is a full / normal trafficking IXP member.Pro-bono: like full but for organisations that you provide IXP access to for the good of the internet / your members. Examples at INEX include the AS112 service, Packet Clearing House's route collector and DNS TLD/root services and other DNS root servers such as the RIPE K root / Verisign, etc.Internal: while not enforced, you should really only have two internal customers which is the IXP itself and, separately, the IXP route servers. Connections / interfaces such as route collectors and core links would be associated with the IXP customer. Because route servers typically have a dedicated ASN, they would have their own customer with their interfaces associated here.Associate: INEX has a concept of associate members which enables those organisations who are involved in the IP and networking industry, but who do not have their own IP traffic to peer, an opportunity to participate in the extensive INEX community. See full details here. Associate customers in IXP Manager have very limited functionality but it allows us to keep track of them.The Shortname field is something we are slowly removing. It is currently visible in some URLs and a couple other areas. It should be a lowercase single word ([a-z0-9]) and it should not be changed after it is set.
The Corporate Website is used when linking the customer name in various customer lists. It must be a valid URL. Try and stick to the scheme: http://www.example.com/ - i.e. include http[s]:// and end with a trailing slash.
The Date Joined is just that and must be set. However, the Date Left has real consequences: setting Date Left effectively closes the customer's account. This means configuration will no longer be included for graphing, router configuration, etc. We tend not to delete customers but mark them as closed by setting this field.
Status yields three options. The most important of which is Normal which is what you'll use nearly 100% of the time. Setting either of the other two options (Suspended / Not Connected) will have the same effect as closing the account as described above: removing route server / collector sessions, graphing configuration, etc.
MD5 Support: this is not something that has been fully integrated into all view screens. You should probably default to Yes for now as this will cover 95+% of cases. It is an informational flag only for member to member bilateral peering.
The AS Number is just the integer value without any AS prefix, etc.
Max Prefixes is known as the global max prefixes value. It is used to work out the appropriate max prefixes value to apply to all router configurations in the stock / default templates (route collector and servers, AS112). The calculated value is also included in emails from the Peering Manager from customer to customer.
There are two issues with max prefixes:
The max prefixes value is worked out in the code when generating router configuration is as follows:
At INEX, we default to 50 for small members, and 250 for medium sized members (who may already have 50 say), and as advised by larger members.
The Peering Email is used in member lists and by the Peering Manager for sending emails. We try and encourage an alias of peering@example.com but this does not always work out.
The IPv4 Peering Macro is used instead of the AS number when set to generate inbound prefix filters for the route servers based on the member's published IRR records. AS-BTIRE in the RIPE database is an example for BT Ireland.
The IPv6 Peering Macro was added for another IX using IXP Manager that had a customer which used a separate macro for v4 and v6. We only know of that single instance of this. In the event that IPv6 Peering Macro is set, this will be used to generate IPv6 inbound prefix filters, otherwise the IPv4 Peering Macro will be used for both. If neither is set, the IRR policy of the AS number will be used. Use AS-NULL to disable one or the other protocol peering macro if only one is required.
It is not possible to have a different ASN for IPv4 and IPv6. We are not aware of any cases where this should be necessary but if it is, create two customers.
The Peering Policy is informational only and is displayed in member lists. Typically speaking, route server members should have an open peering policy but others are possible if you use standard route server communities for controlling the distribution of prefixes.
The IRRDB source sets the database where IXP Manager queries the customer's IRR data from. See the IRRDB feature page for more information.
The checkbox labelled Active Peering Matrix indicates whether or not the customer's route server and bilateral peering sessions should appear in the public peering matrix.
All of this is purely informational and is used by IX staff to contact the member about various issues. It is also available to other customers of the exchange to similarly contact their bilateral peers with any issues.
"},{"location":"usage/customers/#reseller-details","title":"Reseller Details","text":"This section will only be displayed if reseller functionality is enabled.
See the reseller instructions for details on this.
"},{"location":"usage/customers/#welcome-emails","title":"Welcome Emails","text":"When a new customer is provisioned, you can send them a welcome email from IXP Manager which is a useful way to provide all their connectivity details and other on-boarding information for your IX.
From the Customer Overview page, you will find the Send Welcome Email... option under the tools menu on the top right hand corner of the page:
To be useful, you need to skin the welcome email.
From IXP Manager v4.8.0 onwards, its format is Markdown and it is sent as a HTML email. The file you need to skin is (with an example of how to do it):
cd ${IXPROOT}\nmkdir -p resources/skins/example/customer/emails\ncp resources/views/customer/emails/welcome-email.blade.php resources/skins/inex/customer/emails/\nThe example skin name in the above is just an example. Please read the skinning documentation.
Customer users and administrators can upload and manage logos for customers. To enable this functionality, set the following in your ${IXPROOT}/.env file:
IXP_FE_FRONTEND_DISABLED_LOGO=false\nWhen you do this, the ability to manage logos will appear:
Logos will then be shown in the customer overview page and a new admin left-hand-side menu option called Member Logos (which shows all logos).
Logos are stored under ${IXPROOT}/public/logos in a sharded directory structure based on the SHA1 of the image content.
Following a feature request, we have a configuration option which can be set to allow each IXP Manager installation customise how the customer / member name is displayed. E.g. Acme Ltd or Acme Ltd (AS65500) for example.
You can customise this by setting the following option in your .env:
IXP_FE_CUSTOMER_NAME_FORMAT=\"\"%a (AS%i)\"\nThe above is the default which uses the abbreviated name and the customer's ASN. You can see the available options in the config/ixp_fe.php file.
You can also find more detail in this issue thread.
"},{"location":"usage/customers/#registration-and-billing-details","title":"Registration and Billing Details","text":"After you add a new customer (or from the customer overview page from the dropdown edit icon on the right of the title area, you can select Edit Billing/Registration Details), you will get the following form:
All of these details are informative only and only available to administrative users.
"},{"location":"usage/customers/#notification-of-billing-details-changed","title":"Notification of Billing Details Changed","text":"If you want notification of a customer's billing details being changed by email, set the following parameter in your ${IXPROOT}/.env file:
IXP_FE_CUSTOMER_BILLING_UPDATES_NOTIFY=\"mail@example.com\"\nThis can be useful to alert your accounts / billing staff of these changes automatically.
If you need multiple people notified, use an alias address encompassing all the users.
Prior to v4.8, you had to edit the config/ixp_tools.php configuration file and set the billing_updates_notify array element. If this file does not exist, create it from the suggested template: cp config/ixp_tools.php.dist config/ixp_tools.php.
IXP Manager makes customer/member details available publicly (without login) through the Member Information menu item. To disable this, set the following in your .env:
IXP_FE_CUSTOMER_DETAILS_PUBLIC=false\nIn IXP Manager v6, we changed the database access layer to Laravel's Eloquent. As part of this work, we added a new listener for any UI based changes to database objects.
You will find [View logs] buttons through IXP Manager and these will link to the appropriate entries in the Logs controller (which you can find in the left hand menu under IXP UTILITIES).
NB: logs are expunged after six months. We feel this is a useful compromise between: auditing changes; keeping the database from growing unnecessarily large; and data privacy (as logs include user and contact objects).
A sample of the logs list for a rack / cabinet:
As you can see, for the purposes of demonstration, I created, edited and then deleted a rack.
The creation log contains:
The edit log highlights the changes made:
The creation log contains:
And the deletion log retains the data:
"},{"location":"usage/email/","title":"Configuring Email","text":"IXP Manager uses Laravel's mail system to send email. This system allows for many possible email sending drivers (such as Mailgun, Postmark, Amazon SES, etc.). If you wish to use one of these services than please refer to the official documentation. You can also read the config/mail.php configuration file in your IXP Manager installation for further details. NB: we link to the 'master' version of Laravel's documentation above - see IXP Manager's composer.json file and use the appropriate version of Laravel's documentation to match.
This guide will explain how to configure and test IXP Manager to send email using a standard SMTP service.
"},{"location":"usage/email/#configuring-smtp","title":"Configuring SMTP","text":"A sample SMTP configuration block in your IXP Manager .env file would be:
### Email Settings.\n#\n# We use Laravel's mail system - see: https://docs.ixpmanager.org/usage/email/\n#\n# The default setting are as follows:\n#\n# MAIL_MAILER=\"smtp\"\n# MAIL_HOST=\"localhost\"\n# MAIL_PORT=25\n# MAIL_ENCRYPTION=false\n# MAIL_USERNAME=\n# MAIL_PASSWORD=\nThe options that are commented out above show defaults. Under the hood, Laravel currently uses swiftmailer and the parameters above are passed through to that library (this changes from Laravel v9).
The configuration options for SMTP in the .env file are as follows.
MAIL_MAILER=\"smtp\" - this is the mail transport to use. The other available options are outside the scope of this documentation.
MAIL_HOST is the hostname or IP address of your SMTP relay server. We would generally expect an IXP to have an internal SMTP relay server within the management network to handle the sending of email from monitoring systems, cron processes, IXP Manager, etc. This can also be localhost or 127.0.0.1 if you are running a local daemon such as Postfix.
MAIL_PORT is the TCP port which the mail relay server listens for connections. Typical values are 587 for TLS encrypted mail servers and 25 for unencrypted mail servers (these should be on your local network only - if you are using a third party or remote relay service, you should use TLS or SSL encryption).
MAIL_ENCRYPTION can be \"tls\" or \"ssl\" for encryption. If you are using localhost or an internal relay server without encryption, set this to MAIL_ENCRYPTION=false.
Finally, MAIL_USERNAME and MAIL_PASSWORD can be set if your mail relay server requires authentication. If unset, then no authentication is assumed (which is the default).
A local SMTP relay server on the same host as IXP Manager would therefore require no configuration as the defaults mirror:
MAIL_MAILER=\"smtp\"\nMAIL_HOST=\"localhost\"\nMAIL_PORT=\"25\"\nMAIL_ENCRYPTION=false\n# MAIL_USERNAME=\n# MAIL_PASSWORD=\nIXP Manager sends emails using the name and email address configured in the following .env parameters:
IDENTITY_NAME=\"${IDENTITY_LEGALNAME}\"\nIDENTITY_EMAIL=\"ixp@example.com\"\nWhere ${IDENTITY_LEGALNAME} means use the value as configured in the IDENTITY_LEGALNAME .env parameter.
You should set these as appropriate to your IXP.
"},{"location":"usage/email/#testing-smtp","title":"Testing SMTP","text":"A new Artisan SMTP test utility was introduced in IXP Manager >v5.7.0. You can run it as follows:
$ php artisan utils:smtp-mail-test [-v] {recipient-email}\nA example of a working test run looks like this:
$ php artisan utils:smtp-mail-test me@example.com\nThis utility allows you to test your SMTP settings to verify that IXP Manager can send email.\n\nTesting using the following parameters:\n\n+------------+---------------------+\n| Driver | smtp |\n| Host | localhost |\n| Port | 25 |\n| Encryption | |\n| Username | |\n| Password | |\n| From Name | INEX DEV IXP |\n| From Email | test@ixpmanager.org |\n+------------+---------------------+\n\n\n\nTrying to send email...\n\nSUCCESS - email has been sent.\nIf you add the verbose option you will also be shown the SMTP dialog:
$ php artisan utils:smtp-mail-test -v me@example.com\n\n...\n\n========================================\nSMTP Dialog:\n\n++ Starting Swift_SmtpTransport\n<< 220 mail.example.com ESMTP Postfix\n\n>> EHLO [127.0.0.1]\n\n<< 250-mail.example.com\n250-PIPELINING\n250-SIZE 80200000\n250-VRFY\n250-ETRN\n250-STARTTLS\n250-ENHANCEDSTATUSCODES\n250-8BITMIME\n250-DSN\n250 SMTPUTF8\n\n>> STARTTLS\n\n<< 220 2.0.0 Ready to start TLS\n\n...\nIf there is an error sending an email, it will provide the exception thrown and the error message:
...\nTrying to send email...\n\nFAILED TO SEND EMAIL!\n\n\n\nException thrown: ErrorException\nError: stream_socket_enable_crypto(): Peer certificate CN=`mail.example.com' did not match expected CN=`192.0.2.16'\nFile: /tmp/dev/ixpm/vendor/swiftmailer/swiftmailer/lib/classes/Swift/Transport/StreamBuffer.php\nLine: 94\nSimilarly, if you provide the verbose option in the case of an error, you will be provided with a stack trace and the SMTP dialog.
"},{"location":"usage/interfaces/","title":"Customer Interfaces","text":"This section explains how to set up a customer interface.
"},{"location":"usage/interfaces/#video-tutorial","title":"Video Tutorial","text":"We created a video tutorial demonstrating these steps. You can find the video here in our YouTube channel. As always, the full catalog of video tutorials is here.
"},{"location":"usage/interfaces/#database-overview","title":"Database Overview","text":"To fully understand how IXP Manager treats customer interfaces, you need a little background on the database schema. This will also help explain why we have laid out the UI as it is.
The original database schema dates from pre-2005 and has stood the test of time extremely well.
The above is described as follows:
The best way to provision a new interface for a customer is to use the wizard. This can be accessed from the customer's overview page via a menu on the top right:
When you open the wizard, you will see:
This can be used to provision a single port standard customer connection. If they customer needs a LAG or other non-standard options, these can be added afterwards.
"},{"location":"usage/interfaces/#general-interface-settings","title":"General Interface Settings","text":"The customer should be prefilled and read-only as you enter the wizard from a specific customer overview page.
You would normally just select your main / primary peering VLAN from the VLAN dropdown. There are some notable exceptions:
Use 802.1q framing checkbox if the port should be tagged facing the customer. If you are not using any automation tools, this will be informational for you rather than production affecting.This section allows you to select the physical interface / switch port for the connection.
Switch: a dropdown list of all switches. Be careful as at present this list is all active switches rather than switches on the same infrastructure as the selected VLAN from General Interface Settings.Port: the switch port to use. This is dynamically populated when the switch is selected and will only show ports of type Peering or type Unset / Unknown (these are set on a per port basis when adding / editing switches).Status: the port status currently has one of five options. They effectively work as a boolean where Connected means on/enabled and the rest mean disabled as explained below. In practice, we tend to just use three states:
Connected: this is the most important. When a virtual interface has any port with the Connected state, then IXP Manager will consider this connection active and will generate router configuration, monitoring configuration, etc.
Awaiting X-Connect: the customer has requested an upgrade / new port and we are awaiting for the co-location provider / customer to get the cross connect organised.Quarantine: the port is connected and is under going quarantine prior to being moved onto the production peering LAN. During quarantine, INEX checks the port to ensure only ARP, IPv4 and IPv6 packets are received (no *-discovery, STP, etc. as well as a number of other things).The Not Connected and Disabled states have the same effect as (2) and (3) above and can be used as informational settings where (2) and (3) do not apply.
Speed and duplex are self explanatory. These settings in the physical interface entity are informational unless you are doing automation. They also have knock on effects to (for example) graphing - where the MRTG max value on an interface is set to this to prevent weird excessive spikes on counter rollovers.
"},{"location":"usage/interfaces/#general-vlan-settings","title":"General VLAN Settings","text":"These settings apply to the VLAN interface.
The Max BGP Prefixes is a setting used to determine max prefixes on router BGP peers - please see the global version of this as explained in the customer section for details.
If Apply IRRDB Filtering is not set, then the route servers will accept any prefixes advertised by the customer (note that the default templates will filter martians and apply a max prefix limit). Generally speaking this is a very bad idea and should only be used in exceptional cases. INEX never uses this setting - but demand from other IX's had it added.
Multicast Enabled is informational only. INEX used to support multicast on the peering LAN but removed support in 2015 due to lack of interest and added complexity / cost when purchasing new switches.
If Route Server Client is checked, then IXP Manager will configure a BGP peer for this connection when generating route server configurations. It is also used in other areas to show if a member uses the route servers or not, by the Peering Manager to calculate missing BGP sessions, etc.
Similarly, if AS112 Client is checked, then IXP Manager will configure a BGP peer for this connection when generating AS112 router configurations.
When IPv4 / IPv6 Enabled is checked under General Interface Settings above, these two sections will be available.
The same details apply to IPv4 and IPv6 options so we will document them together.
IP Address: the IP address to assign to this customer. This is taken from available IP addresses for the VLAN selected in General Interface Settings.Hostname: if you use IXP Manager to configure your DNS ARPA entries, the hostname entered here will be returned when a PTR request is made for the assigned IP address. Enter a complete hostname without trailing period such as: www.example.com.BGP MD5 Secret: The will be used for generating router configurations.Can Ping: IXP Manager generates configuration for a number of other tools such as Smokeping and Nagios which ping customer routers. These are invaluable tools for problem solving, monitoring and graphing long term trends. We enable this by default unless a customer specifically asks us not to.Can Monitor RC BGP: this is more of a legacy option for configuration builders that used to check for established route collector BGP sessions and warn if not present. This is deprecated and will be removed.If you wish to make Hostname above optional, set the following .env configuration option:
IXP_FE_VLANINTERFACES_HOSTNAME_REQUIRED=false\nOnce an interface has been added as per the above wizard instructions, you can view and edit the interface by selecting the edit icon against the connection you are interested in from the Ports tab on the customer overview page. When you do that, you will see a screen such as the following:
You can see from the layout of this screen how it ties in with the schema explained above.
"},{"location":"usage/interfaces/#virtual-interface-details","title":"Virtual Interface Details","text":"The screenshot above shows the virtual interface details with the Advanced Options shown. The additional fields here that were not in the wizard are described below.
Link aggregation / LAG framing is mostly informational unless you are doing automation. There are some restrictions. Namely / specifically:
The Virtual Interface Name is again mostly informational unless you are doing automation. It should be the start of the LAG name without the number. On an IOS device this would be Port-channel for example. Matched with this is the Channel Group Number with is tacked onto the end of the Virtual Interface Name. Leave it as 0 and when you check Link aggregation / LAG framing and save the changes, IXP Manager will set this to the next available unused port channel / bundle / LAG number on that switch.
Both Description and MTU are informational.
You can add additional physical interfaces to a connection / virtual interface. This effectivily means you are creating a LAG. The form for adding additional physical interfaces is identical to that in the wizard.
"},{"location":"usage/interfaces/#vlan-interfaces","title":"VLAN Interfaces","text":"The most common use case of more than one VLAN Interface is when your customer may also have private VLANs on their connection.
Other than that, the VLAN interface add / edit form has all the same elements as the wizard with one addition:
Busy host: this flag indicates that the customer's router is unusually slow to reply to ICMP echo requests and that when monitoring, the configuration should allow for warnings after a 5sec RTT rather than 1sec.In cases where the IXP provides subrate connectivity, the declared port speed at an IXP may not match the port speed which is configured on the access device. Support for this scenario was included in v6.2.0:
rate_limit column on the database as the actual request for partial port speeds is really a request to honour rate limits on ports. If there are other use cases this can still be used, the actual physical (production) effect is determined by how individual IXPs use this information in their provisioning systems / as they manually configure switches.This page will collect various operational notes, hints and tips and FAQs over time.
"},{"location":"usage/operational-notes/#server-topology","title":"Server Topology","text":"Added 2020-10-28, Nick Hilliard
On the mailing list, we were asked about recommended server topologies. Nick answered:
At INEX, we split services over different physical machines running virtual servers to keep them as separate as possible. This means we can perform maintenance on individual components relatively easily without affecting other components. Currently we have the following configured:
We run route servers on different physical servers. They're kept separate (different hardware, different hypervisor, not attached to the orchestration system) because they're categorised as critical production servers, i.e. if they go down, production IXP traffic may be affected.
It doesn't really matter what hypervisor software you use. We've used ESXi, Xencenter and XCP-ng and they all work fine. Our current preference is for XCP-ng because it provides live migration of VMs on local disk storage without a license (XC and ESXi both need a license for this).
It would be a good idea to use two physically identical servers for the hypervisor, so that you can use services like VM migration and live-migration. For disk storage, we'd recommend RAID with battery backup, so that you can add or replace physically failed disks easily.
One thing that does matter is disk I/O on the sflow server - if you have anything more than about 30 IXP participants, then you need SSD to handle the iops.
"},{"location":"usage/operational-notes/#backup-ixp-manager","title":"Backup IXP Manager","text":"Added 2020-03-24, Barry O'Donovan
On the mailing list, someone asked about backing up IXP Manager before an upgrade. Barry O'Donovan answered this here and the advice was:
It's not something I generally do as we have our production servers backed up nightly. But:
Assuming you have IXP Manager installed at /srv/ixpmanager then I'd proceed as follows (replacing yyyymmdd with today's date):
Put IXP Manager in maintenance mode (php /srv/ixpmanager/artisan down).
Take a MySQL dump:
mysqldump --lock-tables --quick --skip-events --triggers \\\n -h <host> -u <username> -p<password> ixpmanager | \\\n bzip2 -9 >/srv/ixpmanager/db-yyyymmdd.sql.bz2\nDuplicate the IXP Manager directory in its entirety:
rsync -a /srv/ixpmanager/ /srv/ixpmanager-yyyymmdd\nUpgrade IXP Manager per the usual instructions.
If you need to rollback then:
Restore the database from the dump above:
bzcat /srv/ixpmanager/db-yyyymmdd.sql.bz2 | \\\n mysql -h <host> -u <username> -p<password> ixpmanager\nShift the directories around:
mv /srv/ixpmanager /srv/ixpmanager-failed\nmv /srv/ixpmanager-yyyymmdd /srv/ixpmanager\nAdded 2020-04-21, Barry O'Donovan
A common question is will IXP Manager work with Nginx + php-fpm considering the automated installation script uses Apache. The short answer is: yes, of course! Use whichever you're most comfortable with.
From experience, people who install IXP Manager and end up asking for installation help are not overly comfortable with Linux / web servers. The easiest installation and maintainable option (by a measurable distance) is Apache. This is why the installation script uses it.
Do we recommend either / any advantages to one over the other? No and no. IXP Manager is a low volume / transaction application. Whatever typical performance benefits you might expect from Nginx + php-fpm simply won't apply here.
"},{"location":"usage/switches/","title":"Switches","text":"The central element of an IXP is the switches. IXP Manager provides comprehensive management features for switches (and more complex configurations such as VXLAN overlay networks).
We strongly advise against trying to add and manage switches in IXP Manager without SNMP. SNMP v2 is a core element of how switches work within IXP Manager including accurate port discovery, graphing, port states, optic availability, etc.
"},{"location":"usage/switches/#listing-switches","title":"Listing Switches","text":"You access the switch management functionality in IXP Manager via the Switches menu option under IXP Admin Actions in the left hand side control menu. The default action is to list the configured switches:
From the above screenshot, you will notice a number of features:
In the list view above, you will also notice that there are per row / per switch options on the right:
From the list view described above, click the plus button in the top right to add a switch. Switches are added by SNMP poll so the first step is to provide a hostname and SNMP v2 community:
The switch must respond to SNMP queries from the server on which IXP Manager is installed. This can be testing on the command line as follows:
root@ixpmanager:~# snmpget -c yourcommunity -v 2c switch01.mgmt.example.com .1.3.6.1.2.1.1.1.0\niso.3.6.1.2.1.1.1.0 = STRING: \"Arista Networks EOS version 4.18.0F running on an Arista Networks DCS-7280SR-48C6\"\nAfter completing the details and clicking Next >>, IXP Manager will poll the switch and present you with the second (and last) stage in adding a switch:
The important things to note about this are:
The discovery of a switches vendor, model, operating system details and serial number - as well as MAU details - is achieved via a third party package called OSS_SNMP. While this shares an author in common with IXP Manager, it is a separate project.
If your switch is not discovered automatically, you can open a ticket with the OSS_SNMP project directly and ensure you provide the details requested here.
"},{"location":"usage/switches/#managing-switch-ports","title":"Managing Switch Ports","text":"Recall the per row / per switch options on the right hand side of each switch's row when listing switches:
These options allow you to list and manage switch ports. Of these, the most relevant is the View / Edit Ports under SNMP Actions which leads to a page as follows:
The page allows you to:
Note that deleting ports is not a permanent action if the port physically exists and is discovered in a subsequent SNMP poll.
"},{"location":"usage/switches/#switch-port-types","title":"Switch Port Types","text":"While some of these are clear from the name, we will explain each type here for completeness:
Switch and switch port information in the database can go stale very quickly. As such, IXP Manager will poll switches using SNMP every five minutes via the task scheduler. You can do it manually via the Artisan command:
/srv/ixpmanager/artisan switch:snmp-poll\nThe command signature is:
switch:snmp-poll [--log] [--noflush] [-q, --quiet] [<switch>]\nwhere:
[-q, --quiet] does not output anything unless there is an error. Should be used for cron jobs.[--log] outputs detailed SNMP polling information to /srv/ixpmanager/storage/logs/laravel.log. You can tail this file when running it to help diagnose any issues.[--noflush] polls the switch but does not write anything to the database.[<switch>] allows you to optionally limit the polling to a single named switch (the switch's name, not hostname). If not specified, all pollable switches are polled.Not that inactive switches are not polled unless an inactive switch name is explicitly specified.
Similarly, any switch that is not set to poll (Poll checkbox with adding / editing a switch) will be skipped unless explicitly specified.
"},{"location":"usage/switches/#matching-database-ports-to-switch-ports","title":"Matching Database Ports to Switch Ports","text":"When we poll the switch to update the database, we need a method to match ports in the database with those on the switch so we can update, remove and add ports. This is achieved using the ifIndex as reported by SNMP.
We have tried other methods in the past including ifName but there is no perfect solution to this as switch operating system updates can cause any of these data points to change. In the end we settled on ifIndex.
If you find that a switch update had caused the ifIndex to change, then you can reindex the database by updating the ifIndex based on the ifName using the switch:reindex-ifindex Artisan command.
To perform a test run and see what would change, execute it per the following example:
$ ./artisan switch:reindex-ifindex swi2-nwb1-3 --noflush\n - swp1 unchanged, ifIndex remains the same\n ...\n - bond2 unchanged, ifIndex remains the same\n - bond3 ifIndex changed from 10056 to 10178\n ...\n - mgmt unchanged, ifIndex remains the same\n\n*** --noflush parameter set - NO CHANGES MADE TO DATABASE\nIf you are comfortable with the changes proposed, rerun it
Operational Note: if performing switch operating system updates that are known to change the ifIndex, it is strongly advised to disable polling (Poll checkbox when adding / editing a switch) for the duration of the upgrade work and until after you have reindexed the ports.
ifType)","text":"By default, IXP Manager restricts the type of port to ifType ethernetCsmacd, l2vlan and l3ipvlan, because most network operating systems include various types of virtual port which are not relevant to IXP operation. Sometimes, some vendors (e.g. Juniper) use a richer set of ports, and a wider selection of ifTypes. If these ifTypes were enabled in the general case, IXP Manager operators would be presented with lots of port types that were irrelevant to their IXP service.
This is a traditional user interface situation: we need a balance between hiding the inherent complexity of what's going on, while enabling enough flexibility to allow the operator to do what they need, while ensuring that the underlying code base and config is maintainable as a long term proposition.
If you examine the file config/ixp.php you'll find an element called snmp['allowed_interface_types']. The default behaviour is equivalent to creating a .env setting as follows:
IXP_SNMP_ALLOWED_INTERFACE_TYPES=\"6,135,136\"\nwhere 6, 135 and 136 are the SNMP codes for ifType ethernetCsmacd, l2vlan and l3ipvlan respectivily. Note that over time we may add more to the default stack - the configuration file will always represent the default status.
If you wish to have IXP Manager poll additional interface / port types on your switch then set this .env variable. For example, to additionally allow irb interfaces on Juniper (which at time of writing use ifOther) then set it as follows:
IXP_SNMP_ALLOWED_INTERFACE_TYPES=\"1,6,135,136\"\nMore detail may be found in the originating GitHub issue #695).
"},{"location":"usage/switches/#migrating-customers-to-a-new-switch","title":"Migrating Customers to a New Switch","text":"When moving IXP customers from one switch to another, add the new switch into the IXP Manager as described above. The customer port assignments can easily be changed to the new switch using the IXP Manager web interface. It is advisable not to delete the old port assignment and create a new one, because if this happens, then the old customer port graphs will not be preserved.
The process is, for each customer:
When the switch port updates have been completed, it's advisable to rebuild the mrtg configuration using the CLI tool and (if using dynamically discovered MAC addresses) also to update the layer 2 database, otherwise some MRTG and sflow stats may be lost.
"},{"location":"usage/switches/#related-tools","title":"Related Tools","text":""},{"location":"usage/switches/#port-audit","title":"Port Audit","text":"A new feature (adding in v4.9.0) allows IXP Manager administrators to audit port speeds as configured in physical interfaces against what has been discovered in the last SNMP run.
You can run it from Artisan such as the following example:
./artisan audit:port-speeds\n\nAudit of Configured Physical Interface Port Speeds Against SNMP Discovered Speeds\n\n+------------------------------+----------+----------------+-----------------------+----------+------------+\n| Customer | PI DB ID | Switch | Switchport | PI Speed | SNMP Speed |\n+------------------------------+----------+----------------+-----------------------+----------+------------+\n| INEX Route Servers [AS43760] | 14 | swi2-tcy1-2 | GigabitEthernet27 | 0 | 1000 |\n| INEX [AS2128] | 15 | swi1-ix1-2 | X460-48t Port 47 | 0 | 1000 |\n| INEX [AS2128] | 16 | swi2-ix1-1 | GigabitEthernet25 | 0 | 1000 |\n| AS112 Reverse DNS [AS112] | 21 | swi2-nwb1-1 | X670G2-48x-4q Port 15 | 0 | 1000 |\n| INEX [AS2128] | 357 | swic-cix-2 | GigabitEthernet27 | 100 | 1000 |\n| AS112 Reverse DNS [AS112] | 590 | swt-cwt1-edge1 | swp3 | 10000 | 1000 |\n+------------------------------+----------+----------------+-----------------------+----------+------------+\nThe above examples are edge cases as they are not physically connected devices but rather virtual machines. This audit can be added to cron such that it will only make noise if an issue is found with something like:
13 9 * * * www-data /srv/ixpmanager/artisan audit:port-speeds \\\n --cron --ignore-pids 14,15,16,21,357,590\nUser management prior to v5.0 was handled differently - please see this page for the legacy usage.
The IXP Manager Users feature allows you to add and manage users (people who can login to IXP Manager) on a per customer basis including:
For details on session management and two-factor authentication, please see this page. For logging in with PeeringDB OAuth, please see this page.
"},{"location":"usage/users/#types-of-users","title":"Types of Users","text":"There are three types of user:
privs = 1).privs = 2).privs = 3). FULL ACCESS TO ALL CUSTOMERS AND FUNCTIONS. This is only for your IXP staff!If you are a Superuser, you can manage users in one of two ways:
If you are a customer administrator user, you can manage your own users via the Users menu in the top menu bar. In all cases, you will be given a list of users such as:
The available actions include:
Since a user can be associated with multiple customers, the new user you wish to add may already exist on the system. For this reason, the first step of adding a user is to just provide and email address:
If the user does not exist, you will be invited to complete the rest of the standard details:
Note that, as always, the [Help] button will provide context help for each input field. Once you successfully complete the details, the new user will be sent a welcome email (see below for details) and invited to set their password.
If any users do exist with this email, you will be shown the user's name, username (and, if a superadmin, the other customer(s) the user is associated with). Note that it is possible for an email to be associated with more than one username but this should only happen for legacy users that predate the ability to assign a user to more than one customer.
Select the user you wish to add to the customer and set the desired privilege and click [Add User]. The new user will be sent a specific welcome email for users that already exist on the system to let them know they have been added to a new customer account (see below for details).
"},{"location":"usage/users/#deleting-users","title":"Deleting Users","text":"Note that deleting a user results in one of two actions:
There are three command line tools for managing users available since v6:
user:create: create a user.user:find: find and print user(s) detailsuser:set-password: set the user's passwordHere's a sample run of user:set-password:
\u276f ./artisan user:set-password --search john\n+-----+------------+------------+----------------+--------------+-------+\n| ID | Name | Username | Email | Customers | Privs |\n+-----+------------+------------+----------------+--------------+-------+\n| 115 | John Smith | sjohnsmith | js@example.com | Acme Limited | CA |\n| ... | | | | | CA |\n+-----+------------+------------+----------------+--------------+-------+\n\n Enter ID to change password for:\n > 115\n\n Password or (return to have one generated):\n >\n\nGenerated password: 1eHRUoDNiGBlkJEz\nPassword set.\nThis section explains the handling around users with multiple customers.
When logging in, the last customer that the user acted for will be selected. If this customer does not exist / the relationship no longer exists / no previous customer set then a customer will be chosen at random.
If a user is associated with more than one customer, then the facility to switch users can be found under the My Account menu on the top right:
The current customer is highlighted.
"},{"location":"usage/users/#welcome-email","title":"Welcome Email","text":"IXP Manager sends a welcome email to all newly created users.
The default template for new users this can be found at resources/views/user/emails/welcome.blade.php. When an existing user is associated with an additional customer, the following template is used: resources/views/user/emails/welcome-existing.blade.php.
If you wish to change these templates, you can do so via the standard skinning mechanism.
"},{"location":"usage/users/#logging-in-as-another-user","title":"Logging in as Another User","text":"Administrative users (AUTH_SUPERUSER) can switch to other users to see what they see via the user list or the customer overview page.
The purpose of this is for both development and for support staff to replicate issues as reported by users.
"},{"location":"usage/users/#passwords-and-password-hashing","title":"Passwords and Password Hashing","text":"As of v4.5, all passwords are stored as bcrypt with a cost >=10.
As of v4.9, administrative users are unable to set a user's password. User's can set (and reset) their passwords via their Profile page or using the password reset functionality.
"},{"location":"usage/legacy/users/","title":"Users","text":"This page refers to a legacy version of IXP Manager (<v5.0)User management prior to v5.0 was handled differently - please see this page for current usage.
The IXP Manager Users feature allows you to add and manage users (people who can login to IXP Manager) on a per customer basis including:
See the entity definitions here.
There are three types of user:
AUTH_CUSTUSER - a standard customer user with portal access to a specific customer's dashboard (priv == 1).AUTH_CUSTADMIN - a customer administrative user. The only purpose of this account is to allow customers to create, edit and remove their own users. No other access is available through a CUSTADMIN login (priv == 2).AUTH_SUPERUSER - IXP staff only. FULL ACCESS TO ALL CUSTOMERS AND FUNCTIONS. This is only for your IXP staff! (priv == 3)There is a fourth internal permission but no user record exists for it:
AUTH_PUBLIC - a visitor who has not logged into IXP Manager (priv == 0).Additional Historical Perspective: the use of AUTH_CUSTADMIN was modeled on RIPE's equivalent model at the time. RIPE have since abandoned this model and it is our intention to do likewise.
"},{"location":"usage/legacy/users/#welcome-email","title":"Welcome Email","text":"IXP Manager sends a welcome email to all newly created users. The default template for this can be found at resources/views/user/emails/welcome.blade.php. If you wish to change this, you can do so via the standard skinning mechanism.
Administrative users (AUTH_SUPERUSER) can switch to other users to see what they see via the user list or the customer overview page.
The purpose of this is for both development and for support staff to replicate issues as reported by users.
"},{"location":"usage/legacy/users/#planned-work","title":"Planned Work","text":"As IXP Manager v5 evolves, we would like to make a number of changes:
Prior to IXP Manager v4.5, we supported both plaintext and bcrypt password hashing. There was a historical justification at INEX for support plaintext (this may still be documented here). However, IXP Manager is meant to represent the best practices for managing IXP's. As such, plaintext support was removed in v4.5.
As of v4.5, all passwords are stored as bcrypt with a cost >=10.
Prior to IXP Manager v4.9, we allowed administrative users to set a user's password. This has been removed as we believe it to be bad practice - only a user should know their own password. User's can set (and reset) their passwords via their Profile page or using the password reset functionality.
"},{"location":"usage/legacy/users/#historical-perspective","title":"Historical Perspective","text":"IXP Manager of pre-April 2013 had separate contacts and users which - at the time - we felt was quite confusing. LONAP sponsored a rework of this in 2013 to merge the concept of users and contacts with login privileges. Strangely, this actually caused more confusion and also was a developer nightmare with hacked in code to handle the database tables in multiple places. As such, in 2019 with release v4.9, this was undone and contacts and users are now separate entities again.
"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to IXP Manager","text":"IXP Manager is the most trusted IXP platform worldwide.
It is a full stack management system for Internet eXchange Points (IXPs) which includes an administration and customer portal; provides end to end provisioning; and both teaches and implements best practice. It allows IXPs to manage new customers, provision new connections / services and monitor traffic usage. It has a number of provisioning templates including its ability to generate secure proven route server configuration and provides a built in looking glass for these.
INEX are pleased to release IXP Manager under an open source license (the GNU Public License V2) which we hope will benefit the wider IXP community, and especially new and small IXPs looking to expand.
Additional information: https://www.ixpmanager.org/
"},{"location":"#other-links","title":"Other Links","text":"INEX is an Internet eXchange Point and Ireland's IP peering hub. It is a neutral, industry-owned Association, founded in 1996, that provides IP peering facilities for its members. INEX membership is open to all organisations that can benefit from peering their IP traffic. See: https://www.inex.ie/. INEX is IXP Manager's core team and founder.
Principle Authors:
The team at INEX deserves special mention - its CEO, Eileen Gallagher for her steadfast support and promotion of the project; the INEX Board of Directors - past and present - for their approval to open source the project and their on-going support of the project; and all team members who contribute real-world feedback, suggestions and all-round support!
See the team page on the IXP Manager website for more details.
We are also grateful for all the individuals who have contributed code, issues, mailing list help and feature requests.
"},{"location":"#sponsors","title":"Sponsors","text":"IXP Manager is extremely grateful to its existing sponsors and patrons and continues to seek sponsors for on going development. If you are interested, please see out call for sponsorship.
"},{"location":"#license","title":"License","text":"IXP Manager is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version v2.0 of the License.
IXP Manager is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License v2.0 along with IXP Manager. If not, see:
http://www.gnu.org/licenses/gpl-2.0.html
"},{"location":"#documentation-license","title":"Documentation License","text":"This documentation is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
"},{"location":"dev/api/","title":"API","text":"You'll find API documentation when logged into IXP manager under My Account / API Keys.
"},{"location":"dev/authentication/","title":"Authentication & Session Management (Development Notes)","text":"Please read the authentication usage instructions first as that provides some key information for understanding the below brief notes.
IXP Manager uses Laravel's standard authentication framework with Laravel's Eloquent ORM.
See also Barry O'Donovan's PHP write up of the 2fa and user session management changes introduced in v5.3.0 and the v5.2.0 to v5.3.0 diff.
"},{"location":"dev/authentication/#multiple-sessions-remember-me-cookies","title":"Multiple Sessions / Remember Me Cookies","text":"The default Laravel functionality around remember me is a single shared token across multiple devices. In practice this never worked well for us (but this is most likely a consequence of using LaravelDoctrine). Regardless, we also wanted to expand the functionality to uniquely identify each session and allow other sessions to be logged out by the user.
"},{"location":"dev/authentication/#sessionguard-and-userprovider","title":"SessionGuard and UserProvider","text":"Most of the functionality exists in the session guard and user provider classes. We have overridden these here:
app/Services/Auth/SessionGuard.phpapp/Services/Auth/EloquentUserProvider.phpAgain, the idea is to minimise the changes required to the core Laravel framework (and Laravel Eloquent).
"},{"location":"dev/authentication/#how-it-works","title":"How It Works","text":"When you log in and check remember me, IXP Manager will create a new UserRememberToken database entry with a unique token and an expiry set to config( 'auth.guards.web.expire') (note this is minutes).
Your browser will be sent a cookie named remember_web_xxxx (where xxxx is random). This cookie contains the encrypted token that was created (UserRememberToken). IXP Manager uses this cookie to create a new authenticated session if your previous session has timed out, etc.
Note that this remember_web_xxxx cookie has an indefinite expiry date - the actual expiring of the remember me session is handled by the expiry field in the UserRememberToken database entry.
When you subsequently make a request to IXP Manager:
user() method) first tries to retrieve your session via the standard browser session cookie (laravel_session).remember_web_xxxx cookie and, if it exists, validates it and looks you in with a new laravel_session.Two-factor authentication (2fa) is implemented using the pragmarx/google2fa package via its Laravel bridge antonioribeiro/google2fa-laravel.
The database table for storing a user's secret key is user_2fa. 2FA for a user is enabled if:
$user->user2FA entity (one to one); andAuth::getUser()->user2FA->enabled is true.Once 2fa is enabled, the mechanism for enforcing it is the 2fa middleware. This is applied to all authenticated http web requests via app/Providers/RouteServiceProvider.php.
We use the antonioribeiro/google2fa-laravel bridge's PragmaRX\\Google2FALaravel\\Events\\LoginSucceeded event to update a user's remember me token via the listener IXP\\Listeners\\Auth\\Google2FALoginSucceeded. The update is to set user_remember_tokens.is_2fa_complete to true so that the SessionGuard knows to skip 2fa on these sessions.
IXP Manager grew out of a code base and schema that started in the early '90s. Long before test driven development or behaviour driven development was fashionable for PHP. However, as IXP Manager is taking over more and more critical configuration tasks, we continue to back fill some automated testing with continuous integration for critical elements.
We use GitHub Actions for continuous integration which is provided free for public repositories.
Our current build status is:
The CI system runs the full suite of tests every time a commit is pushed to GitHub. As such, any build failing states are usually transitory. Official IXP Manager releases are only made when all tests pass.
We use two types of unit tests:
We won't be aggressively writing tests for the existing codebase but will add tests as appropriate as we continue development. What follows is some basic instructions on how to set up tests and an overview (or links) to some of the tests we have implemented.
DISCLAIMER: This is not a tutorial on unit testing, phpunit, Laravel Dusk or anything else. If you have no experience with these tools, please read up on them elsewhere first.
"},{"location":"dev/ci/#setting-up-phpunit-tests","title":"Setting Up PHPUnit Tests","text":"Documentation by real example can be found via the GitHub Actions workflow files and the CI data directory which contains scripts, database dumps and configurations.
Testing assumes a known good sample database which contains a small mix of customers with different configuration options. The files generated from this database are tested against known good configuration files. You first need to create a database, add a database user, import this testing database and then configure a .env file for testing (see the one here use here).
In MySQL:
CREATE DATABASE ixp_ci CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_unicode_ci';\nGRANT ALL ON `ixp_ci`.* TO `ixp_ci`@`localhost` IDENTIFIED BY 'somepassword';\nFLUSH PRIVILEGES;\nThen import the sample database:
cat data/ci/ci_test_db.sql.bz2 | mysql -h localhost -u ixp_ci -psomepassword ixp_ci\nNow, create your .env for testing, such as:
DB_HOST=localhost\nDB_DATABASE=ixp_ci\nDB_USERNAME=ixp_ci\nDB_PASSWORD=somepassword\nNote that the phpunit.xml file in the root directory has some default settings matching the test database. You should not need to edit these.
Please review the official documentation here.
You need to ensure the development packages for IXP Manager are installed via:
# move to the root directory of IXP Manager\ncd $IXPROOT\ncomposer install --dev\nYou need to set the APP_URL environment variable in your .env file. This value should match the URL you use to access your application in a browser.
travis / travisci.hecustadmin / travisci and imcustadmin / travisci.hecustuser / travisci and imcustuser / travisci.In one console session, start the artisan / Laravel web server:
# move to the root directory of IXP Manager\ncd $IXPROOT\nphp artisan serve\nAnd then kick off all the tests which includes PHPUnit and Laravel Dusk tests, run:
./vendor/bin/phpunit\nSample output:
PHPUnit 7.2.2 by Sebastian Bergmann and contributors.\n\n............................................................... 63 / 144 ( 43%)\n............................................................... 126 / 144 ( 87%)\n.................. 144 / 144 (100%)\n\nTime: 1.86 minutes, Memory: 103.73MB\nIf you only want to run Laravel Dusk / browser tests, run the following (shown with sample output):
$ php artisan dusk\nPHPUnit 6.5.8 by Sebastian Bergmann and contributors.\n\n.. 2 / 2 (100%)\n\nTime: 12.73 seconds, Memory: 24.00MB\nIf you want to exclude the browser based tests, just exclude that directory as follows:
$ ./vendor/bin/phpunit --filter '/^((?!Tests\\\\Browser).)*$/'\nPHPUnit 7.2.2 by Sebastian Bergmann and contributors.\n\n............................................................... 63 / 142 ( 44%)\n............................................................... 126 / 142 ( 88%)\n................ 142 / 142 (100%)\n\nTime: 1.59 minutes, Memory: 106.41MB\nYou can also limit tests to specific test suites:
$ ./vendor/bin/phpunit --testsuite 'Dusk / Browser Test Suite'\n$ ./vendor/bin/phpunit --testsuite 'Docstore Test Suite'\n$ ./vendor/bin/phpunit --testsuite 'IXP Manager Test Suite'\nPlease see the contributing instructions for full details.
Third-party patches are welcomed for adding functionality and fixing bugs. Before they can be accepted into the project, contributors must sign the below Contributor License Agreement (gpg --clearsign inex-cla.txt) and email it to operations (at) inex (dot) ie.
Individual Contributor License Agreement v1.1\n=============================================\n\nInternet Neutral Exchange Association Company Limited By Guarantee\n\nThis document clarifies the terms under which You, the person listed below,\nmay make Contributions \u2014 which may include without limitation, software, bug\nfixes, configuration changes, documentation, or any other materials \u2014 to any\nof the projects owned or managed by Internet Neutral Exchange Association\nCompany Limited By Guarantee, hereinafter known as \"INEX\".\n\nPlease complete the following information about You and the Contributions.\nIf You have questions about these terms, please contact us at\noperations@inex.ie.\n\nYou accept and agree to the following terms and conditions for Your present\nand future Contributions submitted to INEX. Except for the license granted\nherein to INEX, You reserve all right, title, and interest in and to Your\nContributions.\n\nINEX projects (code, documentation, and any other materials) are released\nunder the terms of the GNU General Public License, v2.0.\n\nYou certify that:\n\n(a) Your Contributions are created in whole or in part by You and You have\nthe right to submit it under the designated license; or\n\n(b) Your Contributions are based upon previous work that, to the best of\nyour knowledge, is covered under an appropriate open source license and You\nhave the right under that license to submit that work with modifications,\nwhether created in whole or in part by You, under the designated license; or\n\n(c) Your Contributions are provided directly to You by some other person who\ncertified (a) or (b) and You have not modified them.\n\n(d) You understand and agree that INEX projects and Your Contributions are\npublic and that a record of the Contributions (including all metadata and\npersonal information You submit with them) is maintained indefinitely and\nmay be redistributed in a manner consistent with INEX's policies and/or the\nrequirements of the GNU General Public License v2.0 where they are relevant.\n\n(e) You are granting Your Contributions to INEX under the terms of the GNU\nGeneral Public License v2.0.\n\nFull Name:\nEmail Addresses:\nDate:\nFor development purposes, we have both Docker and Vagrant build files.
This page on Docker for IXP Manager development should be read in conjunction with the official IXP Manager Docker repository. While that repository is not for development purposes, the terminology and container descriptions apply here also.
"},{"location":"dev/docker/#tldr-guide-to-get-docker-running","title":"TL;DR Guide to Get Docker Running","text":"If you want to get IXP Manager with Docker up and running quickly, follow these steps:
Clone IXP Manager to a directory:
git clone https://github.com/inex/IXP-Manager.git ixpmanager\ncd ixpmanager\ncp .env.docker .env\ncp tools/docker/containers/mysql/docker.sql.dist tools/docker/containers/mysql/docker.sql\nSpin up the Docker containers
docker-compose -p ixpm up\nAccess IXP Manager on: http://localhost:8880/
Log in with one of the following username / passwords:
Admin user: docker / docker01
as112admin / as112adminas112user / as112userAs the IXP Manager ecosystem grows, it becomes harder and harder to maintain ubiquitous development environments. Docker is ideally suited to solving these issues.
The multi-container Docker environment for developing IXP Manager builds an IXP Manager system which includes:
The following are a list of Docker commands that are useful in general but also specifically for the IXP Manager Docker environment.
Note that in our examples, we set the Docker project name to ixpm and so that prefix is used in some of the below. We also assume that only one IXP Manager Docker environments is running and so we complete Docker container names with _1.
# show all running containers\ndocker ps\n\n# show all containers - running and stopped\ndocker ps -a\n\n# stop a container:\ndocker stop <container>\n\n# start a container:\ndocker start <container>\n\n# we create a 'ixpmanager' network. Sometimes you need to delete this when\n# stopping / starting the environment\ndocker network rm ixpm_ixpmanager\n\n# you can copy files into a docker container via:\ndocker cp test.sql ixmp_mysql_1:/tmp\n# where 'ixmp_mysql_1' is the container name.\n# reverse it to copy a file out:\ndocker cp ixmp_mysql_1:/tmp/dump.sql .\n\n# I use two useful aliases for stopping and removing all containers:\nalias docker-stop-all='docker stop $(docker ps -a -q)'\nalias docker-rm-all='docker rm $(docker ps -a -q)'\n\n# You can also remove all unused (unattached) volumes:\ndocker volume prune\n# WARNING: you might want to check what will be deleted with:\ndocker volume ls -f dangling=true\nAs above, please note that in our examples, we set the Docker project name to ixpm and so that prefix is used in some of the below. We also assume that only one IXP Manager Docker environments is running and so we complete Docker container names with _1.
For most routine development use, you only need two containers usually:
docker-compose -p ixpm up mysql www\nIf you are sending emails as part of your development process, include the mail catcher:
docker-compose -p ixpm up mysql www mailcatcher\nWhen the mysql container builds, it pre-populates the database with the contents of the SQL file found at tools/docker/containers/mysql/docker.sql. This is not present by default and is ignored by Git (to ensure you do not accidentally commit a production database!).
A default SQL database is bundled and should be placed in this location via:
cp tools/docker/containers/mysql/docker.sql.dist tools/docker/containers/mysql/docker.sql\nYou can put your own database here also. If you do, you will need to rebuilt the mysql contain:
docker-compose build mysql\nYou can access the MySQL database via:
docker exec -it ixpm_mysql_1 mysql -i ixpmanager\nAnd you can get shell access to the container with:
docker exec -it ixpm_mysql_1 bash\nYou can also connect to the MySQL server from your local machine using tools such as the standard MySQL client, TablePlus or Sequel Pro with the following settings:
mysql --protocol=TCP --port 33060 -u root\nNote that the www container mounts the IXP Manager development directory under /srv/ixpmanager. This means all local code changes are immediately reflected on the Docker web server.
The Dockerfile used to build the www container can be found at tools/docker/containers/www/Dockerfile.
You can access the container with:
docker exec -it ixpm_www_1 bash\nWe include a mailcatcher container which catches all emails IXP Manager sends and displays them on a web frontend. Ensure this container is started by either:
# start all containers:\ndocker-compose -p ixpm up\n# start mailcatcher with (at least) mysql and www:\ndocker-compose -p ixpm up mysql www mailcatcher\nThe .env.docker config contains the following SMTP / mail settings which ensure emails get send to the mailcatcher:
MAIL_HOST=172.30.201.11\nMAIL_PORT=1025\nYou can then view emails sent on: http://localhost:1080/
"},{"location":"dev/docker/#emulating-switches","title":"Emulating Switches","text":"ixpm_switch1_1 and ixpm_switch2_1 emulate switches by replaying SNMP dumps from real INEX switches (with some sanitisation). The OIDs for traffic have been replaced with a dynamic function to give varying values.
From the www container, you can interact with these via:
$ docker exec -it ixpm_www_1 bash\n# ping switch1\n...\n64 bytes from switch1 (172.30.201.60): icmp_seq=1 ttl=64 time=0.135 ms\n...\n# ping switch2\n...\n64 bytes from switch2 (172.30.201.61): icmp_seq=1 ttl=64 time=0.150 ms\n...\n\n\n# snmpwalk -On -v 2c -c switch1 switch1 .1.3.6.1.2.1.1.5.0\n.1.3.6.1.2.1.1.5.0 = STRING: \"switch1\"\n# snmpwalk -On -v 2c -c switch2 switch2 .1.3.6.1.2.1.1.5.0\n.1.3.6.1.2.1.1.5.0 = STRING: \"switch2\"\nYou'll note from the above that the hostnames switch1 and switch2 work from the www container. Note also that the SNMP community is the hostname (switch1 or switch2 as appropriate).
The packaged database only contains switch1. This allows you can add the second switch via http://localhost:8880/switch/add-by-snmp by setting the hostname and community to switch2.
If you want to add new customers for testing, add switch2 and then use interfaces Ethernet 2, 8, 13 and 6 and 7 as a lag as these have been preset to provide dynamic stats.
The containers include a working route server (ixpm_rs1_1) with 3 IPv4 clients (ixpm_cust-as112_1, ixpm_cust-as42_1, ixpm_cust-as1213_1) and and 2 IPv6 clients (ixpm_cust-as1213-v6_1, ixpm_cust-as25441-v6_1). IXP Manager also includes a working looking glass for this with Bird's Eye installed on the route server.
You can access the Bird BGP clients on the five sample customers using the following examples:
# access Bird command line interface:\ndocker exec -it ixpm_cust-as112_1 birdc\n\n# run a specific Bird command\ndocker exec -it ixpm_cust-as112_1 birdc show protocols\nThe route server runs an IPv4 and an IPv6 daemon. These can be accessed via the looking glass at http://127.0.0.1:8881/ or on the command line via:
# ipv4 daemon:\ndocker exec -it ixpm_rs1_1 birdc -s /var/run/bird/bird-rs1-ipv4.ctl\n\n# ipv6 daemon:\ndocker exec -it ixpm_rs1_1 birdc6 -s /var/run/bird/bird-rs1-ipv6.ctl\nIn this container, Bird's Eye can be found at /srv/birdseye with the web server config under /etc/lighttpd/lighttpd.conf.
We include the IXP Manager scripts for updating the route server configuration and reconfiguring Bird:
# get shell access to the container\ndocker exec -it ixpm_rs1_1 bash\n\n# all scripts under the following directory\ncd /usr/local/sbin/\n\n# reconfigure both daemons:\n./api-reconfigure-all-v4.sh\n\n# reconfigure a specific daemon with verbosity:\n./api-reconfigure-v4.sh -d -h rs1-ipv4\nFor developing / testing Grapher with Mrtg, we include a container that runs Mrtg via cron from a pre-configured mrtg.conf file.
NB: please ensure to update the GRAPHER_BACKENDS option in .env so it includes mrtg as follows:
GRAPHER_BACKENDS=\"mrtg|dummy\"\nThe configuration file matches the docker.sql configuration and can be seen in the IXP Manager source directory at tools/docker/mrtg/mrtg.cfg.
You can access the Mrtg container via:
docker exec -it ixpm_mrtg_1 sh\nWe also install a script in the root directory of the container that will pull a new configuration from IXP Manager. Run it via:
docker exec -it ixpm_mrtg_1 sh\ncd /\n./update-mrtg-conf.sh\n\n# or without entering the container:\ndocker exec -it ixpm_mrtg_1 /update-mrtg-conf.sh\nIt will replace /etc/mrtg.conf for the next cron run. It also sets the configuration not to run as a daemon as cron is more useful for development.
In this example, we look at the ixpmanager/www Docker image and update it from base php:7.0-apache to php:7.3-apache:
cd cd tools/docker/containers/www\n# replace:\n# FROM php:7.0-apache\n# with:\n# FROM php:7.3-apache\ndocker build .\n# or tag with: docker build -t ixpmanager/www:v5.0.0\ndocker push\n# if you're not logged in, use: docker login\nDo not forget to update your docker-compose.yml files to reference the new tag.
"},{"location":"dev/docker/#dev-tool-integrations","title":"Dev Tool Integrations","text":"NB: these tools and integrations are not IXP Manager specific but rather the typical Docker / PHP development tool chain. Please use support forums for the relevant sections / tools rather than contacting the IXP Manager developers directly.
"},{"location":"dev/docker/#php-storm-and-xdebug","title":"PHP Storm and Xdebug","text":"We are big fans of PhpStorm at IXP Manager DevHQ. One key feature is PhpStorm's integration with PHP Xdebug. We of course also need this to work with Docker.
Some background information on Xdebug is provided below but you are expected to be familiar with the Xdebug documentation on remote debugging.
The way interactive remote debugging works with Xdebug is as follows:
php.ini settings on the www container).To get this working with Docker, we need to work through each of these steps.
1. Enable Remote Debugging in the Docker Container
If you examine the www container Dockerfile in the IXP Manager source under tools/docker/containers/www/Dockerfile, you will see that we:
pecl install xdebug)./usr/local/etc/php/conf.d/local-ixpmanager-xdebug.ini as follows:[xdebug]\nzend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20151012/xdebug.so\nxdebug.remote_enable=1\nxdebug.remote_port=9001\nxdebug.remote_autostart=0\nxdebug.idekey=PHPSTORM\nxdebug.profiler_enable=0\nxdebug.profiler_enable_trigger=1\nxdebug.profiler_output_dir=/srv/ixpmanager/storage/tmp\nxdebug.auto_trace=0\nxdebug.trace_enable_trigger=1\nxdebug.trace_output_dir=/srv/ixpmanager/storage/tmp\nNote that the zend_extension may change as it is dynamically set by the build script. We also chose port 9001 rather than the default of 9000 due to local conflicts with common tool chains.
The one key element that is missing in the INI is the remote debugger IP address. This needs to be set to your development computer's LAN address (there are other options but this works best in practice). Once you know this address (say it's 192.0.2.23), set the following in the ${IXPROOT}/.env:
# For PHP xdebug, put in the IP address of your host\nDOCKER_XDEBUG_CONFIG_REMOTE_HOST=192.0.2.23\nWhen you start the Docker environment from $IXPROOT using docker-compose with something like:
cd $IXPROOT\ndocker-compose -p ixpm up mysql www\nthen docker-compose will use this setting from the .env file and it will be passed through the Xdebug.
2. Install a Xdebug Plugin on Your Browser
Some recommended plugins from the Xdebug documentation on remote debugging are these: Firefox, Chrome, Safari. It can also be enabled manually using a GET parameter - see the Xdebug documentation.
The only required parameter is the session key. For PhpStorm, the default is PHPSTORM unless you have configured it differently (see step 3 below).
The PHP Xdebug browser plugins allow you to enable debugging on a per request basis. See the Firefox link above to the plugin homepage for screenshots (as of 2018-01 at least).
3. Configure PhpStorm
PhpStorm have their own documentation for Xdebug. The short version to match the above two steps is:
You now need to create a Run/Debug Configuration. This is so you can map file paths on the remote system (www container) to your local development files:
For testing, set a break point in public/index.php and access your development IXP Manager using your new browser plugin. You should be able to step through each statement and - presuming your mappings are correctly set up - step into any file in the project.
Profiling and Function Traces
You may have noticed in the Xdebug configuration above, we have allowed for the triggering of function traces and profiling also. The browser plugins should support these - certainly the Firefox one does (leave the trigger key blank in both cases).
When you request an IXP Manager page via Firefox with profiling enabled, you will find the cachegrind file in $IXPROOT/storage/tmp on your own system You can then view this in PhpStorm via the menu Tools -> Analyze Xdebug Profiler Snapshot....
Function traces can be found in the same directory - these are just text files.
"},{"location":"dev/docs/","title":"Documentation","text":"From v4 onwards, we use GitHub Pages with MkDocs to build the documentation.
Both the site and the content are hosted on GitHub.
"},{"location":"dev/docs/#contributing-suggesting-errata","title":"Contributing / Suggesting Errata","text":"We welcome contributions or errata that improve the quality of our documentation. Please use one of the following two channels:
If you haven't already, install MkDocs. These instructions work on MacOS as of 2024:
# create a venv\npython3 -m venv venv\ncd venv\n\n# install mkdocs\n./bin/pip install mkdocs mike pymdown-extensions mkdocs-material mkdocs-git-revision-date-localized-plugin\nThe documentation can then be built locally as follows:
git clone https://github.com/inex/ixp-manager-docs-md.git\ncd ixp-manager-docs-md\n./venv/bin/mkdocs build\nYou can serve them locally with the following and then access them via http://127.0.0.1:8000 -
./venv/bin/mkdocs serve\nOr to see the full versioning site, use:
./venv/bin/mike serve\nSince September 2024, we now use documentation versioning and so you should only be pushing to the latest major.minor release of the dev major.minor version.
Never deploy to historical versions!
As an example, as the time of writing, 6.4.x is the latest release and 7.0 is in development. We did our final push to 6.4 via:
PATH=./venv/bin:$PATH ./venv/bin/mike deploy --push --update-aliases 6.4 latest\nAnd all new documentation will be pushed to dev via:
PATH=./venv/bin:$PATH ./venv/bin/mike deploy --push --update-aliases 7.0 dev\nOnce 7.0 is released, we will push a final update to 7.0 updating it to latest:
PATH=./venv/bin:$PATH ./venv/bin/mike deploy --push --update-aliases 7.0 latest\nAnd all new documentation will be pushed to dev via:
PATH=./venv/bin:$PATH ./venv/bin/mike deploy --push --update-aliases 7.1 dev\nNote that PATH=./venv/bin:$PATH is used as mike in turn calls mkdocs which is in this path.
You must be an authorised user for this but we welcome pull requests against the documentation repository!
Do not forget to push your changes to GutHub (if you have push permissions):
git add .\ngit commit -am \"your commit message\"\ngit push\nFoil is the view layer of IXP Manager.
"},{"location":"dev/foil/#undefined-variables","title":"Undefined Variables","text":"Foil is configured to throw an exception if a variable is undefined.
Methods to test a variable include:
<?= isset( $t->aaa ) ? 'b' : 'c' ?>\n// c\nMethods that do not work include:
<?= $t->aaa ?? 'c' ?>\nThis page collates various notes and bets practice for writing HTML forms with IXP Manager and Laravel.
IXP Manager uses the library Former to generate forms. Here are some examples of how to use Former.
"},{"location":"dev/forms/#html5-validation","title":"HTML5 Validation","text":"Former adds HTML5 validation tags when it created forms. If you wish to test the PHP code's validation rules, you will need to disable this is development by setting the following .env setting:
FORMER_LIVE_VALIDATION=false\nWe had some issues using Former's checkboxes correctly - this is why we are providing the correct way to use them.
"},{"location":"dev/forms/#configuration","title":"Configuration","text":"First make sure that the Former configuration file (config/former.php) is correctly configured:
// Whether checkboxes should always be present in the POST data,\n// no matter if you checked them or not\n'push_checkboxes' => true,\n\n// The value a checkbox will have in the POST array if unchecked\n'unchecked_value' => 0,\nThe following is the structure of a checkbox input:
Former::checkbox( 'checkbox-name' ) will be the HTML name=\"\" of the input in the DOM.->id( 'checkbox-id' ) will be the HTML `id=\"\"`` of the input in the DOM, it is not required and defaults to the name above.->label( 'my-label' ) will be the label of the input displayed on the left of the checkbox, it is not required. If you are just using a right hand side text label, setting this to ' ' can help improve layout.->label( 'my-text' ) will be the text of the input displayed on the right of the checkbox, it is not required.->value( 1 ) this is really important for the correct functioning of the checkboxes.->blockHelp( \"help text\u201d) will be the help text of the checkbox.Note: in this example the checkbox will be unchecked:
Former::checkbox( 'checkbox-name' )\n ->id( 'checkbox-id' )\n ->label( 'my-label' )\n ->text( 'my-text' )\n ->value( 1 )\n ->blockHelp( \"Help text\u201d );\nTo check a checkbox by default add the following function to the checkbox structure above:
->check()\nIf the checkbox has to be checked depending on a variable:
->check( $myVariableIsChecked ? 1 : 0 )\nNote: The above case should be an exception and not a common way to populate the checkboxes. To populate the checkboxes correctly you have to do it via the controller as explained below.
"},{"location":"dev/forms/#controller","title":"Controller","text":"You can populate a form via the controller with the function Former::populate() by the usual method of passing an array of values:
Former::populate([\n 'my-checkbox' => $object->isChecked() ? 1 : 0,\n]);\nIXP Manager uses the library Mardown to edit notes input field. Here are some examples of how to use Markdown.
"},{"location":"dev/forms/#view_1","title":"View","text":"You will have to use the following HTML structure to be able to add markdown to your textrea :
<div class=\"form-group\">\n <label for=\"notes\" class=\"control-label col-lg-2 col-sm-4\">Notes</label>\n <div class=\"col-sm-8\">\n <ul class=\"nav nav-tabs\">\n <li role=\"presentation\" class=\"active\">\n <a class=\"tab-link-body-note\" href=\"#body\">Body</a>\n </li>\n <li role=\"presentation\">\n <a class=\"tab-link-preview-note\" href=\"#preview\">Preview</a>\n </li>\n </ul>\n <br>\n <div class=\"tab-content\">\n <div role=\"tabpanel\" class=\"tab-pane active\" id=\"body\">\n <textarea class=\"form-control\" style=\"font-family:monospace;\" rows=\"20\" id=\"notes\" name=\"notes\"><?= $note_value ?></textarea>\n </div>\n <div role=\"tabpanel\" class=\"tab-pane\" id=\"preview\">\n <div class=\"well well-preview\" style=\"background: rgb(255,255,255);\">\n Loading...\n </div>\n </div>\n </div>\n <br><br>\n </div>\n</div>\nhref=\"#body\" from <a id=\"tab-link-body\" class=\"tab-link-body-note\" href=\"#body\">Body</a> have to match with the id=\"body\" from <div role=\"tabpanel\" class=\"tab-pane active\" id=\"body\">. The same for <a id=\"tab-link-preview\" class=\"tab-link-preview-note\" href=\"#preview\">Preview</a> and <div role=\"tabpanel\" class=\"tab-pane\" id=\"preview\">.
If you want to add more than one textarea with markdown to your page you will have to make sure that the HTML ID of the inputs are different like on the following example :
<div class=\"form-group\">\n <label for=\"notes\" class=\"control-label col-lg-2 col-sm-4\">Public Notes</label>\n <div class=\"col-sm-8\">\n\n <ul class=\"nav nav-tabs\">\n <li role=\"presentation\" class=\"active\">\n <a class=\"tab-link-body-note\" href=\"#body1\">Body</a>\n </li>\n <li role=\"presentation\">\n <a class=\"tab-link-preview-note\" href=\"#preview1\">Preview</a>\n </li>\n </ul>\n\n <br>\n\n <div class=\"tab-content\">\n <div role=\"tabpanel\" class=\"tab-pane active\" id=\"body1\">\n <textarea class=\"form-control\" style=\"font-family:monospace;\" rows=\"20\" id=\"notes\" name=\"notes\"><?= $t->notes ?></textarea>\n <p class=\"help-block\">These notes are visible (but not editable) to the member. You can use markdown here.</p>\n </div>\n <div role=\"tabpanel\" class=\"tab-pane\" id=\"preview1\">\n <div class=\"well well-preview\" style=\"background: rgb(255,255,255);\">\n Loading...\n </div>\n </div>\n </div>\n\n <br><br>\n </div>\n\n</div>\n\n\n<div class=\"form-group\">\n\n <label for=\"private_notes\" class=\"control-label col-lg-2 col-sm-4\">Private Notes</label>\n <div class=\"col-sm-8\">\n\n <ul class=\"nav nav-tabs\">\n <li role=\"presentation\" class=\"active\">\n <a class=\"tab-link-body-note\" href=\"#body2\">Body</a>\n </li>\n <li role=\"presentation\">\n <a class=\"tab-link-preview-note\" href=\"#preview2\">Preview</a> \n </li>\n </ul>\n\n <br>\n\n <div class=\"tab-content\">\n <div role=\"tabpanel\" class=\"tab-pane active\" id=\"body2\">\n <textarea class=\"form-control\" style=\"font-family:monospace;\" rows=\"20\" id=\"private_notes\" name=\"private_notes\"><?= $t->private_notes ?></textarea>\n <p class=\"help-block\">These notes are <b>NOT</b> visible to the member. You can use markdown here.</p>\n </div>\n <div role=\"tabpanel\" class=\"tab-pane\" id=\"preview2\">\n <div class=\"well well-preview\" style=\"background: rgb(255,255,255);\">\n Loading...\n </div>\n </div>\n </div>\n\n <br><br>\n </div>\n\n</div>\nNote: Please do not change the HTML class of the elements!
"},{"location":"dev/frontend-crud/","title":"Frontend CRUD","text":"IXP Manager, like many applications, has a lot of tables that need basic CRUD access: Ceate, Read, Update and Delete (plus list and view). In older versions of IXP Manager (and as yet unupdated code), we used this Zend Framework trait to allow us to repidly deploy CRUD interfaces.
For IXP Manager >= v4.7, we have duplicated (and improved) this to create a scaffolding framework in Laravel. This page documents that class.
"},{"location":"dev/frontend-crud/#configuration","title":"Configuration","text":"In any controller using extending the Doctrine2Frontend class, a _feInit() method is required which configures the controller and, for example, allows you to set what is displayed for different levels of user privileges.
The primary purpose of this function is to define the anonymous object _feParams (using an object ensures that the view gets a reference to the object and not a copy of a static array at a point in time):
<?php\nprotected function _feInit()\n{\n $this->view->feParams = $this->_feParams = (object)[\n\n // the ORM entity object that CRUD operations will affect:\n 'entity' => InfrastructureEntity::class,\n\n 'pagetitle' => 'Infrastructures',\n\n // default is false. If true, add / edit / delete will be disabled\n 'readonly' => false,\n\n 'titleSingular' => 'Infrastructure',\n 'nameSingular' => 'an infrastructure',\n\n 'viewFolderName' => 'infrastructure',\n\n 'readonly' => self::$read_only,\n\n 'listColumns' => [\n // what columns to display in the list view\n 'id' => [ 'title' => 'DB ID', 'display' => true ],\n 'name' => 'Name',\n 'shortname' => 'Shortname'\n ],\n\n 'listOrderBy' => 'name', // how to order columns\n 'listOrderByDir' => 'ASC', // direction of order columns\n ];\n\n // you can then override some of the above for different user privileges (for example)\n switch( Auth::user() ? Auth::user()->getPrivs() : UserEntity::AUTH_PUBLIC ) {\n\n case UserEntity::AUTH_SUPERUSER:\n $this->_feParams->pagetitle = 'Infrastructures (Superuser View)';\n\n $this->_feParams->listColumns = array_merge(\n $this->_feParams->listColumns, [\n // ...\n ];\n );\n break;\n\n default:\n if( php_sapi_name() !== \"cli\" ) {\n abort( 'error/insufficient-permissions' );\n }\n }\n\n // display the same information in the single object view as the list of objects\n $this->_feParams->viewColumns = $this->_feParams->listColumns;\n}\nBy default, all Doctrine2Frontend controllers can only be accessed by an authenticated super user (Entities\\User::AUTH_SUPERUSER). You can change this by setting the following property on your implementation:
<?php\n/**\n * The minimum privileges required to access this controller.\n *\n * If you set this to less than the superuser, you need to manage privileges and access\n * within your own implementation yourself.\n *\n * @var int\n */\npublic static $minimum_privilege = UserEntity::AUTH_SUPERUSER;\nIf you set this to less than the superuser, you need to manage privileges and access within your own implementation yourself.
This is normally handled in a number of ways:
Request object utilising the authorize() method;feInit()The feInit() method would normally look something like the following:
<?php\n// phpunit / artisan trips up here without the cli test:\nif( php_sapi_name() !== 'cli' ) {\n\n // custom access controls:\n switch( Auth::check() ? Auth::user()->getPrivs() : UserEntity::AUTH_PUBLIC ) {\n case UserEntity::AUTH_SUPERUSER:\n break;\n\n case UserEntity::AUTH_CUSTUSER:\n switch( Route::current()->getName() ) {\n case 'Layer2AddressController@forVlanInterface':\n break;\n\n default:\n $this->unauthorized();\n }\n break;\n\n default:\n $this->unauthorized();\n }\n}\nThe $this->unauthorized( $url = '', $code = 302 ) calls abort() with the given redirect code and URL. The default parameters will do the right thing.
Routes are explicitly defined in Laravel. The Doctrine2Frontend class sets up the standard routes automatically once you add the following to your routes/web.php (or as appropriate) file on a per implementation basis. E.g. for the Infrastructure implementation, we add to routes/web-doctrine2frontend.php:
<?php\nIXP\\Http\\Controllers\\InfrastructureController::routes();\nNote that by placing the above in routes/web-doctrine2frontend.php, you ensure the appropriate middleware is attached.
This routes() function determines the route prefix using kebab case of the controller name. That is to say: if the controller is CustKitController, the determined prefix is cust-kit. You can override this by setting a $route_prefix class constant in your implementation.
The standard routes added (using infrastructure as an example) are:
infrastructure/addinfrastructure/edit/{id}infrastructure/listinfrastructure/view/{id}infrastructure/delete/{id}infrastructure/storeIf you want to create your own additional routes, create a function as follows in your implementation:
<?php\npublic static function additionalRoutes( $route_prefix ) {}\nAnd add routes (using the normal Route::get() / ::post() / etc Laravel methods).
If you want to completely change the routes, just override the public static function routes() {} function.
All the common view templates for thss functionality can be found in resources/views/frontend directory. You can override any of these with your own by creating a template of the same name and placing it under resources/views/xxx (or resources/skins/skinname/xxx) where xxx is the feParams['viewFolderName'].
If your controller should be read only (list and view actions, no add, edit or delete) then set the following static member:
<?php\n/**\n * Is this a read only controller?\n *\n * @var boolean\n */\npublic static $read_only = true;\nEach of the typical CRUD actions will be described here.
NB: the best documentation is sometimes the code. Check out the above routes file (routes/web-doctrine2frontend.php) and examine some of the implemented controllers directly.
The list action is for listing the contents of a database table in a HTML / DataTables view.
The only requirement of the list action is that the following abstract function is implemented:
<?php\n/**\n * Provide array of table rows for the list action (and view action)\n *\n * @param int $id The `id` of the row to load for `view` action. `null` if `list` action.\n * @return array\n */\nabstract protected function listGetData( $id = null );\nA sample implementation for the infrastructure controller just calls a Doctrine2 repository function:
<?php\nprotected function listGetData( $id = null ) {\n return D2EM::getRepository( InfrastructureEntity::class )->getAllForFeList( $this->feParams, $id );\n}\nThe table rows returned in the above array must be associatative arrays with keys matching the feParams['listColumns'] definition.
The list view template optionally includes other templates you can define (where xxx below is the feParams['viewFolderName']):
resources/views/frontend/js/list which activates the DataTables, sets up sorting, etc. You can override this (and include the original if appropriate) if you want to add additional JS functionality.resources/views/xxx/list-preamble template exists, it is included just before the table.resources/views/xxx/list-postamble template exists, it is included just after the table.resources/views/xxx/list-head-override template exists, it will replace the <thead> element of the list table (example).resources/views/xxx/list-head-override template exists, it will replace the <tr> elements of the list table (example).resources/views/xxx/list-empty-message template exists, it will replace the the standard information box when a table is empty (example).The following hooks are available:
protected function preList():void {} - called before the list is displayed allowing you to add elements to the template, etc.The view action is for showing a single database row identified by the id passed in the URL.
The only requirement of the view action is that the abstract function listGetData( $id = null ) as used by the list action has been correctly implemented to take an optional ID and return an array with a single element matching that ID.
The table rows returned in the above array must be associatative arrays with keys matching the feParams['viewColumns'] definition.
The list view template optionally includes other templates you can define (where xxx below is the feParams['viewFolderName']):
resources/views/frontend/js/view.resources/views/xxx/view-preamble template exists, it is included just before the view panel.resources/views/xxx/view-postamble template exists, it is included just after the view panel.resources/views/xxx/view-row-override template exists, it will replace the <tr> element of the view (example).The presentation of the create / update (also known as add / edit) page is discussed here. Form processing and storage will be dealt with in the next section.
The first required element of this functionality is the implementation of the following abstract function:
<?php\nabstract protected function addEditPrepareForm( $id = null ): array;\nThe use of this function is best explained with reference to an implementation from the infrastructure controller:
<?php\n/**\n * Display the form to add/edit an object\n * @param int $id ID of the row to edit\n * @return array\n */\nprotected function addEditPrepareForm( $id = null ): array {\n if( $id !== null ) {\n\n if( !( $this->object = D2EM::getRepository( InfrastructureEntity::class )->find( $id) ) ) {\n abort(404);\n }\n\n $old = request()->old();\n\n // we use array_key_exists() here as the array can contain the\n // key with a null value.\n\n Former::populate([\n 'name' => array_key_exists( 'name', $old ) ? $old['name'] : $this->object->getName(),\n 'shortname' => array_key_exists( 'shortname', $old ) ? $old['shortname'] : $this->object->getShortname(),\n 'isPrimary' => array_key_exists( 'isPrimary', $old ) ? $old['isPrimary'] : ( $this->object->getIsPrimary() ?? false ),\n ]);\n }\n\n return [\n 'object' => $this->object,\n ];\n}\nNote from the above:
$t->params in the template. Note that $t->params['data'] is added later and contains the feParams object.The next required element is building the actual Former object for display. For this, you must create a custom resources/views/xxx/edit-form template. See, as an example, the infrastructure one under resources/views/infrastructure/edit-form.js.
The add/edit view template optionally includes other templates you can define (where xxx below is the feParams['viewFolderName']):
resources/views/xxx/js/edit.resources/views/xxx/edit-preamble template exists, it is included just before the view panel.resources/views/xxx/edit-postamble template exists, it is included just after the view panel.You can query the boolean $t->params['isAdd'] in your templates to distinguish between add and edit operations.
Storing the edited / new object requires implementing a single abstract method which manages validation and storage. This is best explained with a practical implementation:
<?php\n/**\n * Function to do the actual validation and storing of the submitted object.\n * @param Request $request\n * @return bool|RedirectResponse\n */\npublic function doStore( Request $request )\n{\n $validator = Validator::make( $request->all(), [\n 'name' => 'required|string|max:255',\n 'shortname' => 'required|string|max:255',\n ]);\n\n if( $validator->fails() ) {\n return Redirect::back()->withErrors($validator)->withInput();\n }\n\n if( $request->input( 'id', false ) ) {\n if( !( $this->object = D2EM::getRepository( InfrastructureEntity::class )->find( $request->input( 'id' ) ) ) ) {\n abort(404);\n }\n } else {\n $this->object = new InfrastructureEntity;\n D2EM::persist( $this->object );\n }\n\n $this->object->setName( $request->input( 'name' ) );\n $this->object->setShortname( $request->input( 'shortname' ) );\n $this->object->setIxfIxId( $request->input( 'ixf_ix_id' ) ? $request->input( 'ixf_ix_id' ) : null );\n $this->object->setPeeringdbIxId( $request->input( 'pdb_ixp' ) ? $request->input( 'pdb_ixp' ) : null );\n $this->object->setIsPrimary( $request->input( 'primary' ) ?? false );\n $this->object->setIXP( D2EM::getRepository( IXPEntity::class )->getDefault() );\n\n D2EM::flush($this->object);\n\n if( $this->object->getIsPrimary() ) {\n // reset the rest:\n /** @var InfrastructureEntity $i */\n foreach( D2EM::getRepository( InfrastructureEntity::class )->findAll() as $i ) {\n if( $i->getId() == $this->object->getId() || !$i->getIsPrimary() ) {\n continue;\n }\n $i->setIsPrimary( false );\n }\n D2EM::flush();\n }\n\n return true;\n}\nNote from this:
$this->object = $inf; as it is used to create log messages, etc.The following hooks are available:
protected function postStoreRedirect() {} - the Doctrine2Frontend class returns null. Override it to return a valid route name to have the post store redirect go somewhere besides /list.$this->store_alert_success_message (string) in doStore().Deletes are handled via posts and so have Laravel's built in CSRF protection. The logic is quiet simple:
<?php\npublic function delete( Request $request ) {\n\n if( !( $this->object = D2EM::getRepository( $this->feParams->entity )->find( $request->input( 'id' ) ) ) ) {\n return abort( '404' );\n }\n\n if( $this->preDelete() ) {\n D2EM::remove( $this->object );\n D2EM::flush();\n $this->postFlush( 'delete' );\n AlertContainer::push( $this->feParams->titleSingular . \" deleted.\", Alert::SUCCESS );\n }\n\n return redirect()->action( $this->feParams->defaultController.'@'.$this->feParams->defaultAction );\n}\nAs you can see, it calls a protected function preDelete(): bool {} hook which, if it returns false, the delete operation is abandoned.
The following hooks are available:
* `protected function postDeleteRedirect() {}` - the *Doctrine2Frontend* class returns null. Override it to return\n a valid route name to have the post store redirect go somewhere besides `/list`.\nThere is a postFlush() hook:
<?php\n/**\n * Optional method to be overridden if a D2F controllers needs to perform post-database flush actions\n *\n * @param string $action Either 'add', 'edit', 'delete'\n * @return bool\n */\nprotected function postFlush( string $action ): bool\n{\n return true;\n}\nwhich is called during some actions with the action name as a parameter: add, edit, delete. This function is called just after the database flush operation.
This is a quick write up as I commit a new graph type. To be fleshed out.
Our new graphing backend, Grapher, supports different graph types from different backends. To add a new graph type - let's call it Example - you need to do the following:
app/Services/Grapher/Graph/Example.php. This must extend the abstract class app/Services/Grapher/Graph.php.example() function to app/Services/Grapher.php which instantiates the above graph object.app/Services/Grapher/Backend/xxx) to handle this new graph file. I.e. create the actual implementation for getting the data to process this graph.supports() function in the appropriate backends (and the app/Services/Grapher/Backend/Dummy backend).To serve this graph over HTTP:
Create a GET route in app/Providers/GrapherServiceProvider.php
app/Http/Controllers/Services/Grapher.phpapp/Http/Middleware/Services/Grapher.phpHere's a great example from a Github commit.
"},{"location":"dev/grapher/#adding-a-new-mrtg-graph","title":"Adding a New MRTG Graph","text":"Here is an example of adding broadcast graphs to MRTG.
"},{"location":"dev/helpders/","title":"Helpers","text":"Various helpers we use within IXP Manager.
"},{"location":"dev/helpders/#alerts","title":"Alerts","text":"To show Bootstrap-styled alerts on view (Foil) templates, add them in your controllers as follows:
<?php\n use IXP\\Utils\\View\\Alert\\Container as AlertContainer;\n use IXP\\Utils\\View\\Alert\\Alert;\n\n ...\n\n AlertContainer::push( '<b>Example:</b> This is a success alert!, Alert::SUCCESS );\nwhere the types available are: SUCCESS, INFO (default), DANGER, WARNING.
To then display (all) the alerts, in your foil template add:
<?= $t->alerts() ?>\nThese alerts are HTML-safe as they display the message using HTML Purifier's ''clean()''.
"},{"location":"dev/introduction/","title":"Development Introduction","text":"We welcome contributions to IXP Manager from the community. The main requirement is that you sign the contributor's license agreement.
"},{"location":"dev/introduction/#core-vs-packages","title":"Core vs Packages","text":"If you plan to add a significant / large piece of functionality, then please come and talk to us first via the mailing lists. There are two ways to get such contributions into IXP Manager:
The following is a reply to someone looking to contribute something that didn't fit with what IXP Manager's mission was which may also help anyone considering contributing.
We have learned the very (very) hard way to avoid adding non-core functionality into the core of IXP Manager. At INEX, we won't be using XXX in the short to medium term and nor are we aware of IX's that use it.
This means that XXX code will be non-core and not used or tested (or testable easily) by the core IXP Manager developers. This creates a bunch of issues including:
a) becomes a new consideration for IXP Manager updates and schema changes;
b) the IXP Manager issue tracker and mailing list will be the goto place for people seeking help with this functionality and we will not be able to provide that;
c) would require assurances of maintainers and support for XXX to the project - I'm not sure that can be given at this stage;
d) large features require documentation: https://docs.ixpmanager.org/
e) past experience has shown us that we often end up having to remove chunks of non-core functionality due to (a), (b) and (c) above and this is also costly on time.
Now, we really do not want to discourage adding XXX support to IXP Manager - I like the project and you have shown it can work at an IX. It'd be great to have it as part of the IXP Manager tool chain.
One of the advantages of switching from Zend Framework to Laravel has been the ability to have add on functionality by way of packages:
https://laravel.com/docs/5.6/packages
I think this is a perfect way to add XXX support and we can help ensuring UI hooks by detecting the packet and adding menu options.
This also solves all the issues above:
a) is not an impediment to upgrades: if the XXX package falls behind the pace of IXP Manager development and someone wants XXX support, they just install a version of IXP Manager that is aligned with the XXX package.
b) issue and support wise, having XXX as a package creates a clean line of delineation between IXP Manager and XXX code bases so people can raise issues and questions with the correct project.
c) is mostly answered by (a).
d) documentation becomes the purview of the XXX team and we can provide the appropriate links from ours.
"},{"location":"dev/introduction/#database-orms","title":"Database / ORMs","text":"As of v6.0.0, IXP Manager uses the Laravel Eloquent ORM, replacing the Doctrine ORM used in previous versions.
a) do not change the schema of any existing table. This would need to be done in IXP Manager core via Eloquent as part of a new release and should be discussed with the core developers.
b) ideally schema changes would be limited to namespaced (xxx_*) tables (where xxx represents your package / feature.)
IXP Manager has looking glass support allowing IXPs to expose details on route server / collector / AS112 BGP sessions to their members.
As it stands, we have only implemented one looking glass backend - Bird's Eye; a simple secure micro service for querying Bird (JSON API) (and also written by us, INEX).
We have implemented this in IXP Manager as a service so that other backends can be added easily.
Disclaimer: the links and line numbers here are against IXP Manager v4.5.0 and they may have changed since.
"},{"location":"dev/looking-glass/#adding-support-for-additional-lgs","title":"Adding Support for Additional LGs","text":"An additional API backend needs to be given a constant in Entities\\Router named API_TYPE_XXX where XXX is an appropriate name.
It then needs to have a case: check in app/Services/LookingGlass.php. This needs to instantiate your service provider.
Your service provider must implement the App\\Contracts\\LookingGlass interface.
For a concrete example, see the Bird's Eye implementation.
"},{"location":"dev/release-procedure/","title":"Release Procedure","text":"DRAFT: in advance of the v4.8.0 release, I am gathering some notes here towards writing for formal release procedure for new minor versions of IXP Manager.
release-v5..env.example has been updated with new options and comments.Laravel Telescope is an elegant debug assistant for the Laravel framework. Telescope provides insight into the requests coming into your application, exceptions, log entries, database queries, queued jobs, mail, notifications, cache operations, scheduled tasks, variable dumps and more. Telescope makes a wonderful companion to your local Laravel development environment.
"},{"location":"dev/users/","title":"Development Notes for User Management","text":"The project management of this m:n (customer:user) enhancement is an internal Island Bridge Networks issue and this page serves to expose that and more information publicly.
Read the official user documentation first as that will answer questions around how it is meant to work.
Here is the schema for customers / users around the time of the v5 release:
One for the goals of this enhancement was to try to not break as much existing functionality as possible. As an example, we would typically get the user's customer relation using $user->getCustomer() and this was linked via the user.custid column.
In developing this enhancement, we needed to track two things:
By using the user.custid for this purpose, we retained the ability to call $user->getCustomer() which meant the vast majority of existing code continued to work as expected.
So, the mechanism for switching a user from one customer to another is:
user.custid to the target customer ID;When logging in, the system will:
For development purposes, we have Vagrant build files.
The Vagrant file was updated for IXP Manager v7.
The entire system is built from a fresh Ubuntu 24.04 installation via the tools/vagrant/bootstrap.sh script. This also installs a systemd service to run tools/vagrant/startup.sh on a reboot to restart the various services.
Note the developers use Parallels (see below) and have not tested on VirtualBox for sometime.
If you want to get IXP Manager with Vagrant and VirtualBox up and running quickly, follow these steps:
Clone IXP Manager to a directory:
git clone https://github.com/inex/IXP-Manager.git ixpmanager\ncd ixpmanager\nEdit the Vagrantfile in the root of IXP Manager and delete the config.vm.provider \"parallels\" do |prl| block and uncomment the config.vm.provider \"virtualbox\" do |vb|.
Spin up a Vagrant virtual machine:
vagrant up\nbrew tap hashicorp/tap\nbrew install hashicorp/tap/hashicorp-vagrant\nvagrant plugin install vagrant-parallels\ngit clone https://github.com/inex/IXP-Manager.git ixpmanager\ncd ixpmanager\nvagrant up\nAccess IXP Manager on: http://localhost:8088/
Log in with one of the following username / passwords:
Admin user: vagrant / Vagrant1 (api key: r8sFfkGamCjrbbLC12yIoCJooIRXzY9CYPaLVz92GFQyGqLq)
as112 / AS112as112as112user / AS112as112Please see Vagrant's own documentation for a full description of how to use it fully.
To access the virtual machine that the above has spun up, just run the following from the ixpmanager directory:
vagrant ssh\nOnce logged into the Linux machine, you'll find the ixpmanager directory mounted under /vagrant.
sudo su - root/password via:mysql -u root -ppassword ixpmysql -u root -ppassword -h 127.0.0.1 -P 33061/vagrant in the Vagrant virtual machine. This is mounted as the vagrant user. Any changes made on your own machine are immediately reflected on the virtual machine and vice-versa.vagrant to avoid all file system permission issues.Spinning up Vagrant in the above manner loads a sample database from tools/vagrant/vagrant-base.sql. If you have a preferred development database, place a bzip'd copy of it in the ixpmanager directory called ixpmanager-preferred.sql.bz2 before step 5 above.
The Vagrant bootstrapping includes installing snmpsim making three \"switches\" matching those in the supplied database available for polling. The source snmpwalks for these are copied from tools/vagrant/snmpwalks to /srv/snmpclients and values can be freely edited there.
Example of polling when ssh'd into vagrant:
snmpwalk -c swi1-fac1-1 -v 2c swi1-fac1-1\nsnmpwalk -c swi1-fac2-1 -v 2c swi1-fac1-1\nsnmpwalk -c swi2-fac1-1 -v 2c swi2-fac1-1\nAs you can see, the community selects the source file - i.e., -c swi1-fac1-1 for /srv/snmpclients/swi1-fac1-1.snmprec. The Vagrant bootstrap file adds these switch names to /etc/hosts also.
The bootstrapping also configures mrtg to run and includes this in the crontab rather than using dummy graphs. The snmp simulator has some randomised elements for some of the interface counters.
"},{"location":"dev/vagrant/#route-server-collector-as112-testbed-and-looking-glass","title":"Route Server / Collector / AS112 Testbed and Looking Glass","text":"When running vagrant up for the first time, it will create a full route server / collector /as112 testbed complete with clients:
All Bird instance sockets are located in /var/run/bird/ allowing you to connect to them using birdc -s /var/run/bird/xxx.ctl.
In additional to this, a second Apache virtual host is set up listening on port 81 locally providing access to Birdseye installed in /srv/birdseye. The bundled Vagrant database is already configured for this and should work out of the box. All of Birdseye's env files are generated via:
php /vagrant/artisan vagrant:generate-birdseye-configurations\nVarious additional scripts support all of this:
tools/vagrant/bootstrap.sh file which sets everything up.tools/vagrant/scripts/refresh-router-testbed.sh will reconfigure all routers.tools/vagrant/scripts/as112-reconfigure-bird2.sh will (re)configure and start, if necessary, the AS112 Bird instances.tools/vagrant/scripts/rs-api-reconfigure-all.sh will (re)configure and start, if necessary, the route server Bird instances.tools/vagrant/scripts/rc-reconfigure.sh will (re)configure and start, if necessary, the route collector Bird instances.For the clients, we run the following:
mkdir -p /srv/clients\nchown -R vagrant: /srv/clients\nphp /vagrant/artisan vagrant:generate-client-router-configurations\nchmod a+x /srv/clients/start-reload-clients.sh\n/srv/clients/start-reload-clients.sh\nAll router IPs are added to the loopback interface as part of the tools/vagrant/bootstrap.sh (or the startup.sh script on a reboot). There are also necessary entries in /etc/hosts to map router handles to IP addresses. There are two critical Bird BGP configuration options to allow multiple instances to run on the same server and speak with each other:
strict bind yes;\nmultihop;\nIXP Manager has a number of API endpoints which are documented in the appropriate places throughout the documentation.
Please find details below about authenticating for API access to secured functions.
"},{"location":"features/api/#creating-an-api-key","title":"Creating an API Key","text":"When logged into IXP Manager, create an API as follows:
Treat your API key as a password and do not copy the below URLs into public websites and other public forums.
"},{"location":"features/api/#api-authentication","title":"API Authentication","text":"There are two ways to use your API key to authenticate to IXP Manager.
You can test these using the API test endpoint at api/v4/test. For example:
https://ixp.example.com/api/v4/test\nThe plaintext response will also indicate if you are authenticated or not (which can be via existing session or API key).
"},{"location":"features/api/#1-http-header-parameter","title":"1. HTTP Header Parameter","text":"You can pass your API key in the HTTP request as a request header parameter called X-IXP-Manager-API-Key. For example:
curl -X GET -H \"X-IXP-Manager-API-Key: my-api-key\" https://ixp.example.com/api/v4/test\nThis is a legacy method that is still supported. You can tack your key on as follows:
https://ixp.example.com/api/v4/test?apikey=my-api-key\nIn IXP Manager v5.1 we introduced some new API Key management features:
API keys are not shown by default but require a password to be entered to show them. If you wish to show the keys (inadvisable), you can set IXP_FE_API_KEYS_SHOW=true in .env. This is only available to mimic historic functionality and will be removed in the future.
By default, a user can create no more than 10 keys. If you wish to change this, set IXP_FE_API_KEYS_MAX=n in .env where n is an integer value > 0.
Prerequisite Reading: Ensure you first familiarize yourself with the generic documentation on managing and generating router configurations here.
AS112 is a service which provides anycast reverse DNS lookup for several prefixes, namely:
Because these IP addresses are widely used for private networking, many end-user systems are configured to perform reverse DNS lookups for these address ranges. DNS lookups for these ranges should always be null-answered quickly, in order to make sure that DNS retransmits don\u2019t occur (thereby overloading local DNS resolvers), and to prevent end-user systems from hanging due to DNS lookups.
AS112 services are provided around the world by a group of volunteers and, very often, by IXP operators for the benefit of their members.
INEX has always provided an AS112 service to our members on all peering LANs and so it is an integral part of IXP Manager. You can read all about INEX's implementation at https://www.inex.ie/technical/as112-service/ including graphs for the service. Feel free to use our test and examples from that page for your own IXP.
"},{"location":"features/as112/#building-an-as112-service","title":"Building an AS112 Service","text":"You can find instructions for building an AS112 service in rfc7534. You should also add AS112 redirection using DNAME functionality as per rfc7535.
You will also find a lot more information and how-tos on the official website at: https://www.as112.net/.
Follow these instructions in every way to build the AS112 service on a (virtual) machine with an appropriate DNS server - except skip the installation and configuration of the BGP daemon. When using IXP Manager, you will need to use Bird for this and IXP Manager will create the configuration.
"},{"location":"features/as112/#managing-your-as112-service-from-ixp-manager","title":"Managing Your AS112 Service from IXP Manager","text":"AS112 is disabled by default in IXP Manager. This really just means UI elements are hidden. To enable these, set the following in your .env file:
IXP_AS112_UI_ACTIVE=true\nThis will add UI elements including:
Enabling the AS112 service simply indicates if a BGP peering session should be created in the AS112 BGP configuration when downloading the AS112 router's BGP configuration from IXP Manager.
"},{"location":"features/as112/#creating-the-pro-bono-as112-customer","title":"Creating the Pro-Bono AS112 Customer","text":"You need to add the AS112 service as a pro-bono member of your IXP in IXP Manager. Here's INEX's example:
You then need to create an interface for the AS112 service on each peering LAN where the service will be offered. Here again is INEX's example from our peering LAN1 in Dublin:
Note that historically INEX has not used MD5 on our AS112 service. This is because the service dates from over 20 years ago at INEX when MD5 support was not available. There is no reason not to use MD5 on the service if you wish.
"},{"location":"features/as112/#generating-the-bird-configuration","title":"Generating the Bird Configuration","text":"Please see the router configuration generation for this.
For your AS112 server, we have a sample script(s) for pulling and updating the configuration from IXP Manager. We typically put this in an hourly cron.
"},{"location":"features/as112/#other-notes","title":"Other Notes","text":"At INEX, we typically have our AS112 service peer with our route servers.
This will happen automatically if you check the Route Server Client on the AS112 VLAN interface configuration (see above screen shot) and also check the AS112 Client checkbox on the VLAN interfaces of your route servers in IXP Manager. Note that in the same way as you create an AS112 pro-bono customer, you should also have a dedicated route server internal customer.
"},{"location":"features/console-servers/","title":"Console Servers","text":"An IXP would typically have out of band access (for emergencies, firmware upgrades, etc) to critical infrastructure devices by means of a console server.
IXP Manager has Console Servers and Console Server Connections menu options to allow IXP administrators add / edit / delete / list console server devices and, for any such device, record what console server port is connected to what device (as well as connection characteristics such as baud rate).
From IXP Manager v4.8.0 onwards, each of these pages has a notes field which supports markdown to allow you to include sample connection sessions to devices. This is especially useful for rarely used console connections to awkward devices.
"},{"location":"features/console-servers/#improvements-from-v480","title":"Improvements from v4.8.0","text":"One of the new features of v4.8.0 is fixing the switch database table which until now could hold switches and console servers. This was awkward in practice and we have split these into distinct database tables and menu options.
"},{"location":"features/core-bundles/","title":"Core Bundles","text":"A core bundle is a link between the IXP's own switches. These are often referred to as trunks, interswitch links (ISLs), core links, etc. IXP Manager has a number of features to support these since v6 was released.
Before continuing with this document, it is critical you have read and understand how IXP Manager represents normal member connections - please read the Customer Connections page before proceeding as the rest of this document assumes that foundational knowledge.
Within IXP Manager, a core bundle represents a link(s) between two switches. This bundle may have one or more links and it may be one of three types:
A layer 2 LACP link (L2-LAG). Where your exchange has more than two switches, a protocol such as spanning tree would operate across these links to prevent loops.
If you are running just two switches with a single link between them, this is also the option you would choose. We'd typically recommend a protocol such as LACP or UDLD runs across even single links to detect unidirectional link errors.
A layer 3 LAG (L3-LAG) is for one or more aggregated links between a switch when using a routed underlay such as MPLS / VPLS / VXLAN. Each end of the link would have an IP address and participate in a routed core network.
ECMP is similar to L3-LAG above, each individual link in the core bundle has its own IP addressing and traffic distribution across the links is handled via equal-cost multi-path (ECMP) routing.
Some of the features that core bundles provide and enable include:
To fully understand IXP Manager's implementation of core bundles, it is important to have an awareness of the database representation of them. This is why reading the customer connections page is important - core bundles have been designed to fit into the existing database representation:
As you'll note, we still have a virtual interface (VI) as the syntactic sugar to represent a link where:
What's new is we've added a new element of syntactic sugar - the core bundle (CB) - and this is used to group the two ends of the link(s) between switches together.
The above may seem quite complex but it works well in practice. Most importantly, IXP Manager guides you through most of the complexity when setting up and managing core bundles. However, it's still important to have a grasp of the above as the user interface does reflect the underlying database schema.
"},{"location":"features/core-bundles/#creating-a-core-bundle","title":"Creating a Core Bundle","text":"Core bundles can be added like any another object in IXP Manager: find Core Bundles under IXP Admin Actions on the left hand side menu and then, when you are on the core bundles page, select the [+] add button on the top right of the page.
Adding a core bundle is presented with wizard-type functionality. As with most IXP Manager pages, there is extensive context-based help available by clicking the help button at the end of the form.
There's a number of elements to adding a core bundle and we'll take them individually here using an ECMP bundle as an example.
"},{"location":"features/core-bundles/#general-settings","title":"General Settings","text":"The context help shown in the image explains each element's requirements quite well.
You will notice that we often say informational unless you are provisioning your switches from IXP Manager. This is because many of these settings have no impact with IXP Manager or associated functions such as graphing. The value of entering this information won't be appreciated unless you are provisioning switches via IXP Manager using something such as Napalm.
Manually provisioning a core bundle with 8 x 10Gb ECMP links for a VXLAN underlay requires 16 interface configurations with consistent and correct IP addressing, MTU, BFD, etc. Add to that the 16 BGP neighbor configurations required. This does not scale beyond a handful of switches. We'd argue it barely scales to two switches. Especially when you then need to change the cost / preference settings.
Using IXP Manager, INEX can edit the cost of a core bundle and push it out through our SaltStack + Napalm configuration in a quick and error free manner.
It should also be recognised that the specific meaning of cost, preference, STP, etc. do not need to be taken literally - use them as appropriate for your network design and technology. For example, INEX uses cost for BGP metrics.
Lastly, some elements appear in general settings as they need to be consistent across all links in a core bundle - for example the MTU.
"},{"location":"features/core-bundles/#common-link-settings","title":"Common Link Settings","text":"Again, the context help shown in the image explains each element's requirements quite well. In addition to those, please note:
The final section requires you add one or more core links and select the 'a side' and 'b side' ports for each link added.
Note that some elements are core bundle type specific - e.g. as this is an ECMP core bundle, the subnet and BFD can be configured on a per link basis. For a L3-LAG, these are configured as part of the general settings.
There are a number of features to assist with adding large bundles (e.g. when we developed this using INEX as a test case, and before the widespread deployment of 100Gb WDM kit, 8 x 10Gb bundles were not uncommon). When you click Add another core link to the bundle...:
The next subnet will be calculated and populated. E.g. if you chose 10.10.20.0/30 for link 1, then 10.10.20.4/30 will be populated for link 2, and so on.
We have discussed this with some IXPs who use an addressing scheme where they try and embed information in the IP address such as facility or switch. We always advise that you treat an IP address as a 32-bit unique identifier and nothing else. If you choose a more complex addressing scheme, you can of course override IXP Manager's assistance here.
Your provisioning system will be responsible for picking the IP address for each side from 10.10.20.4/30. We recommend (and implement) a system such that the lowest usable address is assigned to the 'a side' and the next usable address is assigned to the 'b side'. For illustration:
10.10.20.0/31 10.10.20.0 10.10.20.1 10.10.20.0/30 10.10.20.1 10.10.20.2 10.10.20.0/24 10.10.20.1 10.10.20.2 Core bundles make graphing inter-switch links really easy - in fact, so long as you already have MRTG graphing configured, you just need to add the bundle, allow MRTG configuration to update and the graphs will appear in the statistics menu.
In fact, you can see a live example from INEX here. If this link yields a 404, it will mean we've since mothballed that specific link. Just browse to the Statistics menu and select Inter-Switch / PoP Graphs for another.
You'll note:
There is an API endpoint for superadmins to get the status of core bundles:
/api/v4/switch/{switchid}/core-bundles-status\nwhere {switchid} is the database ID of the switch.
A sample of the JSON output is:
{\n \"status\": true,\n \"switchname\": \"swi1-cwt1-4\",\n \"msgs\": [\n \"swi1-cwt1-4 - swi1-cwt1-1 OK - 1\\/1 links up\",\n \"swi1-cwt1-4 - swi1-cwt1-2 OK - 1\\/1 links up\",\n \"swi1-cwt1-4 - swi1-cwt2-1 OK - 1\\/1 links up\",\n \"swi1-cwt1-3 - swi1-cwt1-4 OK - 3\\/3 links up\",\n \"swi1-cwt1-4 - swi1-cwt2-3 OK - 4\\/4 links up\"\n ]\n}\nIf any individual link has failed, status will return false and an appropriate message will be provided for the relevant link(s):
\"ISSUE: swi1-cwt1-4 - swi1-cwt1-1 has 0\\/1 links up\"\nIndividually disabled core links (via the core bundle UI) will not trigger an alert. If an entire core bundle is disabled in the UI it will be listed as follows:
\"Ignoring swi1-cwt1-4 - swi1-cwt1-1 as core bundle disabled\"\nAs you can see, it returns a msgs[] element for each core bundle indicating the number of core links up.
The Nagios script we use at INEX to check the core bundles on a switch can be found here on the GitHub repository here: tools/runtime/nagios/ixp-manager-check-core-bundles.sh.
The Nagios command and service definition is as follows (this is an example - please alter to suit your own environment):
define command {\n command_name check_ixpmanager_core_bundles\n command_line /path/to/ixp-manager-check-core-bundles.sh -k <API Key> -i $_HOSTDBID$ -u 'https://ixpmanager.example.com'\n}\n\ndefine service {\n use ixp-production-switch-service\n hostgroup_name ixp-production-switches\n service_description Core Bundles\n check_command check_ixpmanager_core_bundles\n}\nThe hostgroup_name and _HOSTDBID come from the Switch Monitoring section in Nagios Monitoring.
NB: Nagios monitoring requires that the Automated Polling / SNMP Updates for switches is working and is working for any switch you want monitored. The Nagios script / API check is a database check. This means if you poll switches every $x minutes (5 by default) and your Nagios script runs the service check every $y minutes (also 5 by default), the maximum delay in notification of a core bundle with issues should be approx. $x + $y minutes.
At INEX, we use Network Weathermap to create the weathermaps on our website.
This isn't something we can document exhaustively as it varys from IXP to IXP. The general approach to take is:
As an outline of this process, here's the script Nick created for INEX:
#!/bin/sh\n\nPATH=/opt/local/bin:${PATH}\netcdir=/opt/local/etc\n\nAPIKEY=xxxx\nAPIURL=https://ixpmanager.example.com/api/v4\n\ncurl -s -X GET -H \"X-IXP-Manager-API-Key: ${APIKEY}\" \\\n ${APIURL}/provisioner/corebundle/list.yaml > ${etcdir}/ixp-corebundles.yaml\ncurl -s -X GET -H \"X-IXP-Manager-API-Key: ${APIKEY}\" \\\n ${APIURL}/provisioner/switch/list.yaml > ${etcdir}/ixp-switches.yaml\n\nrender-jinja-template.py \\\n --yaml ${etcdir}/ixp-corebundles.yaml \\\n --yaml ${etcdir}/ixp-switches.yaml \\\n --yaml ${etcdir}/switchpos.yaml \\\n --jinja ${etcdir}/ixp-weathermap.conf\nThe switchpos.yaml file is a manual file that contains the x/y coordinates for each switch in the following format:
---\nswitchpos:\n\n swi1-cls1-1:\n x: 130\n y: 40\n\n swi1-cwt1-1:\n x: 50\n y: 100\nHopefully this helps - improving this is something that is on our TODO list.
"},{"location":"features/cronjobs/","title":"Cron Jobs - Task Scheduling","text":"Prior to IXP Manager v5, a number of cron jobs had to be configured manually. From v5.0 onwards, cron jobs are handled by Laravel's task scheduler. As such, you just need a single cron job entry such as:
* * * * * www-data cd /path-to-your-ixp-manager && php artisan schedule:run >> /dev/null 2>&1\nYou can see the full schedule in code here (look for the function protected function schedule(Schedule $schedule)).
The following tasks are run via this mechanism and are referenced elsewhere in the documentation:
telescope:prune daily.Some data should not be retained indefinitely for user privacy / GDPR / housekeeping reasons. The utils:expunge-logs command runs daily at 03:04 and currently:
An IXP assigns each customer (an) IP address(es) from the range used on the peering LAN(s). These IP addresses can show up in traceroutes (for example) and both IXPs and customers like to have these resolve to a hostname.
When creating VLAN Interfaces in IXP Manager there is a field called IPv[4/6] Hostname. This is intended for this DNS ARPA purpose. Some customers have specific requirements for these while other smaller customers may not fully understand the use cases. At INEX, we typically default to entries such as:
customer-name.v4.example.com (where example.com would be inex.ie in our case)customer-name.v6.example.comIXP Manager can generate your ARPA DNS entries for your peering IP space as per the hostnames configured on each VLAN interface and provide them in two ways:
Both of these are explained below.
Note that the API endpoints below can be tested in your browser by directly accessing the URLs when logged in. Otherwise, you need an API key when using them in scripts.
"},{"location":"features/dns-arpa/#as-json","title":"As JSON","text":"You can use the IXP Manager API to get all ARPA entries for a given VLAN and protocol as a JSON object using the following endpoint format:
https://ixp.example.com/api/v4/dns/arpa/{vlanid}/{protocol}\nwhere:
vlanid is the database ID (DB ID) of the VLAN. You can find the DB ID in IXP Manager in the VLAN table (select VLANs from the left hand side menu).protocol is either 4 for IPv4 or 6 for IPv6.If either of these are invalid, the API will return with a HTTP 404 response.
And example of the JSON response returned is:
[\n {\n \"enabled\": true,\n \"address\": \"192.0.2.67\",\n \"hostname\": \"cherrie.example.com\",\n \"arpa\": \"67.2.0.192.in-addr.arpa.\"\n },\n ...\n]\nwhere:
enabled indicates if the protocol has been enabled for this user. This is nearly always true. A situation where it may be false is if you enabled IPv6 for a user; then that user subsequently decided to not use IPv6; then you unchecked the IPv6 Enabled box in the VLAN Interface form without removing address / hostname entries.address - this IPv4/6 address of the VLAN interface as assigned by the IXP.hostname - the configured hostname for this address as entered into IXP Manager.arpa: the generated ARPA record name for the IP address assigned by the IXP.You can now feed the JSON object into a script to create your own DNS zones appropriate to your DNS infrastructure.
When scripting, we would normally pull the JSON object using something like:
#! /usr/bin/env bash\n\nKEY=\"your-ixp-manager-api-key\"\nURL=\"https://ixp.example.com/api/v4/dns/arpa\"\nVLANIDS=\"1 2\"\nPROTOCOLS=\"4 6\"\n\nfor v in $VLANIDS; do\n for p in $PROTOCOLS; do\n\n cmd=\"/usr/local/bin/curl --fail -s \\\n -H \\\"X-IXP-Manager-API-Key: ${KEY}\\\" \\\n ${URL}/${v}/${p} \\\n >/tmp/dns-arpa-vlanid$v-ipv$p.json.$$\"\n eval $cmd\n\n if [[ $? -ne 0 ]]; then\n echo \"ERROR: non-zero return from DNS ARPA API call for vlan ID $v with protocol $p\"\n continue\n fi\n\n // do something\n\n rm /tmp/dns-arpa-vlanid$v-ipv$p.json.$$\n done\ndone\nRather than writing your own scripts to consume the JSON object as above, it may be easier to use the bundled ISC Bind templates or to write your own template for IXP Manager.
You can use the IXP Manager API to get all ARPA entries for a given VLAN and protocol as plain text based on a template by using the following API endpoint:
https://ixp.example.com/api/v4/dns/arpa/{vlanid}/{protocol}/{template}\nwhere:
vlanid and protocol is as above in As JSON.template is the name of a template file residing in the view path api/v4/dns/.Remember that the included ISC Bind templates can be skinned or you can add custom templates to your skin directory. More detail on this can be found in the dedicated section below.
The bundled ISC Bind templates can be used by setting {template} to bind or bind-full in the above URL. For the example interface in the JSON above, the ISC Bind bind template would yield:
67.2.0.192.in-addr.arpa. IN PTR cherrie.example.com.\n(note that the terminated period on the hostname is added by the template)
The two bundled templates are:
bind: outputs resource records only as per the above example.bind-full: outputs a complete Bind zone file including head and serialized serial number (UNIX timestamp). This must be templated as it uses example.com for email and name server domains.You can use skinning to make changes to the bundled ISC Bind template or add your own.
Let's say you wanted to add your own template called mytemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/dns\ncp resources/views/api/v4/dns/bind.foil.php resources/skins/myskin/api/v4/dns/mytemplate1.foil.php\nYou can now edit this template as required. The only constraint on the template name is it can only contain characters from the classes a-z, 0-9, -. NB: do not use uppercase characters.
Contribute back - if you write a useful generator, please open a pull request and contribute it back to the project.
The following variables are available in the template:
$t->arpa: array of the ARPA entries - see below.$t->vlan: instance of the Vlan entity object.$t->protocol: either 4 or 6.The following variables are available for each element of the $t->arpa array (essentially the same as the JSON object above): enabled, hostname, address, arpa. See above for a description.
The actual code in the bundled ISC Bind sample is as simple as:
<?php foreach( $t->arpa as $a ): ?>\n<?= trim($a['arpa']) ?> IN PTR <?= trim($a['hostname']) ?>.\n<?php endforeach; ?>\nAt INEX, we have (for example) one peering LAN that is a /25 IPv4 network and so is not a zone file in its own right. As such, we make up the zone file using includes. The main zone file looks like:
$TTL 86400\n\n$INCLUDE /usr/local/etc/namedb/zones/soa-0.2.192.in-addr.arpa.inc\n\n$INCLUDE zones/inex-dns-slave-nslist.inc\n\n$INCLUDE zones/reverse-mgmt-hosts-ipv4.include\n$INCLUDE zones/reverse-vlan-12-ipv4.include\nThe SOA file looks like (as you might expect):
@ IN SOA ns.example.come. hostmaster.example.com. (\n 2017051701 ; Serial\n 43200 ; Refresh\n 7200 ; Retry\n 1209600 ; Expire\n 7200 ) ; Minimum\nThe reverse-vlan-12-ipv4.include is the output of the ISC Bind bind template above for a given VLAN ID.
We use the sample script update-dns-from-ixp-manager.sh which can be found in this directory to keep this updated ourselves.
IXP Manager has two document stores which allow administrators to upload and manage document. The two types are:
Both document stores support:
.txt) and display and parsing of Markdown (.md) files within IXP Manager.Also for the general document store, and non-public documents within it, logging and reporting of downloads (total downloads and unique user downloads).
Please note that all actions except for viewing and downloading files are restricted to super users.
The general document store is accessible:
The per-member document store is accessible:
In the following sections, we use screenshots from the general document store but will highlight and specific differences for the per-member document store.
"},{"location":"features/docstore/#directories","title":"Directories","text":"Directories are database entries to which uploaded files are attached (rather than actual directories on the storage media).
Directories can be created via the Create Directory button on the top right of the document store. See the following image showing the Create Directory form. As usual, contextual help is available via the green Help button.
To create per-member directories: First select the appropriate member from the Members/Customers list on the left-hand menu, then select the Documents tab, then select the Create Directory button on the top right.
Note that you do not need to set any permissions on directories - directories (and directory hierarchy) will only be visible to each user class if they contain files that the specific user class should be able to see.
If you enter a description, you will see a gray section at the top of the directory listing as shown in the following image. The text you enter will be parsed as Markdown and displayed as HTML. If you leave the description blank, no such section will be shown. This is a useful feature to provide context to your users about the documents in a given directory.
When viewing directories in a directory listing, a per-directory context menu is available per the following image and with the following two options:
Files can be uploaded via the Upload File button on the top right of the document store. See the following image showing the Upload File form with the contextual help shown (via the green Help button).
To upload per-member files: First select the appropriate member from the Members/Customers list on the left-hand menu, then select the Documents tab, then select the Upload File button on the top right.
The various fields are well explained by the contextual help above and we will add some additional emphasis here:
NB: for the per-member document store, there is no option to make a file Publicly available.
The following is how a file appears in a directory listing:
CUSTUSER indicates the minimum access permissions for the file. The numbers 19 (10) tell super admins that there have been a total of 19 downloads and 10 of those were unique to individual users in IXP Manager (i.e. some users would have downloaded this file two or more times). Note that only downloads by logged in users are counted. Publicly accessible files downloaded by non-logged in users are not recorded (if you must know this then that information is available from your web server log files). The date, Feb 29, 2020 is the date the file itself (not metadata) was last changed via the Edit option.
NB: there is no logging of files downloaded in the per-member document store. Please see below for more information.
The options in the per-file context menu are:
If you wish to purge the download logs for a file, you will find a Purge all download logs and reset download statistics checkbox on the file edit form. You can check this without making any other changes except to purge the logs.
"},{"location":"features/docstore/#sha256-functionality","title":"SHA256 Functionality","text":"Checksums can be used to verify the authenticity / integrity of downloaded files. The primary use-case when developing the Document Store at INEX was for official documents from the INEX Board of Directors which they wished to share with the membership - for example minutes of board meetings.
The INEX Board Secretary would provide the PDF documents to the operations team for upload. In parallel the Secretary would also email the members' mailing list to inform them that a new set of minutes are being uploaded and the secretary would include the sha256 checksum in that email. This is a useful way to independently verify the authenticity of official documents and the reason this feature exists.
When uploading (or changing an uploaded file), if you enter a sha256 checksum, it will be verified on upload (and rejected if it does not match). If you leave it blank, the sha256 checksum will be calculated by IXP Manager.
"},{"location":"features/docstore/#download-logs","title":"Download Logs","text":"The general Document Store logs file downloads / views by user. The total number of downloads and the unique users download count is shown on the directory listing. You can also get access to the individual download logs for each file via its context menu.
Non-unique individual download logs are expunged once they are more than six months old - except for the first download by each user. The user interface presents this information differently so that it is clear when you are looking at a file that is more than six months old.
There are a number of reasons to log file downloads:
However, there is no reasonable need that we can see to retain individual downloads for more than 6 months. As such, these are automatically expunged by the scheduler.
Note also that all we record is user ID, file ID and time. No IP address or other information is recorded.
"},{"location":"features/docstore/#patch-panel-files","title":"Patch Panel Files","text":"As a useful convenience, the per-member document store presents a virtual directory which collates any patch panel files that have been uploaded to a member's current or past cross connect record.
"},{"location":"features/docstore/#access-considerations","title":"Access Considerations","text":"IXP Manager generates a complete directory hierarchy for each of the four user classes. As such, users will only see the directory hierarchies that lead to files that are accessible to them. If a leaf directory does not contain a file that a user class cannot access then they will not see the directory in the listings.
Similarly, users will only see files listed that they can access.
If there are no documents in the Document Store for a specific user class (or public user), the the Document Store menu item will not appear under Customer / Member Information at the top of the page.
If you wish to complete disable the general document store, set the following option in .env:
IXP_FE_FRONTEND_DISABLED_DOCSTORE=true\nIf you wish to complete disable the per-member document store, set the following option in .env:
IXP_FE_FRONTEND_DISABLED_DOCSTORE_CUSTOMER=true\nThe best way to view the limitations described herein is to understand that the development goals of the document stores were to create something which is simple and secure while consciously avoiding a recreation of Dropbox or a CRM system. We discussed tens of features, dials and knobs for the document stores but chose to not implement them.
No backup / restore / undelete: if you delete a file (or directory) in the web user interface then you will also delete the file as it is stored on disk. This is not a soft-delete option and it does not include a Dropbox-esque undelete for 90 days. If you select and then confirm the deletion of a file or directory, then we assume you have made a deliberate and conscious decision to do just that.
It should be noted that while IXP Manager does not provide this kind of functionality - it also cannot reliably provide it. As a self-hosted application, it is up to the local system administrators to ensure adequate file system and database backups are in place. Then, with adequate local backup procedures (or the developers expectations that a copy of important documents would also be kept off IXP Manager's document store), restoration of deleted documents is possible.
No editing of files - particularly text and Markdown which are viewable within IXP Manager. We actually tried this but the code and user experience changes required pushed the complexity needle beyond where we wanted this feature to go.
Only superusers can upload / edit / delete files. This won't change for the general document store. We can review it for the per-member document store if the feature is requested.
Because only superusers can upload / edit files, there is no restriction on file types - we expect you to use your own good judgement here. There is also no restriction on file sizes - as a self-hosted application, storage space is your own consideration.
File upload size may be limited by your web server or PHP configuration. For PHP, find which .ini file is in use by running php --ini and then set the following as you wish (example values given):
upload_max_filesize = 100M\npost_max_size = 100M\nApache has no limit by default so if running Apache with PHP, just restart Apache (and / or PHP FPM) to apply the above. For Nginx, you need to set this as it has a default upload size of 1MB:
server {\n ...\n client_max_body_size 100M;\n}\nFor more information or other web server / PHP combinations, look at the specific documentation for those tools or Google it as this is a common question with many answers.
"},{"location":"features/helpdesk/","title":"Helpdesk Integration","text":"** WORK IN PROGRESS - DEVELOPMENT NOTES **
As an IXP scales, it will eventually have to replace email support via a simple alias / shared IMAP mailbox with a proper ticketing system. After extensive (and painful!) research, we at INEX chose Zendesk as the system that most matched our budget and required features (1).
While your mileage may vary on this - or you may already have something else - please note that the reference implementation for helpdesk integration on IXP Manager is Zendesk. So, if you haven't already chosen one, Zendesk will provide maximum integration with minimal pain.
Please do not open a feature request for other helpdesk implementations as the authors cannot undertake such additional work. If you wish to have integration with another helpdesk implemented, please consider commercial support
"},{"location":"features/helpdesk/#features-supported","title":"Features Supported","text":"IXP Manager currently supports:
Work that is in progress includes:
As Zendesk is the only implementation currently, this refers only to Zendesk.
"},{"location":"features/helpdesk/#zendesk","title":"Zendesk","text":"You need to enable API access to Zendesk as follows:
With your Zendesk login and the token from above, edit the .env file in the base directory of IXP Manager and set:
HELPDESK_BACKEND=zendesk\nHELPDESK_ZENDESK_SUBDOMAIN=ixp\nHELPDESK_ZENDESK_TOKEN=yyy\nHELPDESK_ZENDESK_EMAIL=john.doe@example.com\nYou can now test that your settings are correct with: FIXME
"},{"location":"features/helpdesk/#implementation-development","title":"Implementation Development","text":"The helpdesk implementation in IXP Manager is designed using contracts and service providers. I.e. it is done The Right Way (tm).
The reference implementation is for Zendesk but it's coded to a contract (interface) at app/Contracts/Helpdesk.php.
The actual Zendesk implementation can be found at: app/Services/Helpdesk/Zendesk.php.
The good news here is if you want another helpdesk supported, you just need to:
switch() statement in app/Providers/HelpdeskServiceProvider.php(1) Actually, Zendesk wasn't our first ticketing system. For a number of years we used Cerb but it didn't stay current in terms of modern HTML UI/UX and it suffered from feature bloat. One requirement for our replacement was a decent API and with Zendesk's API we were able to migrate all our old tickets using this script.
"},{"location":"features/irrdb/","title":"IRRDB Prefixes and ASN Filtering","text":"Prerequisite Reading: Ensure you first familiarize yourself with the generic documentation on managing and generating router configurations here.
IXP Manager can maintain a list of member route:/route6: prefixes and origin ASNs as registered in IRRDBs in its database and then use these to, for example, generate strict inbound filters on route servers.
"},{"location":"features/irrdb/#setup","title":"Setup","text":"You need to have set up some IRRDB sources (e.g. RIPE's whois service) under the IXP Admin Actions / IRRDB Configuration on the left hand side menu. If you do not have any entries here, there is a database seeder you can use to install some to start you off:
cd $IXPROOT\n./artisan db:seed --class=IRRDBs\nBGPQ3 is a very easy and fast way of querying IRRDBs. You first need to install this on your system. On a modern Ubuntu system this is as easy as:
apt install bgpq3\nThen configure the path to it in your .env file.
# Absolute path to run the bgpq3 utility\n# e.g. IXP_IRRDB_BGPQ3_PATH=/usr/local/bin/bgpq3\nIXP_IRRDB_BGPQ3_PATH=/usr/bin/bgpq3\nTo populate (and update) your local IRRDB, run the following commands:
cd $IXPROOT\nphp artisan irrdb:update-prefix-db\nphp artisan irrdb:update-asn-db\nFrom IXP Manager v5 onwards, and so long as your bgpq3 path is set as above and is executable, the task scheduler will take care of updating your local IRRDB a number of times a day. If you are using a version of IXP Manager before v5, then the above commands should be added to cron to run ~once per day (using the --quiet flag).
There are four levels of verbosity:
--quiet: no output unless there's an error / issue.-vv: include per customer and overall timings (database, processing and network).-vvv (debug): show prefixes/ASNs added remove also.You can also specify a specific customer to update (rather than all) with an additional free form parameter. The database is searched for a matching customer in the order: customer ASN; customer ID (database primary key); and customer shortname. E.g.:
php artisan irrdb:update-prefix-db 64511\nEssentially, based on a customers AS number / IPv4/6 Peering Macro, IXP Manager uses bgpq3 to query IRRDBs as follows:
bgpq3 -S $sources -l pl -j [-6] $asn/macro\nwhere $sources come from the IRRDB sources entries.
Or, a real example:
bgpq3 -S RIPE -l pl -j AS-BTIRE\nbgpq3 -S RIPE -l pl -j -6 AS-BTIRE\nThe IRRDB update commands will:
We use transactions to update the database so, even in the middle of a refresh, a full set of prefixes for all customers will still be available. It also means the update process can be safely interrupted.
Note that our current implementation only queries RADB as BGPQ3 does not support the RIPE whois protocol. Our version will however set the RADB source database according to the member's stated IRRDB database as set on the customer add / edit page - so, for customer's registered with the RIPE IRRDB, the RIPE database of RADB is queried.
"},{"location":"features/ixf-export/","title":"IX-F Member List Export","text":"The IX-F Member Export is an agreed and standardized JSON schema which allows IXPs to make their member lists available for consumption by tools such as PeeringDB, networks with automated peering managers, prospective members and the many other tools appearing in the peering eco-system.
Historical reference: INEX created and hosted a proof of concept directory for the IX-F Export Schema until Euro-IX/IX-F took it in house in 2018.
The key element of the IX-F Member Export is it makes you, the individual IXP, the canonical trusted source for data about your own IXP. Data that has the best chance of being correct and up to date. Particularly, PeeringDB has the option of allowing network data to be updated from IX records - see our documentation on this here.
To find out more about the JSON schema and see examples, you can read more here, explore many of the public IXP end points available here or see the GitHub euro-ix/json-schemas repository.
IXP Manager supports the IX-F Member List Export out of the box. It previously supported all versions from 0.3 to 0.5 but we now only support 0.6, 0.7 and 1.0 (for >=v5.1). We plan to deprecate support for 0.6 during 2019.
Sometimes you may need something more customized than the the IX-F Member Export. For that, see the other member export feature if IXP Manager.
"},{"location":"features/ixf-export/#preparing-the-ix-f-member-export","title":"Preparing the IX-F Member Export","text":"There are a small number of things you should do to ensure your IX-F export is correct.
Correctly set the PeeringDB ID and IX-F ID
The first is to ensure you have correctly set the PeeringDB ID and IX-F ID in your infrastructure (see Infrastructures under the left hand side IXP ADMIN ACTIONS menu).
The IX-F ID is mandatory. You will find yours by searching the IX-F providers database here. If you are a new IXP that is not registered here, please email your IXP's: full name, short name, city / region / country, GPS coordinates and website URL to ixpdb-admin (at) euro-ix (dot) net so they can register it in the IXPDB.
Create Network Info
From IXP Manager v4.9 and above, click VLANs on the left-hand-side menu and then chose Network Information. Once there, add the network address and network mask length for IPv4 and IPv6 for your peering LAN(s).
Prior to v4.9, this was a little hacky: there is a database table called networkinfo that requires you to manually insert some detail on your peering LAN.
The first thing you need is the peering VLAN DB ID. [clarification note: this is nothing to do with PeeringDB but the VLAN created within IXP Manager]. For this, select VLANs under the left hand side IXP ADMIN ACTIONS menu in IXP Manager. Locate your peering VLAN DB ID and note it.
For our example, we will use the following sample data:
192.0.2.0/25 with route servers on .8 and .92001:db8:1000::/64 with route servers on .8 and .9You need need to add this data to networkinfo with the following sample SQL commands:
INSERT INTO `networkinfo`\n ( `vlanid`, `protocol`, `network`, `masklen`, `rs1address`, `rs2address`),\nVALUES\n ( 66, 4, '192.0.2.0', '25', '192.0.2.8', '192.0.2.9' );\n\nINSERT INTO `networkinfo`\n ( `vlanid`, `protocol`, `network`, `masklen`, `rs1address`, `rs2address`),\nVALUES\n ( 66, 6, '2001:db8:1000::', '64', '2001:db8:1000::8', '2001:db8:1000::9' );\nSet Your IXP's Name / Country / etc
The third task is to ensure your IXP's details are correct in the IX-F export.
You will most likely have nothing to do here as it would have been done on installation but this reference may prove useful if there are any issues.
These are mostly set in the .env file (as well as some other places) and the following table shows how they get mapped to the IX-F Export:
shortname In IXP Manager, from the Infrastructure object name field name IDENTITY_LEGALNAME from .env country IDENTITY_COUNTRY from .env in 2-letter ISO2 format url IDENTITY_CORPORATE_URL from .env peeringdb_id In IXP Manager, from the Infrastructure object ixf_id In IXP Manager, from the Infrastructure object support_email IDENTITY_SUPPORT_EMAIL from .env support_phone IDENTITY_SUPPORT_PHONE from .env support_contact_hours IDENTITY_SUPPORT_HOURS from .env emergency_email IDENTITY_SUPPORT_EMAIL from .env emergency_phone IDENTITY_SUPPORT_PHONE from .env emergency_contact_hours IDENTITY_SUPPORT_HOURS from .env billing_email IDENTITY_BILLING_EMAIL billing_phone IDENTITY_BILLING_PHONE billing_contact_hours IDENTITY_BILLING_HOURS We we say from the Infrastructure object above, we mean that when you are logged into IXP Manager as an admin, it's the Infrastructures menu option under IXP Admin Actions on the left hand side.
"},{"location":"features/ixf-export/#accessing-the-ix-f-member-list","title":"Accessing the IX-F Member List","text":"If your version of IXP Manager is installed at, say, https://ixp.example.com/, then the IX-F Member List export can be accessed at:
https://ixp.example.com/api/v4/member-export/ixf/1.0\nwhere 1.0 is a version parameter which allows for support of potential future versions.
Note that the publicly accessible version does not include individual member details such as name, max prefixes, contact email and phone, when the member joined, member's web address, peering policy, NOC website, NOC hours or member type. This information is available to any logged in users or users querying the API with an API key.
"},{"location":"features/ixf-export/#access-without-ix-f-id-being-set","title":"Access Without IX-F ID Being Set","text":"While the IX-F ID is officially required for >= v0.7 of the schema, it may be overlooked on new installations or some IXPs may be uninterested in working with the IX-F IXP database.
The schema requirement for a valid IX-F ID should not prevent the IX-F exporter from working if someone wishes to pull the information regardless of that being set. There are two ways to override this and query the API available from IXP Manager v5.7.0:
The first is to pass an ixfid_y parameter (where y is the database ID of the infrastructure) every infrastructure that does not have one. Using this method will have IXP Manager set the IX-F ID in the generated JSON output suitable for processing by automated scripts. A sample URL for an IXP with two infrastructures might look like this:
https://ixpmanager.example.com/api/v4/member-export/ixf/1.0?ixfid_1=30&ixfid_2=31\nIf you wish to just ignore the IX-F ID and have it set to zero in the JSON output, you can use the following flag:
https://ixpmanager.example.com/api/v4/member-export/ixf/1.0?ignore_missing_ixfid=1\nIXPDB requires two pieces of information to fully integrate with the IXPDB. You can provide this information to ixpdb-admin (at) euro-ix (dot) net or - if you have a login to the Euro-IX website, you should be able to login and edit your own IXP directly on IXPDB.
The first element needed is the API endpoint as described above in Accessing the IX-F Member List.
The second is the API endpoint to export your statistics. This is:
https://ixp.example.com/grapher/infrastructure?id=1&type=log&period=day\nwhere id=1 is the infrastructure DB ID (see Infrastructures under the left hand side IXP ADMIN ACTIONS menu).
To disable public access to the restricted member export, set the following in your .env file:
IXP_API_JSONEXPORTSCHEMA_PUBLIC=false\nWe strongly advise you not to disable public access if you are a standard IXP. Remember, the public version is essentially the same list as you would provide on your standard website's list of members.
In addition, membership of an IXP is easily discernible from a number of other sources including:
Leave public access available, own your own data, ensure it's validity and advertise it!
If you must disable public access but would still like to provide IX-F (or others) with access, you can set a static access key in your .env file such as:
IXP_API_JSONEXPORTSCHEMA_ACCESS_KEY=\"super-secret-access-key\"\nand then provide the URL in the format:
https://ixp.example.com/api/v4/member-export/ixf/1.0?access_key=super-secret-access-key\nIf you wish to control access to the infrastructure statistics, see the Grapher API documentation. The statistics data is a JSON object representing each line of a the rest of the file from a standard MRTG log file. This means the per-line array elements are:
It is possible to exclude some data from v6.0.1 per GitHub issue #722:
While some exchanges are willing to share detailed information about their infrastructure via the IX-F Member Export Schema, others either do not want to or cannot due to regulation. Enabling exchanges to share a limited set of data about their infrastructure would help exchanges find others using the same platforms to learn from each other and shows the diversity of platforms in use across the market.
Please bear in mind that the more data you remove, the less useful the IX-F member export becomes. Most IXPs do not use this exclusion function and, ideally, you will only use it if there is no other choice.For example, a switch object typically looks like:
{\n \"id\": 50,\n \"name\": \"swi1-kcp1-2\",\n \"colo\": \"Equinix DB2 (Kilcarbery)\",\n \"city\": \"Dublin\",\n \"country\": \"IE\",\n \"pdb_facility_id\": 178,\n \"manufacturer\": \"Arista\",\n \"model\": \"DCS-7280SR-48C6\",\n \"software\": \"EOS 4.24.3M\"\n}\nIf, for example, you need to exclude the model and software version, you can add the following to your .env file:
IXP_API_JSONEXPORTSCHEMA_EXCLUDE_SWITCH=\"model|software\"\nwhich will yield:
{\n \"id\": 50,\n \"name\": \"swi1-kcp1-2\",\n \"colo\": \"Equinix DB2 (Kilcarbery)\",\n \"city\": \"Dublin\",\n \"country\": \"IE\",\n \"pdb_facility_id\": 178,\n \"manufacturer\": \"Arista\"\n}\nAs you can see, the configuration option is the set of identifiers you want to exclude (model and software) separated with the pipe symbol. Different combinations are possible - here are some examples:
IXP_API_JSONEXPORTSCHEMA_EXCLUDE_SWITCH=\"software\"\nIXP_API_JSONEXPORTSCHEMA_EXCLUDE_SWITCH=\"model|software\"\nIXP_API_JSONEXPORTSCHEMA_EXCLUDE_SWITCH=\"city|model|software\"\nYou should not exclude the id as these is referred to in the member interface list.
You can exclude detail for the IXP object:
{\n \"shortname\": \"INEX LAN1\",\n \"name\": \"Internet Neutral Exchange Association Limited by Guarantee\",\n \"country\": \"IE\",\n \"url\": \"https:\\/\\/www.inex.ie\\/\",\n \"peeringdb_id\": 48,\n \"ixf_id\": 20,\n \"ixp_id\": 1,\n \"support_email\": \"operations@example.com\",\n \"support_contact_hours\": \"24x7\",\n \"emergency_email\": \"operations@example.com\",\n \"emergency_contact_hours\": \"24x7\",\n \"billing_contact_hours\": \"8x5\",\n \"billing_email\": \"accounts@example.com\",\n ...\n}\nwith the option:
IXP_API_JSONEXPORTSCHEMA_EXCLUDE_IXP=\"name|url\"\nYou should not exclude any of the IDs (peeringdb_id, ixf_id and ixp_id) as these is referred to else where in the document and required externally when using the data.
You can exclude member detail:
{\n \"asnum\": 42,\n \"member_since\": \"2009-01-13T00:00:00Z\",\n \"url\": \"http:\\/\\/www.pch.net\\/\",\n \"name\": \"Packet Clearing House DNS\",\n \"peering_policy\": \"open\",\n \"member_type\": \"peering\",\n ...\n}\nwith the option:
IXP_API_JSONEXPORTSCHEMA_EXCLUDE_MEMBER=\"peering_policy|member_type\"\nAnd finally, you can include member VLAN/protocol detail:
\"ipv4\": {\n \"address\": \"185.6.36.60\",\n \"as_macro\": \"AS-PCH\",\n \"routeserver\": true,\n \"mac_addresses\": [\n \"00:xx:yy:11:22:33\"\n ],\n \"max_prefix\": 2000\n},\n\"ipv6\": {\n \"address\": \"2001:7f8:18::60\",\n \"as_macro\": \"AS-PCH\",\n \"routeserver\": true,\n \"mac_addresses\": [\n \"00:xx:yy:11:22:33\"\n ],\n \"max_prefix\": 2000\n}\nwith the option:
IXP_API_JSONEXPORTSCHEMA_EXCLUDE_INTINFO=\"mac_addresses|routeserver\"\nPlease note that the IXP_API_JSONEXPORTSCHEMA_EXCLUDE_INTINFO affects both the ipv4 and ipv6 clauses.
You can exclude members by ASN or by tag by setting the following .env option:
# Exclude members with certain AS numbers\n# IXP_API_JSONEXPORTSCHEMA_EXCLUDE_ASNUM=\"65001|65002|65003\"\n\n# Exclude members with certain tags\n# IXP_API_JSONEXPORTSCHEMA_EXCLUDE_TAGS=\"tag1|tag2\"\nThe following are enabled by default to prevent exporting test customers:
# Exclude documentation ASNs (64496 - 64511, 65536 - 65551)\n# IXP_API_JSONEXPORTSCHEMA_EXCLUDE_RFC5398=true\n\n# Exclude private ASNs (64512 - 65534, 4200000000 - 4294967294)\n# IXP_API_JSONEXPORTSCHEMA_EXCLUDE_RFC6996=true\nIf you pass withtags=1 as a parameter to the URL endpoint, then you will get an extra section in each member section:
\"ixp_manager\": {\n \"tags\": {\n \"exampletag1\": \"Example Tag #1\",\n \"exampletag2\": \"Example Tag #2\"\n },\n \"in_manrs\": false,\n \"is_reseller\": false,\n \"is_resold\": true,\n \"resold_via_asn\": 65501\n},\nAs you can see:
is_manrs indicates if the member is MANRS compliant.is_reseller indicates if this member is a reseller.is_resold indicates if the member has come via a reseller and, if so, resold_via_asn provides the AS number of the reseller.A common requirement of IXPs is to create a public member list on their official website. This can be done with the IX-F Member Export quite easily. The below HTML and JavaScript is a way to do it with INEX's endpoint. There's a live JSFiddle which demonstrates this also - https://jsfiddle.net/barryo/2tzuypf9/.
The HTML requires just a table with a placeholder and an id on the body:
<table class=\"table table-bordered\" style=\"margin: 10px\">\n <thead>\n <tr>\n <th>Company</th>\n <th>ASN</th>\n <th>Connections</th>\n </tr>\n </thead>\n <tbody id=\"list-members\">\n <tr>\n <td colspan=\"3\">Please wait, loading...</td>\n </tr>\n </tbody>\n</table>\nThe JavaScript loads the member list via the IX-F Export and processes it into the table above:
// Sample IX-F Member Export to Member List script\n//\n// License: MIT (https://en.wikipedia.org/wiki/MIT_License)\n// By @yannrobin and @barryo\n// 2018-03-06\n\nfunction prettySpeeds( s ) {\n switch( s ) {\n case 10: return \"10Mb\";\n case 100: return \"100Mb\";\n case 1000: return \"1Gb\";\n case 10000: return \"10Gb\";\n case 40000: return \"40Gb\";\n case 100000: return \"100Gb\";\n default: return s;\n }\n}\n\n$.getJSON( \"https://www.inex.ie/ixp/api/v4/member-export/ixf/0.7\", function( json ) {\n\n // sort by name\n json[ 'member_list' ].sort( function(a, b) {\n var nameA = a.name.toUpperCase(); // ignore upper and lowercase\n var nameB = b.name.toUpperCase(); // ignore upper and lowercase\n if (nameA < nameB) {\n return -1;\n }\n if (nameA > nameB) {\n return 1;\n }\n // names must be equal\n return 0;\n });\n\n let html = '';\n\n $.each( json[ 'member_list' ], function(i, member) {\n html += `<tr>\n <td>\n <a target=\"_blank\" href=\"${member.url}\">${member.name}</a>\n </td>\n <td>\n <a target=\"_blank\"\n href=\"http://www.ripe.net/perl/whois?searchtext=${member.asnum}&form_type=simple\">\n ${member.asnum}\n </a>\n </td>`;\n\n let connection = '';\n $.each( member[ 'connection_list' ], function(i, conn ) {\n if( conn[ 'if_list' ].length > 1 ){\n connection += conn[ 'if_list' ].length+ '*'\n }\n connection += prettySpeeds( conn[ 'if_list' ][0].if_speed );\n\n if(i < (member[ 'connection_list' ].length - 1 )){\n connection += \" + \";\n }\n });\n\n html += `<td>${connection}</td></tr>\\n`;\n });\n\n $( \"#list-members\" ).html(html);\n});\nThe end result is a table that looks like:
Company | ASN | Connections | --------------------|----------------------------------| 3 Ireland | 34218 | 2*10Gb + 2*10Gb | Afilias | 12041 | 1Gb | ... | ... | ... |
"},{"location":"features/layer2-addresses/","title":"MAC Addresses","text":"IXP Manager has support for layer2 / MAC addresses in two ways:
In early 2017, INEX migrated its primary peering LAN from a flat layer2 with spanning tree design to a VxLAN set-up with automation via Salt and Napalm (we will insert references to presentations here once we complete all required functionality).
Part of the requirements for this automation (and this was an existing feature request from other IXPs) was the management of MAC addresses within IXP Manager and, rather than assigning them to a virtual interface, assign them to specific VLAN interfaces.
Outside of our automation and VXLAN, other uses included:
The features of this system are listed below.
"},{"location":"features/layer2-addresses/#listing-and-searching-existing-configured-mac-addresses","title":"Listing and Searching Existing Configured MAC Addresses","text":"There is a new menu option (left hand side menu) under MAC Addresses called Configured Addresses. This lists all configured MAC addresses including the OUI manufacturer (see below), associated switch / switch port(s), customer name, IPv4 and v6 addresses. You can also:
When editing a customer's interface in the usual manner (customer overview -> Ports -> edit button), you will now see MAC address(es) under VLAN Interfaces:
In the event that there is zero or more than one MAC address, the MAC address demonstrated above will be replaced with an appropriate note to indicate this.
Clicking on the MAC address (or note when none / multiple) will bring you to the configured MAC address management page for this VLAN interface. Addresses can be added / removed on this page. MAC addresses can be entered in either upper or lower cases and can optionally include characters such as ., :, -. These are all stripped before validation and insertion.
As automation features are still a work in progress, not all methods are listed here. Please open an issue on GitHub or start a discussion on the mailing list for whatever methods you would like.
Currently implemented (see the API page for access details):
INEX's use case was to switch from the discovered MAC addresses table to the configured MAC addresses table without the need to data fill all preexisting ~200 MACs. As such we have created an Artisan migration script which can be run with:
php $IXPROOT/artisan l2addresses:populate\nYou will be prompted as follows:
Are you sure you wish to proceed? This command will CLEAR the layer2address table and then copy addresses from the read-only macaddress table. Generally, this command should only ever be run once when initially populating the new table.
One thing to note: as the discovered MAC Addresses table is per virtual interface and the new configured MAC address functionality is per VLAN interface, any MAC from discovered MAC Addresses that is populated into configured MAC Addresses will be populated for every VLAN interface associated with the virtual interface.
The script prints notices for these such as:
Created >1 layer2address for [member name]] with virtual interface: https://www.example.com/ixp/virtual-interface/edit/id/235
The inclusion of the URL makes it easy to double check the result.
For obvious reasons, we only allow a single / unique layer2 address per VLAN. In the event that the script tries to add the same MAC more than once, it will print:
Could not add additional instance of 001122334455 for [Customer]] with virtual interface: https://www.example.com/ixp/virtual-interface/edit/id/265 as it already exists in this Vlan [VLAN name]
These should all be checked manually.
A useful SQL command to double check the results for me was:
SELECT mac, COUNT(mac) AS c FROM l2address GROUP BY mac HAVING COUNT(mac) > 1;\nThis was the original functionality - a read-only table via an admin menu option called MAC Addresses -> Discovered Addresses which lists entries from a database of MAC addresses which are sourced via a script from the IXP's switches directly.
At an IXP, it can be extremely useful to have a quick look up table to see what member owns what MAC address - especially when they start injecting illegal packets into the exchange fabric.
We have a script, update-l2database.pl, for this. To set it up (using Ubuntu as an example), proceed as below. We are in the process of trying to reduce the reliance on the perl library and direct database access. But for now, this script still requires it.
# If you haven't already, install the Perl library for IXP Manager:\napt-get install libnet-snmp-perl libconfig-general-perl libnetaddr-ip-perl\ncd $IXPROOT/tools/perl-lib/IXPManager\nperl Makefile.PL\nmake install\n\n# Then copy and edit the configuration file to set the database connection settings:\ncp $IXPROOT/tools/perl-lib/IXPManager/ixpmanager.conf.dist /usr/local/etc/ixpmanager.conf\njoe /usr/local/etc/ixpmanager.conf #and set database settings\n\n# Now copy the script:\ncp $IXPROOT/tools/runtime/l2database/update-l2database.pl /usr/local/bin\n\n# and then add it to your periodic cron job with:\n/usr/local/bin/update-l2database.pl\nIXP Manager can store the IEEE OUI database and reference it to show the manufacturer behind a MAC address.
"},{"location":"features/layer2-addresses/#populating-and-updating-the-oui-database","title":"Populating and Updating the OUI Database","text":"The OUI is updated weekly by the task scheduler. You can force an update with the following Artisan command:
php $IXPROOT/artisan utils:oui-update\nwhich will populate / update the OUI database directly from the latest IEEE file from their website.
A specific file can be passed via the file parameter. You can also force a database reset (drop all OUI entries and re-populate) via the --refresh option.
Neither of these options are typically necessary.
"},{"location":"features/layer2-addresses/#end-user-access","title":"End User Access","text":"In v4.7.3 we introduced the ability for logged in users to management their own configured MAC addresses.
This is disabled by default but can be enabled with the following .env settings:
# Set this to allow customers to change their own configured MAC addresses:\nIXP_FE_LAYER2_ADDRESSES_CUST_CAN_EDIT=true\n\n# The following defaults are configured for min/max MAC addresses\nIXP_FE_LAYER2_ADDRESSES_CUST_PARAMS_MIN_ADDRESSES=1\nIXP_FE_LAYER2_ADDRESSES_CUST_PARAMS_MAX_ADDRESSES=2\nWhen a MAC is added, a IXP\\Events\\Layer2Address\\Added event is triggered and, similarly, when a MAC is deleted a IXP\\Events\\Layer2Address\\Deleted event is triggered. We have created an event listener for these to fire off an email in both cases. To enable this listener, set the following .env settings:
# Trigger an email when a superuser adds/deletes a MAC:\nIXP_FE_LAYER2_ADDRESSES_EMAIL_ON_SUPERUSER_CHANGE=true\n\n# Trigger an email when a customer user adds/deletes a MAC:\nIXP_FE_LAYER2_ADDRESSES_EMAIL_ON_CUSTOMER_CHANGE=true\n\n# Destination address of the email:\nIXP_FE_LAYER2_ADDRESSES_EMAIL_ON_CHANGE_DEST=ops@ixp.example.net\nThere are two files you can consider skinning with this functionality:
resources/views/layer2-address/emails/changed.blade.php - the email which is sent when a MAC is added / removed.resources/views/layer2-address/customer-edit-msg.foil.php - an informational alert box that is shown to the customer on the MAC add/delete page to set their expectations on time to complete on the IXP end.IXP Manager supports full looking glass features when using the Bird BGP daemon and Bird's Eye (a simple secure micro service for querying Bird).
A fully working example of this can be seen here on INEX's IXP Manager.
Enabling the looking glass just requires:
.env option: IXP_FE_FRONTEND_DISABLED_LOOKING_GLASS=false (in IXP Manager's .env and add it if it's missing as it defaults to true).The looking glass will not work if the versions are not matched correctly as above.
"},{"location":"features/looking-glass/#example-router-configuration","title":"Example Router Configuration","text":"See this screenshot for an appropriately configured INEX router with Bird's Eye:
"},{"location":"features/looking-glass/#looking-glass-pass-thru-api-calls","title":"Looking Glass 'Pass Thru' API Calls","text":"Depending on the configured LG Access Privileges for a given router, IXP Manager will pass through the following API calls to the router API.
https://ixp.example.com/api/v4/lg/{handle}/statushttps://ixp.example.com/api/v4/lg/{handle}/bgp-summaryand return the JSON result.
The rationale for this is that we expect most IX's to keep direct access to looking glass implementations on internal / private networks.
Here are two live examples from INEX:
You can see all of INEX's looking glasses at https://www.inex.ie/ixp/lg. GRNET have also a public IXP Manager integration at: https://portal.gr-ix.gr/lg.
"},{"location":"features/looking-glass/#debugging","title":"Debugging","text":"Generally speaking, if you carefully read the above and the Bird's Eye README file, you should be able to get IXP Manager / Bird's Eye integration working.
If you do not, try all of the following and solve any elements that fail. If you still have issues, email the IXP Manager mailing list with the output of all of the following commands from both sections.
For the following examples, we will use a real INEX example router with these settings:
mysql> SELECT * FROM routers WHERE id = 17\\G\n*************************** 1. row ***************************\n id: 17\n vlan_id: 2\n handle: as112-lan1-ipv4\n protocol: 4\n type: 3\n name: INEX LAN1 - AS112 - IPv4\n shortname: AS112 - LAN1 - IPv4\n router_id: 185.6.36.6\n peering_ip: 185.6.36.6\n asn: 112\n software: 1\n mgmt_host: 10.39.5.6\n api: http://as112-lan1-ipv4.mgmt.inex.ie/api\n api_type: 1\n lg_access: 0\n quarantine: 0\n bgp_lc: 0\n template: api/v4/router/as112/bird/standard\n skip_md5: 1\nlast_updated: 2018-02-03 14:26:15\nFrom the server running IXP Manager:
###############################################################################\n# Does the API hostname resolve?\n$ dig +short as112-lan1-ipv4.mgmt.inex.ie\n\n10.39.5.6\n\n\n###############################################################################\n# Is there network access?\n$ ping as112-lan1-ipv4.mgmt.inex.ie -c 1\n\nPING as112.mgmt.inex.ie (10.39.5.6) 56(84) bytes of data.\n64 bytes from as112.mgmt.inex.ie (10.39.5.6): icmp_seq=1 ttl=64 time=0.103 ms\n\n--- as112.mgmt.inex.ie ping statistics ---\n1 packets transmitted, 1 received, 0% packet loss, time 0ms\nrtt min/avg/max/mdev = 0.103/0.103/0.103/0.000 ms\n\n\n###############################################################################\n# Is the Bird's Eye service available?\n$ curl -v http://as112-lan1-ipv4.mgmt.inex.ie/api/status\n\n* Trying 10.39.5.6...\n* Connected to as112-lan1-ipv4.mgmt.inex.ie (10.39.5.6) port 80 (#0)\n> GET /api/status HTTP/1.1\n> Host: as112-lan1-ipv4.mgmt.inex.ie\n> User-Agent: curl/7.47.0\n> Accept: */*\n>\n< HTTP/1.1 200 OK\n< Cache-Control: no-cache\n< Content-Type: application/json\n< Date: Mon, 12 Feb 2018 16:29:52 GMT\n< Transfer-Encoding: chunked\n< Server: lighttpd/1.4.35\n<\n* Connection #0 to host as112-lan1-ipv4.mgmt.inex.ie left intact\n\n{\n \"api\": {\n \"from_cache\":true,\n \"ttl_mins\":1,\n \"version\":\"1.1.0\",\n \"max_routes\":1000\n },\n \"status\": {\n \"version\":\"1.6.3\",\n \"router_id\":\"185.6.36.6\",\n \"server_time\":\"2018-02-12T16:29:48+00:00\",\n \"last_reboot\":\"2017-11-09T00:23:24+00:00\",\n \"last_reconfig\":\"2018-02-12T16:26:14+00:00\",\n \"message\":\"Daemon is up and running\"\n }\n}\nIf all of the above checks out, watch the log file while you try and access the looking glass:
cd $IXPROOT\ntail -f storage/log/laravel.log\nIf there are error messages in the above log as you try and access the looking glass, include them when emailing the mailing list for help.
Then on the router (the server running Bird's Eye), you need to provide the following answers when seeking help:
###############################################################################\n# Are you running the correct version of Bird's Eye for IXP Manager?\n\ncat /srv/birdseye/version.php\n\n# see the documentation above for the correct versions to match to IXP Manager.\n\n###############################################################################\n# Is Bird actually running and what are the names of its sockets:\n$ ls -la /var/run/bird\n\ntotal 0\ndrwxrwxr-x 2 bird bird 120 Nov 9 00:26 .\ndrwxr-xr-x 25 root root 900 Feb 12 19:40 ..\nsrw-rw---- 1 root root 0 Nov 9 00:23 bird-as112-lan1-ipv4.ctl\nsrw-rw---- 1 root root 0 Nov 9 00:23 bird-as112-lan1-ipv6.ctl\nsrw-rw---- 1 root root 0 Nov 9 00:23 bird-as112-lan2-ipv4.ctl\nsrw-rw---- 1 root root 0 Nov 9 00:23 bird-as112-lan2-ipv6.ctl\n\n###############################################################################\n# What configuration file(s) exist:\n$ ls -la /srv/birdseye/*env\n\n-rw-r--r-- 1 root root 2833 Dec 5 2016 /srv/birdseye/birdseye-as112-lan1-ipv4.env\n-rw-r--r-- 1 root root 2833 Dec 5 2016 /srv/birdseye/birdseye-as112-lan1-ipv6.env\n-rw-r--r-- 1 root root 2833 Dec 5 2016 /srv/birdseye/birdseye-as112-lan2-ipv4.env\n-rw-r--r-- 1 root root 2833 Dec 5 2016 /srv/birdseye/birdseye-as112-lan2-ipv6.env\n\n###############################################################################\n# Let's see the contents of these:\n#\n# NB: when specifying the BIRDC parameter below, for Bird v1.x.y, use the -4/-6\n# switch when querying the ipv4/6 daemon respectively. For Bird v2.x.y, use\n# the -2 switch.\n#\n$ cat /srv/birdseye/*env | egrep -v '(^#)|(^\\s*$)'\n\nBIRDC=\"/usr/bin/sudo /srv/birdseye/bin/birdc -4 -s /var/run/bird/bird-as112-lan1-ipv4.ctl\"\nCACHE_DRIVER=file\nLOOKING_GLASS_ENABLED=true\nBIRDC=\"/usr/bin/sudo /srv/birdseye/bin/birdc -6 -s /var/run/bird/bird-as112-lan1-ipv6.ctl\"\nCACHE_DRIVER=file\nLOOKING_GLASS_ENABLED=true\nBIRDC=\"/usr/bin/sudo /srv/birdseye/bin/birdc -4 -s /var/run/bird/bird-as112-lan2-ipv4.ctl\"\nCACHE_DRIVER=file\nLOOKING_GLASS_ENABLED=true\nBIRDC=\"/usr/bin/sudo /srv/birdseye/bin/birdc -6 -s /var/run/bird/bird-as112-lan2-ipv6.ctl\"\nCACHE_DRIVER=file\nLOOKING_GLASS_ENABLED=true\n\n###############################################################################\n# Test birdc access to the daemon - run for each socket found above:\n# (only one shown here for brevity - include all in your request for help!)\n$ /usr/sbin/birdc -s /var/run/bird/bird-as112-lan1-ipv4.ctl show status\n\nBIRD 1.6.3 ready.\nBIRD 1.6.3\nRouter ID is 185.6.36.6\nCurrent server time is 2018-02-12 19:42:42\nLast reboot on 2017-11-09 00:23:25\nLast reconfiguration on 2018-02-12 19:26:15\nDaemon is up and running\n\n###############################################################################\n# Have you created the sudo file for www-data to be able to access Birdc?\n$ cat /etc/sudoers /etc/sudoers.d/* | grep birdseye\n\nwww-data ALL=(ALL) NOPASSWD: /srv/birdseye/bin/birdc\n\n###############################################################################\n# Does the Bird's Eye client work?\n#\u00a0Run for each socket found above with the appropriate protocol (-4/-6):\n# (only one shown here for brevity - include all in your request for help!)\n\n$ /srv/birdseye/bin/birdc -4 -s /var/run/bird/bird-as112-lan1-ipv4.ctl show status\n\nBIRD 1.6.3 ready.\nAccess restricted\nBIRD 1.6.3\nRouter ID is 185.6.36.6\nCurrent server time is 2018-02-12 19:44:31\nLast reboot on 2017-11-09 00:23:25\nLast reconfiguration on 2018-02-12 19:26:15\nDaemon is up and running\n\n\n###############################################################################\n# Is the web server running:\n$ netstat -lpn | grep lighttpd\n\ntcp 0 0 10.39.5.6:80 0.0.0.0:* LISTEN 1165/lighttpd\ntcp6 0 0 2001:7f8:18:5::6:80 :::* LISTEN 1165/lighttpd\nunix 2 [ ACC ] STREAM LISTENING 13970 635/php-cgi /var/run/lighttpd/php.socket-0\n\n###############################################################################\n# Is PHP running:\n$ netstat -lpn | grep php\n\nunix 2 [ ACC ] STREAM LISTENING 13970 635/php-cgi /var/run/lighttpd/php.socket-0\n\n###############################################################################\n# what's the web server configuration\n# NB: make sure you have compared it to:\n# https://github.com/inex/birdseye/blob/master/data/configs/lighttpd.conf\n$ cat /etc/lighttpd/lighttpd.conf\n\n<not included but linked two lines up>\n\n###############################################################################\n# provide the IXP Manager configuration of your router(s):\nmysql> SELECT * FROM routers\\G\n\n<not included - see example at start of this section>\nIXP Manager has the ability to allow users to subscribe / unsubscribe from Mailman mailing lists (it should be relatively easy to expand this to other mailing list managers as the functionality is based on Mailman but not Mailman specific).
The following sections explain the steps in how this is set up.
NB: This facility does not perform a 100% synchronisation. Any mailing list members that are added separately without a matching user in IXP Manager are not interfered with.
"},{"location":"features/mailing-lists/#configuring-available-mailing-lists","title":"Configuring Available Mailing Lists","text":"There is a sample configuration file which you need to copy as follows:
cd $IXPROOT\ncp config/mailinglists.php.dist config/mailinglists.php\nYou then need to edit this file as follows:
Enable the mailing list functionality by setting this to true:
// Set the following to 'true' to enable mailing list functionality:\n'enabled' => true,\nIf this is not set to true, the user will not be offered subscription options and the CLI/API commands will not execute.
Configure the available mailing list(s) in the lists array. Here is an example:
'lists' => [\n 'members' => [\n 'name' => \"Members' Mailing List\",\n 'desc' => \"A longer description as presented in IXP Manager.\",\n 'email' => \"members@example.com\",\n 'archive' => \"https://www.example.com/mailman/private/members/\",\n ],\n 'tech' => [\n 'name' => \"Tech/Operations Mailing List\",\n 'desc' => \"A longer description as presented in IXP Manager.\",\n 'email' => \"tech@example.com\",\n 'archive' => \"https://www.example.com/mailman/private/tech/\",\n ],\n],\nNote that the members and tech array keys above are the list handles that will be used by the API interfaces later. It is also important that they match the Mailman list key.
Historically, mailing list passwords were also sync'd from the IXP Manager user database unless syncpws is both defined and false for the given list. As we are now enforcing bcrypt as the standard password hashing mechanism, we no longer support this and suggest allowing Mailman to manage its own passwords.
Paths to Mailman commands. These will be used in the API/CLI elements later:
'mailman' => [\n 'cmds' => [\n 'list_members' => \"/usr/local/mailman/bin/list_members\",\n 'add_members' => \"/usr/local/mailman/bin/add_members -r - -w n -a n\",\n 'remove_members' => \"/usr/local/mailman/bin/remove_members -f - -n -N\",\n 'changepw' => \"/usr/local/mailman/bin/withlist -q -l -r changepw\"\n ]\n]\nThis mailing list synchronisation / integration code was written for existing Mailman lists we have at INEX where some lists are public with subscribers that will never have an account on INEX's IXP Manager. As such, these scripts are written so that email addresses in common between IXP Manager and Mailman can manage their subscriptions in IXP Manager but those other subscribers will be unaffected.
Users in IXP Manager will either be marked as being subscribed to a list, not subscribed to a list or neither (i.e. a new user). Subscriptions are managed by user preferences (in the database) of the format:
mailinglist.listname1.subscribed = 0/1\nThere are three steps to performing the synchronisation for each list which are done by either using the IXP Manager CLI script artisan mailing-list:... or the API interface.
NB: these relate to the CLI as implemented from IXP Manager >= v4.7.
The execution of the artisan mailing-list:init script which is really for new IXP Manager users (or initial set up of the mailing list feature). This script is piped the full subscribers list from Mailman (via list_members). This function will iterate through all users and, if they have no preference set for subscription to this list, will either add a \"not subscribed\" preference if their email address is not in the provided list of subscribers or a \"subscribed\" preference if it is.
The execution of the artisan mailing-list:get-subscribers action which lists all users who are subscribed to the given mailing list based on their user preferences. This is piped to the add_members Mailman script.
The execution of the artisan mailing-list:get-subscribers --unsubscribed action which lists all users who are unsubscribed to the given mailing list based on their user preferences. This is piped to the remove_members Mailman script.
The API v4 implementation was added in IXP Manager v4.7. See the end of this document for the API v1 implementation in previous versions of IXP Manager.
If you wish to use the API version, proceed as follows where:
$KEY is one of your SUPERUSER API keys (see here for details);https://ixp.example.com is your IXP Manager web interface;members is an example mailing list handle as defined above in $IXPROOT/config/mailinglists.php.Use the initialisation function for new IXP Manager users (or initial set up of the mailing list feature) which updates IXP Manager with all currently subscribed mailing list members:
/path/to/mailman/bin/list_members members >/tmp/ml-members.txt\ncurl -f --data-urlencode addresses@/tmp/ml-members.txt \\\n -H \"X-IXP-Manager-API-Key: $KEY\" -X POST\n \"https://ixp.example.co/api/v4/mailing-list/init/members\"\nrm /tmp/ml-members.txt\nPipe all subscribed users to the add_members Mailman script:
curl -f -H \"X-IXP-Manager-API-Key: $KEY\" -X GET \\\n \"https://ixp.example.co/api/v4/mailing-list/subscribers/members\" | \\\n /path/to/mailman/bin/add_members -r - -w n -a n members >/dev/null\nPipe all users who are unsubscribed to the remove_members Mailman script:
curl -f -H \"X-IXP-Manager-API-Key: $KEY\" -X GET \\\n \"https://ixp.example.co/api/v4/mailing-list/unsubscribed/members\" | \\\n /path/to/mailman/bin/remove_members -f - -n -N members >/dev/null\nYou can implement mailing list management by configuring IXP Manager as above.
IXP Manager will generate shell scripts to manage all of the above.
Execute the following command for the CLI version (and make sure to update the assignments at the top of the script):
artisan mailing-list:sync-script --sh\nOr the following for the API V4 version (and make sure to update the assignments at the top of the script):
artisan mailing-list:sync-script\nThis generates a script which performs each of the above four steps for each configured mailing list. If your mailing list configuration does not change, you will not need to rerun this.
You should now put this script into crontab on the appropriate server (same server for CLI!) and run as often as you feel is necessary. The current success message for a user updating their subscriptions says within 12 hours so we'd recommend at least running twice a day.
"},{"location":"features/mailing-lists/#todo","title":"Todo","text":"DEPRECATED and only available in IXP Manager <v4.7.
The CLI version of mailing list management was presented above. If you wish to use the API version, proceed as follows where:
$MyKey is one of your SUPERUSER API keys;https://www.example.com/ixp/ is your IXP Manager web interface;members is an example mailing list handle as defined above in $IXPROOT/config/mailinglists.php.Use the initialisation function for new IXP Manager users (or initial set up of the mailing list feature) which updates IXP Manager with all currently subscribed mailing list members:
/path/to/mailman/bin/list_members members >/tmp/ml-listname1.txt\ncurl -f --data-urlencode addresses@/tmp/ml-listname1.txt \\\n \"https://www.example.com/ixp/apiv1/mailing-list/init/key/$MyKey/list/members\"\nrm /tmp/ml-listname1.txt\nPipe all subscribed users to the add_members Mailman script:
curl -f \"https://www.example.com/ixp/apiv1/mailing-list/get-subscribed/key/$MyKey/list/members\" | \\\n /path/to/mailman/bin/add_members -r - -w n -a n members >/dev/null\nPipe all users who are unsubscribed to the remove_members Mailman script:
curl -f \"https://www.example.com/ixp/apiv1/mailing-list/get-unsubscribed/key/$MyKey/list/members\" | \\\n /path/to/mailman/bin/remove_members -f - -n -N members >/dev/null\nMANRS - Mutually Agreed Norms for Routing Security - is a global initiative, supported by the Internet Society, that provides crucial fixes to reduce the most common routing threats. \ufeff
IXP Manager >=v5.0 rewards networks that have joined the MANRS program by highlighting this on the customer's public and internal pages - for example:
This information is updated daily via the task scheduler. If you want to run it manually, run this Artisan command:
$ php artisan ixp-manager:update-in-manrs -vv\nMANRS membership updated - before/after/missing: 5/5/104\nAs you'll see from the output, it will show you the results. We will provide more tooling within IXP Manager to show this information in time.
"},{"location":"features/member-export/","title":"Member Export","text":"The recommended means of exporting member details from IXP Manager is to use the IX-F Member Export tool. We even provide examples of how to use this to create example tables.
However, you may sometimes require additional flexibility which necessitates rolling your own export templates. This Member Export feature will allow you to do this but it does require some PHP programming ability.
This Member Export feature is modeled after the static content tool and you are advised to read that page also.
This feature first appears in v4.8.0 and replaces the deprecated older way of handling this.
"},{"location":"features/member-export/#overview","title":"Overview","text":"In IXP Manager, there are four types of users as described in the users page. Member export templates can be added which requires a minimum user privilege to access (e.g. priv == 0 would be publicly accessible through to priv == 3 which would require a superadmin).
To create your own member export templte, you should first set up skinning for your installation. Let's assume you called your skin example in the following.
To create a publicly accessible member export page called lonap, you would first create a directory structure in your skin as follows:
cd ${IXPROOT}\nmkdir -p resources/skins/example/content/members/{0,1,2,3}\nwhere the directories 0, 1, 2, 3 represent the minimum required user privilege to access the template. You can now create your export template page by creating a file:
resources/skins/example/content/members/0/lonap.foil.php\nand then edit that page. In fact, we have bundled three examples in the following locations:
resources/skins/example/content/members/3/lonap.foil.php: a table that replicates how LONAP have traditionally listed their members (see here). It would be accessed via: https://ixp.example.com/content/members/3/lonapresources/skins/example/content/members/3/json-example.foil.php: a JSON example of the above. The HTTP response content type is set to JSON with .json is added to the URL. However you have to ensure your template outputs JSON also. This would be accessed via: https://ixp.example.com/content/members/3/json-example.jsonresources/skins/inex/content/members/0/list.foil.php: what we at INEX use to generate this members list. You can access the real data via: https://www.inex.ie/ixp/content/members/0/list.json (not that this is publicly accessible).The format of the URL to access these member export templates is:
https://ixp.example.com/content/members/{priv}/{page}[.json]\n{priv} is the minimum required user privilege required to access the page and is used first for testing the user's permissions and second as the directory to check for the file.{page} is the name of the file to load (less .foil.php) and please be aware that this is normalised as follows: preg_replace( '/[^a-z0-9\\-_]/', '', strtolower( $page ) )\n[a-z0-9\\-_] and all lower case.[.json] is an optional extension which tells IXP Manager to set the Content-Type: application/json header in the response.At INEX we use Nagios to monitor a number of production services including:
IXP Manager can generate configuration to monitor the above for you.
NB: IXP Manager will not install and configure Nagios from scratch. You need a working Nagios installation first and then IXP Manager will automate the above areas of the configuration.
"},{"location":"features/nagios/#historical-notes","title":"Historical Notes","text":"If you have used Nagios on IXP Manager <4.5, then how the configuration is generated has changed. The older documentation may be available here. In previous versions of IXP Manager, we generated entire / monolithic Nagios configuration files. We have found in practice that this does not scale well and creates a number of limitations.
IXP Manager >= v4.5 now simply creates the targets on a per VLAN and protocol basis.
"},{"location":"features/nagios/#sample-scripts","title":"Sample Scripts","text":"You will find sample scripts for pulling Nagios configuration from IXP Manager and reloading Nagios at:
https://github.com/inex/IXP-Manager/tree/master/tools/runtime/nagios
"},{"location":"features/nagios/#monitoring-member-reachability","title":"Monitoring Member Reachability","text":"We monitor all member router interfaces (unless asked not to) via ICMP[v6] pings with Nagios. This is all controlled by the Nagios configuration created with this feature.
To enable / disable these checks, edit the VLAN interface configuration and set IPvX Can Ping appropriately. Note that when IPvX Can Ping is disabled, the host definition is created anyway as this would be used for other Nagios checks such as route collector sessions.
There is an additional option when editing a member's VLAN interface called Busy Host. This changes the Nagios ping fidelity from 250.0,20%!500.0,60% to 1000.0,80%!2000.0,90% (using the default object definitions which are configurable). This is useful for routers with slow / rate limited control planes.
Members are added to a number of hostgroups also:
These hostgroups are very useful to single out issues and for post-maintenance checks.
You can use the IXP Manager API to get the Nagios configuration for a given VLAN and protocol using the following endpoint format (both GET and POST requests work):
https://ixp.example.com/api/v4/nagios/customers/{vlanid}/{protocol}\nwhere:
vlanid is the database ID (DB ID) of the VLAN. You can find the DB ID in IXP Manager in the VLAN table (select VLANs from the left hand side menu).protocol is either 4 for IPv4 or 6 for IPv6.If either of these are invalid, the API will return with a HTTP 404 response.
And example of a target in the response is:
###############################################################################################\n###\n### Packet Clearing House DNS\n###\n### Equinix DB2 (Kilcarbery) / Packet Clearing House DNS / swi1-kcp1-1.\n###\n\n### Host: 185.6.36.60 / inex.woodynet.net / Peering VLAN #1.\n\ndefine host {\n use ixp-manager-member-host\n host_name packet-clearing-house-dns-as42-ipv4-vlanid2-vliid109\n alias Packet Clearing House DNS / swi1-kcp1-1 / Peering VLAN #1.\n address 185.6.36.60\n}\n\n### Service: 185.6.36.60 / inex.woodynet.net / Peering VLAN #1.\n\ndefine service {\n use ixp-manager-member-ping-service\n host_name packet-clearing-house-dns-as42-ipv4-vlanid2-vliid109\n}\nYou will notice that the above configuration example is very light and is missing an awful lot of Nagios required configuration directives. This is intentional so that IXP Manager is not too prescriptive and allows you to define your own Nagios objects without having to resort to skinning IXP Manager.
Two of the most important elements of Nagios configuration which you need to understand are object definitions and object inheritance.
You can pass three optional parameters to Nagios via GET/POST and these are:
host_definition; defaults to: ixp-manager-member-host.service_definition; defaults to ixp-manager-member-service.ping_service_definition; defaults to: ixp-manager-member-ping-service.ping_busy_service_definition; defaults to: ixp-manager-member-ping-busy-service.An example of changing two of these parameters is:
curl --data \"host_definition=my-host-def&service_definition=my-service-def\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/nagios/customers/2/4\nAn example of the three objects that INEX use for this are:
define host {\n name ixp-manager-member-host\n check_command check-host-alive\n check_period 24x7\n max_check_attempts 10\n notification_interval 120\n notification_period 24x7\n notification_options d,u,r\n contact_groups admins\n register 0\n}\n\ndefine service {\n name ixp-manager-member-service\n check_period 24x7\n max_check_attempts 10\n check_interval 5\n retry_check_interval 1\n contact_groups admins\n notification_interval 120\n notification_period 24x7\n notification_options w,u,c,r\n register 0\n}\n\ndefine service {\n name ixp-manager-member-ping-service\n use ixp-manager-member-service\n service_description PING\n check_command check_ping!250.0,20%!500.0,60%\n register 0\n}\n\ndefine service {\n name ixp-manager-member-ping-busy-service\n use ixp-manager-member-service\n service_description PING-Busy\n check_command check_ping!1000.0,80%!2000.0,90%\n register 0\n}\nYou can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called mytemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/nagios/customers\ncp resources/views/api/v4/nagios/customers/default.foil.php resources/skins/myskin/api/v4/nagios/customers/mytemplate1.foil.php\nYou can now edit this template as required. The only constraint on the template name is it can only contain characters from the classes a-z, 0-9, -. NB: do not use uppercase characters.
You can then elect to use this template by tacking the name onto the API request:
https://ixp.example.com/api/v4/nagios/customers/{vlanid}/{protocol}/{template}\nwhere, in this example, {template} would be: mytemplate1.
As a policy, INEX tends to use the bundled templates and as such they should be fit for general purpose.
"},{"location":"features/nagios/#switch-monitoring","title":"Switch Monitoring","text":"We monitor all production peering LAN switches for a number of difference services (see below).
IXP Manager produces a host configuration for each production switch such as:
#\n# swi2-dc1-1 - DUB01.XX.YY.ZZ, Data Centre DUB1.\n#\n\ndefine host {\n use ixp-manager-production-switch\n host_name swi2-dc1-1.mgmt.inex.ie\n alias swi2-dc1-1\n address 192.0.2.4\n _DBID 74\n}\nMembers are added to a number of hostgroups also:
These hostgroups are very useful when defining service checks.
You can use the IXP Manager API to get the Nagios configuration for a given infrastructure using the following endpoint format (both GET and POST requests work):
https://ixp.example.com/api/v4/nagios/switches/{infraid}\nwhere:
infraid is the database ID (DB ID) of the infrastructure. You can find the DB ID in IXP Manager in the infrastructures table (select Infrastructures from the left hand side menu).You can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called myswtemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/nagios/switches\ncp resources/views/api/v4/nagios/switches/default.foil.php resources/skins/myskin/api/v4/nagios/switches/myswtemplate1.foil.php\nYou can then elect to use this template by tacking the name onto the API request:
https://ixp.example.com/api/v4/nagios/switches/{infraid}/{template}\nwhere, in this example, {template} would be: myswtemplate1.
You can pass one optional parameter to Nagios via GET/POST which is the host definition to inherit from (see customer reachability testing about for full details and examples):
curl --data \"host_definition=my-sw-host-def\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/nagios/switches/2\nThe recommended way to check various services on your production switches is to use the host groups created by the above switch API call. An example of the hostgroups produced include:
ixp-production-switches-infraid-2: all switches on an infrastructure with DB ID 2;ixp-switches-infraid-2-dc-dub1: all switches in location dc-dub1;ixp-switches-infraid-2-extreme: all Extreme switches on an infrastructure with DB ID 2; andixp-switches-infraid-2-extreme-x670g2-48x-4q: all Extreme switches of model X670G2-48x-4q on an infrastructure with DB ID 2.Using these, you can create generic service definitions to apply to all hosts such as:
define service{\n use my-ixp-production-switch-service\n hostgroup_name ixp-production-switches-infraid-1, ixp-production-switches-infraid-2\n service_description ping - IPv4\n check_command check_ping_ipv4!10!100.0,10%!200.0,20%\n}\n\ndefine service {\n use my-ixp-production-switch-service\n hostgroup_name ixp-production-switches-infraid-1, ixp-production-switches-infraid-2\n service_description SSH\n check_command check_ssh\n}\nYou can target vendor / model specific checks as appropriate:
define service{\n use my-ixp-production-switch-service\n hostgroup_name ixp-switches-infraid-1-extreme, ixp-switches-infraid-2-extreme\n service_description Chassis\n check_command check_extreme_chassis\n}\nThe one thing you'll need to keep an eye on is adding hostgroups to service checks as you create new infrastructures / add new switch vendors / models.
Hint: over the years, we at INEX have written a number of switch chassis check scripts and these can be found on Github at barryo/nagios-plugins.
For example the Extreme version checks and returns something like:
OK - CPU: 5sec - 10%. Uptime: 62.8 days. PSUs: 1 - presentOK: 2 - presentOK:. Overall system power state: redundant power available. Fans: [101 - OK (4311 RPM)]: [102 - OK (9273 RPM)]: [103 - OK (4468 RPM)]: [104 - OK (9637 RPM)]: [105 - OK (4165 RPM)]: [106 - OK (9273 RPM)]:. Temp: 34'C. Memory (slot:usage%): 1:29%.
"},{"location":"features/nagios/#birdseye-daemon-monitoring","title":"Birdseye Daemon Monitoring","text":"We monitor our Bird instances at INEX directly through Birdseye, the software we use for our looking glass. This means it is currently tightly coupled to Bird and Birdseye until such time as we look at a second router software.
IXP Manager produces a host and service configuration for each router such as:
define host {\n use ixp-manager-host-birdseye-daemon\n host_name bird-rc1q-cork-ipv4\n alias INEX Cork - Quarantine Route Collector - IPv4\n address 10.40.5.134\n _api_url http://rc1q-ipv4.cork.inex.ie/api\n}\n\ndefine service {\n use ixp-manager-service-birdseye-daemon\n host_name bird-rc1q-cork-ipv4\n}\nYou can use the IXP Manager API to get the Nagios configuration for all or a given VLAN using the following endpoint format (both GET and POST requests work):
https://ixp.example.com/api/v4/nagios/birdseye-daemons\nhttps://ixp.example.com/api/v4/nagios/birdseye-daemons/{template}\nhttps://ixp.example.com/api/v4/nagios/birdseye-daemons/default/{vlanid}\nhttps://ixp.example.com/api/v4/nagios/birdseye-daemons/{template}/{vlanid}\nwhere:
{template} is the optional skin (see below).{vlanid} is the VLAN id to limit the results to. If setting this, you need to provide a template also (or default for the standard template).You can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called mybetemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/nagios/birdseye-daemons\ncp resources/views/api/v4/nagios/birdseye-daemons/default.foil.php resources/skins/myskin/api/v4/nagios/birdseye-daemons/mybetemplate1.foil.php\nYou can then elect to use this template by tacking the name onto the API request:
https://ixp.example.com/api/v4/nagios/birdseye-daemons/{template}\nwhere, in this example, {template} would be: mybetemplate1.
You can pass two optional parameter to Nagios via GET/POST which is the host and service definition to inherit from (see customer reachability testing about for full details and examples):
curl --data \"host_definition=my-be-host-def&service_definition=my-be-srv-def\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/nagios/birdseye-daemons\nThe default values for the host and service definitions are ixp-manager-host-birdseye-daemon and ixp-manager-service-birdseye-daemon respectively.
You will need to create a parent host and service definition for the generated configuration such as:
define host {\n name ixp-manager-host-birdseye-daemon\n check_command check-host-alive\n check_period 24x7\n max_check_attempts 10\n notification_interval 120\n notification_period 24x7\n notification_options d,u,r\n contact_groups admins\n register 0\n}\n\ndefine service {\n name ixp-manager-service-birdseye-daemon\n service_description Bird BGP Service\n check_command check_birdseye_daemon!$_HOSTAPIURL$\n check_period 24x7\n max_check_attempts 10\n check_interval 5\n retry_check_interval 1\n contact_groups admins\n notification_interval 120\n notification_period 24x7\n notification_options w,u,c,r\n register 0\n}\n\ndefine command{\n command_name check_birdseye_daemon\n command_line /usr/local/nagios-plugins-other/nagios-check-birdseye.php -a $ARG1$\n}\nThe Nagios script we use is bundled with inex/birdseye and can be found here.
Typical Nagios state output:
OK: Bird 1.6.2. Bird's Eye 1.0.4. Router ID 192.0.2.126. Uptime: 235 days. Last Reconfigure: 2017-07-17 16:00:04.26 BGP sessions up of 28.
"},{"location":"features/nagios/#birdseye-bgp-session-monitoring","title":"Birdseye BGP Session Monitoring","text":"We monitor our Bird route collector, route server and AS112 Bird BGP sessions at INEX directly through Birdseye, the software we use for our looking glass. This means it is currently tightly coupled to Bird and Birdseye until such time as we look at a second router software.
IXP Manager produces a host and service configuration for each router type such as:
### Router: INEX LAN1 - Route Collector - IPv4 / 192.0.2.126.\n\ndefine service {\n use ixp-manager-member-bgp-session-service\n host_name as112-reverse-dns-as112-ipv4-vlanid2-vliid99\n service_description BGP session to rc1-lan1-ipv4 (INEX LAN1 - Route Collector - IPv4)\n _api_url http://www.example.com/api\n _protocol pb_0099_as112\n}\nThe configuration also includes hostgroups for the given VLAN, protocol and type for:
You can use the IXP Manager API to get the Nagios configuration for a given protocol, VLAN and router type using the following templates:
https://ixp.example.com/api/v4/nagios/birdseye-bgp-sessions/{vlanid}/{protocol}/{type}\nhttps://ixp.example.com/api/v4/nagios/birdseye-bgp-sessions/{vlanid}/{protocol}/{type}/{template}\nwhere:
{vlanid} is the VLAN id to generate the configuration for.{protocol} is either 4 (ipv4) or 6 (ipv6).{type} is one of (these are defined in Entities\\Router):1 for route servers;2 for route collectors;3 for AS112You can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called myrstemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/nagios/birdseye-bgp-sessions\ncp resources/views/api/v4/nagios/birdseye-bgp-sessions/default.foil.php resources/skins/myskin/api/v4/nagios/birdseye-bgp-sessions/myrstemplate1.foil.php\nYou can then elect to use this template by tacking the name onto the API request:
https://ixp.example.com/api/v4/nagios/birdseye-bgp-sessions/{vlanid}/{protocol}/{type}/{template}\nwhere, in this example, {template} would be: myrstemplate1.
You can pass one optional parameter to Nagios via GET/POST which is the service definition to inherit from (see customer reachability testing about for full details and examples):
curl --data \"service_definition=my-rs-srv-def\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/nagios/birdseye-bgpsessions/2/4/1\nThe default values for the service definition is ixp-manager-member-bgp-session-service respectively.
You will need to create a parent service definition and a check command for the generated configuration such as:
define service {\n name ixp-manager-member-bgp-session-service\n service_description Member Bird BGP Sessions\n check_period 24x7\n max_check_attempts 10\n check_interval 5\n retry_check_interval 1\n contact_groups admins\n notification_interval 120\n notification_period 24x7\n notification_options w,u,c,r\n register 0\n check_command check_birdseye_bgp_session!$_SERVICEAPI_URL!$_SERVICEPROTOCOL\n}\n\ndefine command{\n command_name check_birdseye_bgp_session\n command_line /path/to/nagios-check-birdseye-bgp-sessions.php -a $ARG1$ -p $ARG2$ -n\n}\nThe Nagios script we use is bundled with inex/birdseye and can be found here.
"},{"location":"features/patch-panels/","title":"Patch Panels / Cross Connects","text":"One of the more difficult things for an IXP to manage is the sheer volume of patch panels / cross connects they need to manage. We have approached the issue a number of times in IXP Manager but abandoned the attempt every time. Typically our original solutions were over-engineered where all we really needed was something which could replace a spreadsheet per panel.
We believe we have now developed a feature complete and useful means of managing patch panels and associated cross connects.
"},{"location":"features/patch-panels/#features","title":"Features","text":"We suggest adding fibre ports as two ports per duplex port. I.e. if your patch panel has 12 duplex ports, enter this as 24 ports. When allocating ports later, you can set it as a duplex port and select its partner / slave port. This will future proof your patch panels for the growing use of bidi optics and other simplex based xWDM fibre solutions.
From our experience, duplex fibre ports are often identified as their individual strands. For example, duplex port 5 would be referenced as F9/F10.
Your mileage may vary on this but we need to allow this flexibility to cover both use-cases. You always have options however:
The following image shows a typical add a new patch panel form (as of v4.3). You'll note that clicking Help provides detailed context aware help messages.
Most of this is self-explanatory but:
In addition to that, we will also use a cabinets U's are counted from top/bottom, and a patch panel's U position and mounted at front/rear to also create a location description. * When setting the Number of Ports, ensure you count duplex fibre ports as two ports. So 12 duplex fibre ports would be entered as 24. When editing a patch panel, this input field represents the number of additional ports you want to add to a patch panel and thus defaults to 0 in that situation. * Port Name Prefix: This is an optional field intended for use on fibre patch panels. As an example, you may wish to prefix individual fibre strands in a duplex port with F which would mean the name of a duplex port would be displayed as F1/F2. * Chargeable: Usually IXPs request their members to come to them and bear the costs of that. However, sometimes a co-location facility may charge the IXP for a half circuit or the IXP may need order and pay for the connection. Setting this only sets the default option when allocating ports to members later. The options are Yes / No / Half / Other.
"},{"location":"features/patch-panels/#filtering-patch-panel-ports","title":"Filtering Patch Panel Ports","text":"Quite often, all you are looking for is a free in a particular location (data centre) or cabinet of a particular cable type (UTP / SMF / etc.).
IXP Manager makes this easy from the Patch Panels page via the top right button labeled Filter Options. When clicked, this yields an advanced search as follows:
Cabinets auto-fills when you chose (or change) a location.
"},{"location":"features/patch-panels/#patch-panel-port-states","title":"Patch Panel Port States","text":"A patch panel port can have the following states:
IXP Manager will colour ports in the Available, Prewired and Awaiting Cease states are green allowing an easy visual indication of available ports.
"},{"location":"features/patch-panels/#patch-panel-port-lifecycle","title":"Patch Panel Port Lifecycle","text":"Patch panel ports start as either available or prewired. The context menu in these states is:
The main lifecycle option here is Allocate:
Description: A one line short description to be shown in the list of patch panel ports. Just enough to help explain the ports purpose. Detailed information should be placed in the notes section. Can also be used to explain a reserved / broken / other port. Note that this is parsed as Markdown. NB: A description is discouraged for customer ports connected to a switch. The customer name and switch port are the description.
Colocation Circuit Reference: this is the reference provided by the colocation provider to uniquely reference this cross connect.
Ticket Reference(s): This is a free text field to be used by IXPs as they wish. The intended use is to enter helpdesk ticket references that relate to this cross connect order.
Duplex connection?: Clicking this allows you to select the slave port for duplex connections.
Switch / Switch Port / Customer: You have a number of options when allocating a port:
If the port is pre-wired then the switch / switch port will be set here.
If you need to reset these fields, just click either of the Reset button.
Patch Panel Port Status: when allocating a port, this will allow you to set the state to Awaiting Xconnect or Connected.
Physical Interface Status: this is not depicted above. If the selected switch port has already been assigned to a customer by way of a physical interface, you will have the option to update this here also.
Public and Private Notes: Public notes are available to the customer. Both fields are interpreted as Markdown.
Chargeable: Usually IXPs request their members to come to them and bear the costs of that. However, sometimes a co-location facility may charge the IXP for a half circuit or the IXP may need order and pay for the connection. The options are Yes / No / Half / Other. How individual IXPs use this is up to them.
Internal Use: Marks the port as used by the IXP itself. E.g. metro connections.
Owned By: Useful indication for billing and cease requests. Should represent the contractural owner of the cross connect. One of: Customer, IXP, Service Provider, Data Centre, Other. Service Provider might be a metro provider where they ordered the cross connect.
Once a port is allocated, it enters the Awaiting XConnect / Connected state and there are additional context menu options available:
The three lifecycle actions are:
Over the lifetime of a cross connect - and particularly when it is being ordered, there may be files exchanges between you and your customers or the colocation provider. These can be added to the patch panel port via the Attach File... option.
The dialog will dynamically determine the maximum file upload size based on your PHP settings. To alter this, change the following in your server's appropriate php.ini:
; Maximum allowed size for uploaded files.\nupload_max_filesize = 40M\n\n; Must be greater than or equal to upload_max_filesize\npost_max_size = 40M\nPlease search the internet for further help as this is outside the scope of IXP Manager documentation.
The following features apply to file attachments:
$IXPROOT/storage/files/ppp.Many co-location providers will not accept a cross connect order without a LoA (Letter of Agency/Authority) from the party to whom the cross connect is to be delivered (typically the IXP).
IXP Manager will generate a PDF LoA to download or include in the emails it generates for you. Here is an example:
You will need to skin this yourself to change the legalese, address and contact details and potentially add a logo. See the version INEX uses here (which includes and embedded PNG logo).
Note that Dompdf is used to turn the HTML template into a PDF and it has some restrictions.
You have two options for generating LoAs (without having IXP Manager email them):
The stock LoA template (and INEX's version) includes a link that allows co-location browsers to click on to verify its veracity.
On successful verification, the end user sees:
"},{"location":"features/patch-panels/#email-generation","title":"Email Generation","text":"IXP Manager allows you to send four emails related to patch panels / cross connects (port status dependent). These are listed below. The Email editor looks as follows:
Note that:
The four email templates available are:
All email templates can be skinned for your own needs. See INEX's example skins here.
"},{"location":"features/patch-panels/#viewing-patch-panel-details-and-archives","title":"Viewing Patch Panel Details and Archives","text":"Each patch panel port row has the following button:
The number in the badge indicates how many historical records are available.
Clicking on the button yields the following view screen:
"},{"location":"features/patch-panels/#development-history","title":"Development History","text":"The Patch Panels functionality was developed during Q1 2017 and added in March 2017. This was made possible from sponsorship which enabled us to hire a new full time developer. We are especially grateful to our sponsors - please see them here.
"},{"location":"features/peering-manager/","title":"Peering Manager","text":"The Peering Manager is a fantastic tool that allows your members to view and track their peerings with other IXP members. The display is broken into four tabs for each member:
The mechanism for detecting bilateral peers is by by observing established TCP sessions between member peering IP addresses on port 179 using [sflow](sflow.md]. See the peering matrix documentation as setting up the peering matrix will provide all the data needed for the peering manager.
NB: You must check the Peering Manager option when editing VLANs for that VLAN to be included in the peering manager.
The features of the peering manager include:
This feature requires some settings in your .env which you may have already set:
;; the various identity settings\nIDENTITY_...\n\n;; the default VLAN's database ID (get this from the DB ID column in VLANs)\nIDENTITY_DEFAULT_VLAN=1\nThe default peering request email template can be found at resources/views/peering-manager/peering-message.foil.php. You can skin this if you wish but it is generic enough to use as is.
You can disable the peering manager by setting the following in .env:
IXP_FE_FRONTEND_DISABLED_PEERING_MANAGER=true\nFor testing / experimentation purposes, you can enable a test mode which, when enabled, will send all peering requests to the defined test email.
To enable test mode, just set the following in .env:
PEERING_MANAGER_TESTMODE=true\nPEERING_MANAGER_TESTEMAIL=user@example.com\nWhen test mode is enabled, there will be a clear alert displayed at the top of the peering manager page.
Normally, the peering manager adds a note to the peer's notes and sets a request last sent date when a peering request is sent. In test mode, this will not happen. If you want this to happen in test mode, set these to true:
PEERING_MANAGER_TESTNOTE=true\nPEERING_MANAGER_TESTDATE=true\nThe peering matrix system builds up a list of who is peering with whom over your IXP.
There are two primary data sources: route server clients and sflow. Currently, it is assumed that all IXP participants who connect to the route server have an open peering policy and do not filter prefixes.
NB: You must check the Peering Matrix option when editing VLANs for that VLAN to be included in the peering matrix on the frontend.
"},{"location":"features/peering-matrix/#data-source-route-server-clients","title":"Data Source: Route Server Clients","text":"Route server clients are automatically shown as peering with each other onm the peering matrix. No operator input is required for this.
"},{"location":"features/peering-matrix/#data-source-sflow-bgp-session-detection","title":"Data Source: sflow BGP session detection","text":"IXP Manager can pick out active BGP sessions from an sflow data feed. This is handled using the sflow-detect-ixp-bgp-sessions script. As this is a perl script, it is necessary to install all the perl modules listed in the check-perl-dependencies.pl script.
Sflow is a packet sampling mechanism, which means that it will take some while before the peering database is populated. After 24 hours of operation, the peering database should be relatively complete.
sflow-detect-ixp-bgp-sessions needs its own dedicated sflow data feed, so it is necessary to set up sflow data fan-out using the sflowtool as described in the sflow fan-out section here. INEX normally uses udp port 5501 for its bgp detection sflow feed.
For more information, see the sflow documentation.
Note that the peering matrix functionality depends on SQL triggers which are maintained in the tools/sql/views.sql file. This can be refreshed using the following command:
```sh\nmysql -u ixp -p ixp < $IXPROOT/tools/sql/views.sql\n```\nIn addition to the correct SQL configuration for the <sql> section, sflow-detect-ixp-bgp-sessions needs the following options set in the <ixp> section of ixpmanager.conf:
sflowtool: the location of the sflowtool binary.sflowtool_bgp_opts: command line arguments for sflowtool.<ixp>\n # location of sflow executable\n sflowtool = /usr/local/bin/sflowtool\n\n # sflow listener to p2p rrd exporter, listening on udp port 5500\n sflowtool_opts = -4 -p 5500 -l\n\n # sflow listener for BGP peering matrix, listening on udp port 5501\n sflowtool_bgp_opts = -4 -p 5501 -l\n</ixp>\nThe system can be tested using sflow-detect-ixp-bgp-sessions --debug. If it starts up correctly, the script should occasionally print out peering sessions like this:
DEBUG: [2001:db8::ff]:64979 - [2001:db8::7]:179 tcpflags 000010000: ack. database updated.\nDEBUG: [192.0.2.126]:30502 - [192.0.2.44]:179 tcpflags 000010000: ack. database updated.\nDEBUG: [2001:db8::5:0:1]:179 - [2001:db8::4:0:2]:32952 tcpflags 000011000: ack psh. database updated.\nThe script control-sflow-detect-ixp-bgp-sessions should be copied (and edited if necessary) to the operating system startup directory so that sflow-detect-ixp-bgp-sessions is started as a normal daemon.
The peering matrix is publicly available by default. However you can limit access to a minimum user privilege by setting PEERING_MATRIX_MIN_AUTH to an integer from 0 to 3 in your .env. See here for what these integers mean. For example, to limit access to any logged in user, set the following:
PEERING_MATRIX_MIN_AUTH=1\nYou can disable the peering matrix by setting the following in .env:
IXP_FE_FRONTEND_DISABLED_PEERING_MATRIX=true\nThis probably means that it's not getting an sflow feed. Check to ensure that sflowtool is feeding the script correctly by using the sflow-detect-ixp-bgp-sessions --insanedebug. This should print out what the script is reading from sflowtool. Under normal circumstances, this will be very noisy.
ignored - no address match in database when in debug modeIf the IP addresses match those on the IXP's peering LAN, then the IP address database is not populated correctly. This can be fixed by entering the IXP's addresses in the IP Addressing menu of the web UI.
Check that the tools/sql/views.sql file has been imported into the SQL database.
IXP Manager can authenticate users via their PeeringDB account and affiliations (from V5.2.0). This is hugely beneficial for your customers who are members of multiple IXPs which use IXP Manager - it means they only need their PeeringDB account to access their portal at each of those IXs.
NB: this feature is not set up by default as it requires some configuration on both PeeringDB and your IXP Manager installation.
"},{"location":"features/peeringdb-oauth/#security","title":"Security","text":"Is there a security risk?
Well, we at INEX do not think so and we have developed and enabled this feature for our members.
By enabling PeeringDB OAuth, you are creating a path that delegates authentication and authorization of users on your platform to PeeringDB. This is not a decision that was rushed into. It is particularly notable that PeeringDB is the industry-standard database for network operators and the PeeringDB team take the job of assessing whether someone should be affiliated with a network seriously.
We at INEX also discussed this functionality with a wide variety of people in our industry and the opinion was overwhelmingly in favor with no known dissenters.
Lastly, we have developed this in a security-conscious way. New users get read-only access by default. All information from PeeringDB is validated and a number of other confirmatory steps are taken. You can read all about this in the OAuth User Creation section below.
"},{"location":"features/peeringdb-oauth/#configuring-peeringdb-for-oauth","title":"Configuring PeeringDB for OAuth","text":"There are two steps to configuring OAuth for PeeringDB - first set it up on PeeringDB and then, using the tokens generated there, configure IXP Manager.
"},{"location":"features/peeringdb-oauth/#configuring-peeringdb","title":"Configuring PeeringDB","text":"The first step is to create your IXP Manager OAuth application through your PeeringDB account:
/auth/login/peeringdb/callback action on your IXP Manager installation. For example, if the base URL of your IXP Manager installation is https://www.example.com then set redirect URL to https://www.example.com/auth/login/peeringdb/callback. Note that for OAuth, it is mandatory to use https:// (encryption).Here is a sample form on PeeringDB:
"},{"location":"features/peeringdb-oauth/#configuring-ixp-manager","title":"Configuring IXP Manager","text":"To enable OAuth with PeeringDB on IXP Manager, set the following options in your .env file:
AUTH_PEERINGDB_ENABLED=true\n\nPEERINGDB_OAUTH_CLIENT_ID=\"xxx\"\nPEERINGDB_OAUTH_CLIENT_SECRET=\"xxx\"\nPEERINGDB_OAUTH_REDIRECT=\"https://www.example.com/auth/login/peeringdb/callback\"\nwhile replacing the configuration values for the those from the PeeringDB set-up above.
Once this is complete, you'll find a new option on IXP Manager's login form:
By default, new users are created on IXP Manager as read-only customer users. You can change this to read-write customer admin users by additionally setting the following option:
AUTH_PEERINGDB_PRIVS=2\nIf PeeringDB OAuth is configured and enabled (AUTH_PEERINGDB_ENABLED=true) then it is enabled for all customers. However you may encounter a customer who does not want OAuth access enabled on their account. In this situation, IXP Manager allows you to disabled OAuth on a per-customer basis when adding or editing customers.
Just uncheck the following option on the add / edit customer page:
"},{"location":"features/peeringdb-oauth/#oauth-user-creation","title":"OAuth User Creation","text":"When IXP Manager receives an OAuth login request from PeeringDB, it goes through a number of validation, creation and deletion steps:
unknownpdbuser) using s/[^a-z0-9\\._\\-]/./ with an incrementing integer concatenated as necessary for uniqueness.user.peeringdb_id set to PeeringDB's user ID.user.creator set to OAuth-PeeringDB.If AUTH_PEERINGDB_ENABLED is enabled in your .env, you will see a column called OAuth in the Users list table (accessed via the left hand side menu). This will indicate if the user was created by OAuth (Y) or not (N).
When viewing a user's details (eye button on the users list), it will show how the user was created and also how the user was affiliated with a particular customer. The same is also shown when editing users.
"},{"location":"features/peeringdb-oauth/#historical-notes","title":"Historical Notes","text":"PeeringDB OAuth with IXP Manager as an idea dates from early 2017 when Job Snijders proposed it in GitHub issue peeringdb/peeringdb#131. We recognized the benefits immediately and opened a parallel ticket at inex/IXP-Manager#322. The background discussions at this point were that PeeringDB would be prepared to invest developer time if IXP Manager committed to implementing it. We both did.
PeeringDB's OAuth documentation can be found here.
As part of the development process, we wrote a provider for the Laravel Socialite package which was merged into that package via the SocialiteProviders/Providers#310 pull request.
"},{"location":"features/peeringdb-oauth/#development-notes","title":"Development Notes","text":"Testing in development needs to be setup following the instructions above. While PeeringDB has a beta site, the actual OAuth URL is hard coded into Socialite. You can test against production or edit the two URLs in this file: data/SocialiteProviders/src/PeeringDB/Provider.php.
For local testing, you'll need both SSL and a way for PeeringDB to redirect back to you. valet share from Laravel Valet is perfect for this.
PeeringDB is a freely available, user-maintained, database of networks and interconnection data. The database facilitates the global interconnection of networks at Internet Exchange Points (IXPs), data centers, and other interconnection facilities. The database is a non-profit, community-driven initiative run and promoted by volunteers. It is a public tool for the growth and good of the internet.
IXP Manager uses PeeringDB in a number of current (and planned) ways.
"},{"location":"features/peeringdb/#oauth-user-authentication","title":"OAuth - User Authentication","text":"IXP Manager can authenticate users via their PeeringDB account and affiliations. Please see this page for full details and instructions.
"},{"location":"features/peeringdb/#population-of-data-when-adding-customers","title":"Population of Data When Adding Customers","text":"Much of the information required to add new customers to IXP Manager can be prepopulated from PeeringDB by entering the customer's ASN into the box provided on the add customer page:
For maximum benefit, you should configure a user on PeeringDB for your IXP Manager installation and set these details in the .env file:
#######################################################################################\n# PeeringDB Authentication\n#\n# PeeringDb's API is used, for example, to pre-populate new customer details. If you\n# provide a working PeeringDb username/password then these will be used to get more\n# complete information.\n#\nIXP_API_PEERING_DB_USERNAME=username\nIXP_API_PEERING_DB_PASSWORD=password\nPeeringDB can take data from your IXP Manager installation via the IX-F Export schema that is part of IXP Manager. PeeringDB requires two things for this to work:
First, you need to add your IX-F Export URL to your PeeringDB IX LAN entry:
Secondly, and unfortunately, each individual network must opt in to having their data updated by this mechanism (data meaning connection to the exchange, peering IPs and port speeds). They do this via this option on their network page:
"},{"location":"features/peeringdb/#asn-detail","title":"ASN Detail","text":"In most places in IXP Manager, you can click on an ASN number. This uses PeeringDB's whois service to provide a quick view of that network's PeeringDB record.
Here's a squashed screen shot just to illustrate the feature:
"},{"location":"features/peeringdb/#existence-of-peeringdb-records","title":"Existence of PeeringDB Records","text":"On the customer overview page from IXP Manager v5.0, we provide an indication (yes/no) as to whether a customer has a PeeringDB record. Generally it is important for IXPs to encourage their members to create PeeringDB entries to ensure your IXP is properly represented on their database.
Whether a customer has a PeeringDB entry is updated daily via the task scheduler. If you want to run it manually, run this Artisan command:
$ php artisan ixp-manager:update-in-peeringdb -vv\nPeeringDB membership updated - before/after/missing: 92/92/17\nAs you'll see from the output, it will show you the results. We will provide more tooling within IXP Manager to show this information in time.
"},{"location":"features/peeringdb/#facilities","title":"Facilities","text":"When you add facilities (locations / points of presence / data centers) to IXP Manager, it pulls a list of known facilities from PeeringDB. You should select the correct one from the list (or add a missing one to PeeringDB) when you add/edit your facilities.
Note that this list is cached for two hours.
"},{"location":"features/peeringdb/#infrastructures-and-peeringdb-ixp-entry","title":"Infrastructures and PeeringDB IXP Entry","text":"Similarly to adding facilities above, when you add an infrastructure (IXP) to IXP Manager, it pulls a list of known IXPs from PeeringDB. You should select the correct one from the list (or add a missing one to PeeringDB) when you add/edit your infrastructures.
Note that this list is cached for two hours.
"},{"location":"features/provisioning/","title":"Automated Provisioning","text":""},{"location":"features/provisioning/#introduction","title":"Introduction","text":"At INEX, we have been using IXP Manager for automated provisioning of our peering platform since 2017. We have published all the provisioning templates we use in production here.
InfoYou are welcome to have a look at what's here and contribute feedback via the issues page or the ixpmanager mailing list. Having said that, provisioning is complicated and very specific to individual IXPs. Even if your IXP is running with the same two network operating systems that are in this repo, it is unlikely that people have the resources freely available to be able to make this work for you.
This page has two sections:
The templates INEX has published at the above link provide configuration support for Arista EOS and Cumulus Linux 3.4+/4.0+ devices using SaltStack.
The Arista EOS implementation uses NAPALM and can be easily modified for any other operating system which supports either NAPALM or netmiko.
The Cumulus Linux template implementation uses native SaltStack support, and treats the Cumulus Linux switch like any other Linux device. For an IXP, you need CL >= 3.4.2.
At the bare minimum, in order to make these work, you will need to be completely fluent with NAPALM and advanced use of SaltStack, including how to configure and maintain salt proxies. If you have multiple IXP configurations (e.g. live / test environments), you will also need to be fluent with the idea of multiple salt environments.
A good starting point would be Mircea Ulinic's guides for integrating SaltStack and NAPALM. For a bigger-picture overview about how these templates hang together, we've done some presentations - see the 2017 and 2018 talks on automation on the IXP Manager website.
Note that there is no information in these presentations about the nitty gritty of getting all this stuff to work. The Apricot 2018 presentation involves lots of cheery handwaving and high level overview stuff, but very little detail other than some sample command-lines that we use.
In 2023/4 we hope to design a workshop / tutorial videos on this topic.
"},{"location":"features/provisioning/#api-endpoints","title":"API Endpoints","text":"The API endpoints documented below should provide everything you need to provision all aspects of an IXP fabric.
https://ixp.example.com/). {switchname} should be replaced with the name of your switch as entered in IXP Manager..yaml in the examples but you should be able to replace this with .json also.The INEX sample templates we reference below will get their dynamic information from two sources:
/api/v4/provisioner/switch/switch-name/{$switchname}.yamlSample output:
switch:\n name: swi1-exp1-1\n asn: 65000\n hostname: swi1-exp1-1.mgmt.example.com\n loopback_ip: 192.0.2.1\n loopback_name: Loopback0\n ipv4addr: 192.0.2.100\n model: DCS-7280SR-48C6\n active: true\n os: EOS\n id: 72\n macaddress: 11:22:33:44:55:66\n lastpolled: \"2023-04-21T09:31:11+01:00\"\n osversion: 4.25.4M\n snmpcommunity: supersecret\nAll of this data comes from the switch settings in IXP Manager. The ipv4addr is the management address.
As well as the base configuration shown the the template about, this information could also be used to provision:
/api/v4/provisioner/layer3interfaces/switch-name/{$switchname}.yamlSample output:
layer3interfaces:\n- ipv4: 192.0.2.21/31\n description: 'LAN1: swi1-exp1-3 - swi1-exp1-1'\n bfd: true\n speed: 100000\n name: Ethernet51/1\n autoneg: true\n shutdown: false\n- ipv4: 192.0.2.33/31\n description: 'LAN1: swi1-exp2-3 - swi1-exp1-1'\n bfd: true\n speed: 100000\n name: Ethernet53/1\n autoneg: true\n shutdown: false\n- description: Loopback interface\n loopback: true\n ipv4: 192.0.2.1/32\n name: Loopback0\n shutdown: false\nThis API is used to set up the basic layer3 interface elements that are required in future stages to create a VXLAN overlay. The data comes from two sources on IXP Manager:
/api/v4/provisioner/vlans/switch-name/{$switchname}.yamlSample output:
vlans:\n- name: IXP LAN1\n tag: 10\n private: false\n config_name: vl_peeringlan1\n- name: Quarantine LAN1\n tag: 11\n private: false\n config_name: vl_quarantinelan1\n- name: VoIP Peering LAN1\n tag: 12\n private: false\n config_name: VOIPPeeringLAN1\nThis information comes from the VLAN configuration on IXP Manager. The INEX sample template also configures VXLAN with this information.
"},{"location":"features/provisioning/#layer2-interfaces","title":"Layer2 Interfaces","text":"InfoDespite the template being called cust interfaces, this API endpoint is for both customer interfaces and layer2 core interfaces.
/api/v4/provisioner/layer2interfaces/switch-name/{$switchname}.yamlSample output:
layer2interfaces:\n- type: edge\n description: Sample Member - No LAG\n dot1q: false\n virtualinterfaceid: 26\n lagframing: false\n vlans:\n - number: 10\n macaddresses:\n - 22:33:44:55:66:77\n ipaddresses:\n ipv4: 198.51.100.23\n ipv6: 2001:db8::23\n shutdown: false\n status: connected\n name: \"1:3\"\n speed: 10000\n autoneg: true\n- type: edge\n description: Sample Member - LAG\n dot1q: false\n virtualinterfaceid: 251\n lagframing: true\n lagindex: 3\n vlans:\n - number: 10\n macaddresses:\n - 33:44:55:66:77:88\n ipaddresses:\n ipv4: 198.51.100.108\n ipv6: 2001:db8::108\n name: Port-Channel3\n lagmaster: true\n fastlacp: false\n lagmembers:\n - Ethernet5\n - Ethernet6\n shutdown: false\n status: connected\n- type: edge\n description: Sample Member - LAG\n dot1q: false\n virtualinterfaceid: 251\n lagframing: true\n lagindex: 3\n vlans:\n - number: 10\n macaddresses:\n - 33:44:55:66:77:88\n ipaddresses:\n ipv4: 198.51.100.108\n ipv6: 2001:db8::108\n name: Ethernet5\n lagmaster: false\n fastlacp: false\n shutdown: false\n status: connected\n autoneg: true\n speed: 10000\n rate_limit: ~\n- type: edge\n description: Sample Member - LAG\n dot1q: false\n virtualinterfaceid: 251\n lagframing: true\n lagindex: 3\n vlans:\n - number: 10\n macaddresses:\n - 33:44:55:66:77:88\n ipaddresses:\n ipv4: 198.51.100.108\n ipv6: 2001:db8::108\n name: Ethernet6\n lagmaster: false\n fastlacp: false\n shutdown: false\n status: connected\n autoneg: true\n speed: 10000\n rate_limit: ~\n- type: core\n description: 'LAN1: swi1-exp2-3 to swi1-exp1-1 - Sample Core L2 Link'\n dot1q: true\n stp: false\n cost: ~\n preference: ~\n virtualinterfaceid: 439\n corebundleid: 30\n lagframing: true\n lagindex: 1000\n vlans:\n - number: 10\n macaddresses: []\n - number: 11\n macaddresses: []\n - number: 12\n macaddresses: []\n name: Port-Channel1000\n lagmaster: true\n fastlacp: true\n lagmembers:\n - \"Ethernet48\"\n shutdown: false\n- type: core\n description: 'LAN1: swi1-exp2-3 to swi1-exp1-1 - Sample Core L2 Link'\n dot1q: true\n stp: false\n cost: ~\n preference: ~\n virtualinterfaceid: 439\n corebundleid: 30\n lagframing: true\n lagindex: 1000\n vlans:\n - number: 10\n macaddresses: []\n - number: 11\n macaddresses: []\n - number: 12\n macaddresses: []\n name: \"Ethernet48\"\n lagmaster: false\n fastlacp: true\n shutdown: false\n autoneg: true\n speed: 40000\nThe data comes from two sources on IXP Manager:
/api/v4/provisioner/routing/switch-name/{$switchname}.yamlSample output:
bgp:\n floodlist:\n - 192.0.2.2\n - 192.0.2.12\n - 192.0.2.10\n - 192.0.2.11\n - 192.0.2.40\n - 192.0.2.20\n - 192.0.2.0\n - 192.0.2.60\n - 192.0.2.22\n - 192.0.2.82\n - 192.0.2.23\n - 192.0.2.42\n - 192.0.2.15\n - 192.0.2.16\n - 192.0.2.17\n - 192.0.2.18\n adjacentasns:\n 65082:\n description: swi1-exp1-3\n asn: 65082\n cost: 100\n preference: ~\n 65002:\n description: swi1-exp2-3\n asn: 65002\n cost: 850\n preference: ~\n routerid: 192.0.2.1\n local_as: 65000\n out:\n pg-ebgp-ipv4-ixp:\n neighbors:\n 192.0.2.120:\n description: swi1-exp1-3\n remote_as: 65082\n cost: 100\n preference: ~\n 192.0.2.132:\n description: swi1-exp2-3\n remote_as: 65002\n cost: 850\n preference: ~\nThis completes the layer2 underlay for VXLAN. The sources of information for this are the switches and core bundles in IXP Manager.
"},{"location":"features/reseller/","title":"Reseller Functionality","text":"Reseller mode must be explicitly enabled with a .env option:
IXP_RESELLER_ENABLED=true\nIn our model, a resold member is still a fully fledged member, they just happen to reach the exchange via someone else's network. You / we would still have a relationship with the member independent of the reseller and would still be required to carry out the standard turn up (for us, this includes IP assignment, quarantine procedures, route collector session, route server sessions if appropriate, etc.).
IXP Manager's functionality is simply to:
For resellers, we need to enforce the one port - one mac - one address rule on the peering LAN.
Depending on switch technology, this can be done using
Currently the schema cannot adequately handle a virtual ethernet port.
Typically, we'd assign a dedicated switch (or bunch of switch ports) as a fanout switch with a reseller uplink port (or LAG). The reseller delivers their customer traffic in dedicated VLANs over this uplink port. We then break each individual customer's traffic into dedicated fanout ports. These physical fanout ports have a one to one relationship with peering ports for that customer (these can be single physical ports or LAGs).
The reseller functionality includes:
The following are set in .env:
To enable reseller functionality, set the following to true:
IXP_RESELLER_ENABLED=false\nIf your resold customers are billed directly by the reseller and not the IXP, set this to true to remove billing details from their admin and member areas.
IXP_RESELLER_RESOLD_BILLING=false\nIn the (older Zend Framework) controllers, you can execute reseller code via:
if( $this->resellerMode() ) {\n // your reseller specific code here\n}\nAnd in (the older Zend Framework) Smarty templates, you can add reseller only content via:
{if $resellerMode}\n <!-- Your reseller content -->\n{/if}\nIf you have a $customer entity, you can see if it is a reseller via:
if( $customer->isReseller() ) {}\nTo see if a customer is a resold customer or get the reseller customer entity:
if( $customer->getReseller() ) {} // returns false if not a resold customer\nFinally, to get all resold customer entities of a reseller:
$customer->getResoldCustomers()\nReseller functionality was added jointly by INEX and LONAP in June 2013.
"},{"location":"features/rir-objects/","title":"RIR Objects","text":"IXP Manager can generate (and email) your RIR objects - for example your AS-SETs, AS object, etc - to your RIR for automatic updates / maintenance.
As a concrete example of this, see how INEX do this with our RIPE objects as follows:
Some RIRs, such as RIPE, has a facility to update these objects by email.
"},{"location":"features/rir-objects/#configuration","title":"Configuration","text":"The general form of the Artisan command is:
$ php artisan rir:generate-object --send-email \\\n --to=test-dbm@ripe.net \\\n --from me@example.com autnum\nYou can see the options by using the standard -h help switch with Artisan:
$ php artisan rir:generate-object -h\nUsage:\n rir:generate-object [options] [--] <object>\n\nArguments:\n object The RIR object template to use\n\nOptions:\n --send-email Rather than printing to screen, sends and email for updating a RIR automatically\n --force Send email even if it matches the cached version\n --to[=TO] The email address to send the object to (if not specified then uses IXP_API_RIR_EMAIL_TO)\n --from[=FROM] The email address from which the email is sent (if not specified, tries IXP_API_RIR_EMAIL_FROM and then defaults to IDENTITY_EMAIL)\n -h, --help Display this help message\n -q, --quiet Do not output any message\n\nHelp:\n This command will generate and display a RIR object (and optionally send by email)\nYou will note that without the --send-email switch, the command will print to standard output allowing you to consume the object and use it on another way.
NB: the generated object is stored in the cache when it is generated with --send-email for the first time. Future runs with --send-email will only resend the email if the generated object differs from the cached version. You can force an email to be sent with --force. Secondly, the cache used is a file system based cache irrespective of the CACHE_DRIVER .env settings. To wipe it, run: artisan cache:clear file.
The following options are available for use in the .env file:
#######################################################################################\n# Options for updating RIR Objects - see https://docs.ixpmanager.org/features/rir-objects/\n\n# Your RIR password to allow the updating of a RIR object by email:\nIXP_API_RIR_PASSWORD=soopersecret\n\n# Rather than specifying the destination address on the command line, you can set it here\n# (useful for cronjobs and required for use with artisan schedule:run in >=v5.0)\nIXP_API_RIR_EMAIL_TO=test-dbm@ripe.net\n\n# Rather than specifying the from address on the command line, you can set it here\n# (useful for cronjobs and required for use with artisan schedule:run in >=v5.0)\nIXP_API_RIR_EMAIL_FROM=ixp@example.com\nThere are a number of predefined objects available under resources/views/api/v4/rir and skinning is the recommended way to add / edit these objects.
You can copy an existing template or create a new one. For example, if you wanted a template called my-as-set, you would create it under resources/skins/example/api/v4/rir/my-as-set.foil.php and then specify it to the Artisan command as:
$ php artisan rir:generate-object my-as-set\nThe template name must be lowercase, and contain only the characters: 0-9 a-z _ -.
$customers - complete Doctrine2 objects of all current external trafficking customers / members. You should be able to derive everything from this. Indexed by customer ID.$asns - an associative array for the generation of an IXP AS object indexed by ASN containing elements:['asmacro'] - the member's AS macro (or the ASN if no macro);['name'] - the member's name$rsclients - an associative array for the generation of an IXP's route server AS object. See the function definition for generateRouteServerClientDetails() in app/Tasks/Rir/Generator.php for details on the array structure.You'll find a standard template for an autnum: object at resources/views/api/v4/rir/autnum.foil.php; as well as INEX's own versions under resources/skins/inex/api/v4/rir/autnum-as2128.foil.phpandautnum-as43760.foil.php` for the IXP route collector and and route servers respectively.
Just copy one of these to your own skin directory and edit as appropriate.
"},{"location":"features/rir-objects/#as-set-connected-asns","title":"as-set: - Connected ASNs","text":"You can create an AS-SET of connected ASNs / AS macros (see INEX's AS-SET-INEX-CONNECTED as an example) via the example template as-set-ixp-connected.
You can create an AS-SET of ASNs / AS macros connected to the route servers (see AS-SET-INEX-RS as an example) via the example template as-set-ixp-rs.
There's also templates for v4 and v6 only versions: as-set-ixp-rs-v4 and as-set-ixp-rs-v6.
Prerequisite Reading: Ensure you first familiarize yourself with the generic documentation on managing and generating router configurations here.
Route collectors are an important member setup, diagnostic and metric tool for IXPs. Route collectors accept all routes and advertise none. IXP Manager will generate route collector configuration for you. You can see an example of this generated configuration here.
At INEX we use the Bird BGP daemon as our collector using the stock configuration as generated by IXP Manager. We also use this same setup for the quarantine LAN collectors. You can see our live looking glasses here for more information.
"},{"location":"features/route-collectors/#setting-up","title":"Setting Up","text":"You first need to add your route collector(s) to the IXP Manager routers database. See this page on how to do that.
Typically an IXP's route collector service will share the ASN of the IXP's own management network (but be different to the route server entry). You should also add the route collectors to your initial internal customer representing your IXP on to IXP Manager. Here's INEX's example from our peering LAN1 in Dublin:
"},{"location":"features/route-collectors/#other-information","title":"Other Information","text":""},{"location":"features/route-collectors/#quarantine","title":"Quarantine","text":"We also use a quarantine route collector when provisioning new member connections. This is a Bird BGP daemon running on a virtual machine on our quarantine LAN. For is, this quarantine LAN is:
When adding routers to IXP Manager, setting the quarantine flag means that the configuration will only contain interfaces that are on the quarantine VLAN.
"},{"location":"features/route-servers/","title":"Route Servers","text":"Prerequisite Reading: Ensure you first familiarize yourself with the generic documentation on managing and generating router configurations here.
Normally on a peering exchange, all connected parties will establish bilateral peering relationships with each other customer connected to the exchange. As the number of connected parties increases, it becomes increasingly more difficult to manage peering relationships with customers of the exchange. A typical peering exchange full-mesh eBGP configuration might look something similar to the diagram on the left hand side.
The full-mesh BGP session relationship scenario requires that each BGP speaker configure and manage BGP sessions to every other BGP speaker on the exchange. In this example, a full-mesh setup requires 7 BGP sessions per member router, and this increases every time a new member connects to the exchange.
However, by using a route servers for peering relationships, the number of BGP sessions per router stays at two: one for each route server (assuming a resilient set up). Clearly this is a more sustainable way of maintaining IXP peering relationships with a large number of participants.
"},{"location":"features/route-servers/#configuration-generation-features","title":"Configuration Generation Features","text":"Please review the generic router documentation to learn how to automatically generate route server configurations. This section goes into a bit more specific detail on INEX's route server configuration (as shipped with IXP Manager) and why it's safe to use.
You should also look at the following resources:
The features of the route server configurations that IXP Manager generates include:
With Bird v2 support in IXP Manager >= v5, we provide better looking glass integration and other tooling to show members which prefixes are filtered and why.
"},{"location":"features/route-servers/#filtering-algorithm","title":"Filtering Algorithm","text":"The Bird v2 filtering algorithm is as follows:
If a route fails at any point it is tagged (for looking glass) and rejected.
"},{"location":"features/route-servers/#setting-up","title":"Setting Up","text":"You first need to add your route servers to the IXP Manager routers database. See this page on how to do that.
Typically an IXP's route server service will have a dedicated ASN that is different to the IXP's own management / route collector ASN. As such, you need to add a new internal customer to IXP Manager.
WarningYou are strongly advised to use / request a dedicated 16-bit ASN from your RIR for route server use and in our experience, all RIRs understand this and accomodate it. The route server configurations will support an asn32 but to our knowledge, this has never been used in production. Also, withouot an asn16, you will be unable to offer your members standard community based filtering.
Here's an example from INEX for our route server #1:
You then need to create an interface for this route server on each peering LAN where the service will be offered. Here again is INEX's example from our peering LAN1 in Dublin:
There's a couple things to note in the above:
There are occasions where you may need to override the default filtering mechanism for some members. IXP Manager allows you to create custom Bird2 checks at the start of the standard import / export filters when using Bird2 (not supported on the older Bird v1 configuration).
To do this, you must create skinned files named after the ASN. For example, let's assume your skin name is example and the ASN of the member you want to apply custom filtering to is 64511; then you would an export and/or import filter in files named:
$IXPROOT/resources/skins/example/api/v4/router/server/bird2/f_import_as64511.foil.php$IXPROOT/resources/skins/example/api/v4/router/server/bird2/f_export_as64511.foil.phpYou'll see real examples from INEX here. Remember that these are placed at the beginning of the standard filters allowing you to explicitly accept or reject the prefix. However, remember that INEX accepts prefixes on import always but tags prefixes for filtering with large community routerasn:1101:x - please see the resources referenced above for details on this.
Using Bird v2 and internal large communities, we have completely overhauled how we show end users what prefixes are filtered by the route servers.
If you are running route servers using the Bird v2 configuration and if you have installed the looking glass then you should set the following in your .env file:
IXP_FE_FRONTEND_DISABLED_FILTERED_PREFIXES=false\nThis is a live view gathered from each Bird v2 route server with a looking glass.
Please see our presentations from 2019 for more information on this. Particularly the UKNOF one from September 2019 would be the most up to date.
For a route server to be polled for a customer by this tool, the following conditions must be met:
It is also critical that the looking glass for the route server works.
Caching: for large members with tens of thousands of routes, gathering filtered prefixes can be an expensive task for IXP Manager and the route server (expensive in terms of time and CPU cycles). As such, this feature of IXP Manager requires the use of a persistent cache. We recommend memcached for this which is installed and enabled by default with the automated installer.
"},{"location":"features/route-servers/#well-known-filtering-communities","title":"Well-Known Filtering Communities","text":"The route server configuration that IXP Manager generates by default provides well known communities to allow members to control the distribution of their prefixes.
NB: in the following, rs-asn is the AS number of the IXP's route server.
The standard communities are defined as follows:
Description Community Prevent announcement of a prefix to a peer0:peer-as Announce a route to a certain peer rs-asn:peer-as Prevent announcement of a prefix to all peers 0:rs-asn Announce a route to all peers rs-asn:rs-asn The community for announcing a route to all peers (rs-asn:rs-asn) is the default behaviour and so there is no need to tag routes with this.
Example #1: if a member wishes to instruct the IXP route server (with AS64500) to distribute a particular prefix only to AS64496 and AS64503, the prefix should be tagged with communities: 0:64500 64500:64496 64500:64503 (i.e. announce to no one except...).
Example #2: for a member to to announce a prefix to all IXP route server participants, excluding AS64497, the prefix should be tagged with only community 0:64497.
If you enabled support for BGP large communities, then the following large communities can be used:
Description Community Prevent announcement of a prefix to a peerrs-asn:0:peer-as Announce a route to a certain peer rs-asn:1:peer-as Prevent announcement of a prefix to all peers rs-asn:0:0 Announce a route to all peers rs-asn:1:0 If your route server is configured to support large communities, then you should advise your members to use these over standard 16-bit communities as a large number of networks now have a 32-bit ASN. You should also advise them not to mix standard 16-bit communities and large communities \u2013 please choose one or the other.
Lastly, with BGP large communities, AS path prepending control is also available by default using the following large BGP communities:
Description Community Prepend to peer AS oncers-asn:101:peer-as Prepend to peer AS twice rs-asn:102:peer-as Prepend to peer AS three times rs-asn:103:peer-as "},{"location":"features/route-servers/#rfc1997-passthru","title":"RFC1997 Passthru","text":"RFC1997 defines some well-known communities including NO_EXPORT (0xFFFFFF01 / 65535:65281) and NO_ADVERTISE and states that they have global significance and their operations shall be implemented in any community-attribute-aware BGP speaker.
According to RFC7947, it is a matter of local policy whether these well-known communities are interpreted or passed through. Historically, some IXP route servers interpret them and some pass them through. As such the behaviour of these well-known communities is not well-understood when it comes to route servers and this topic has been the subject of a good deal of debate in the IXP community over the years.
In 2017, INEX and LONAP published draft-hilliard-grow-no-export-via-rs-00 to try and create some consensus on this. While the draft was not accepted as a standard, the discussion drew a conclusion that these well-known communities should not be interpreted by the route server but passed through.
When creating a route server in IXP Manager, there is a checkbox option to control this behavior: Pass through RFC1997 well-known communities (recommended).
It is recommended that this be enabled on route servers.
"},{"location":"features/route-servers/#legacy-prefix-analysis-tool","title":"Legacy Prefix Analysis Tool","text":"The older but deprecated means of viewing filtered prefixes was the Route Server Prefix Analysis tool which allows your members to examine what routes they are advertising to the route servers, which are being accepted and which are being rejected.
"},{"location":"features/route-servers/#limitations-and-caveats","title":"Limitations and Caveats","text":"Implemented as a Perl script which accesses the database directly. The script can also only be used on one LAN and one route server. Thus, pick you most popular LAN and route server.
"},{"location":"features/route-servers/#setting-up_1","title":"Setting Up","text":"compare-route-server-prefixes.pl script and set the Bird configuration file and socket (you can find the position in the file by searching for XXX-SET-ME);compare-route-server-prefixes.pl script a few times a day as you think appropriate;.env file, ensure the following is set:IXP_FE_FRONTEND_DISABLED_RS_PREFIXES=false\nOnce you make the last change above, the prefix analysis tool will be available to administrators and members on IXP Manager.
"},{"location":"features/routers/","title":"Routers","text":"IXP Manager can generate router configuration for typical IXP services such as:
See the above pages for specific information on each of those use cases and below for instructions on how to generate configuration.
TipFor larger router configurations - especially when you have members with large prefix lists, you will need to increase PHP's memory_limit as the default of 128M will not be sufficient. Start with 512MB and watch the log (storage/logs/...) which reports the memory and time for configuration generation.
The basic elements of a router are configured in IXP Manager under the IXP Admin Actions - Routers option on the left hand menu.
When you goto add / edit a router, the green help button will provide explanatory details on each field of information required:
From the router management page, you can:
The simplest configuration to generate is the route collector configuration. A route collector is an IXP router which serves only to accept all routes and export no routes. It is used for problem diagnosis, to aid customer monitoring and for looking glasses (see INEX's here).
The original Bird v1 configuration simply pulls in a fairly standard header (sets up router ID, listening address and some filters) and creates a session for all customer routers on the given VLAN. The new Bird v2 configuration has more features and replicates the route server filtering mechanism but tags and accepts all routes for diagnosis.
When adding a router, you give it a handle. For example: rc1-lan1-ipv4 which, for INEX, would mean a route collector on peering LAN1 using IPv4. Then - for the given router handle - the configuration can be generated and pulled using the API as follows:
#! /bin/sh\n\n# The API Key.\n# This is generated in IXP Manager via the top right menu: *My Account -> API Keys*\nKEY=\"your-admin-ixp-manager-api-key\"\n\n# The base URL of your IXP Manager install plus: 'api/v4/router/gen-config'\nURL=\"https://ixp.example.com/api/v4/router/gen-config\"\n\n# The handle is as described above:\nHANDLE=\"rc1-lan1-ipv4\"\n\n# Then the configuration can be pulled as follows:\ncurl --fail -s -H \"X-IXP-Manager-API-Key: ${KEY}\" ${URL}/${HANDLE} >${HANDLE}.conf\nConfigurations for the route server and AS112 templates can be configured just as easily.
The stock templates for both are secure and well tested and can be used by setting the template element of the router to one of the following. NB: from May 2019, we recommend you use IXP Manager v5 and Bird2 templates.
'api/v4/router/as112/bird/standard''api/v4/router/as112/bird2/standard''api/v4/router/collector/bird/standard''api/v4/router/collector/bird2/standard''api/v4/router/server/bird/standard''api/v4/router/server/bird2/standard'We also provide sample scripts for automating the re-configuration of these services by cron:
All of these scripts have been written defensively such that if there is any issue getting the configuring or validating the configuration then the running router instance should be unaffected. This has worked in practice at INEX when IXP Manager was under maintenance, when there were management connectivity issues and when there were database issues. They also use the updated API (see below) to mark when the router configuration update script ran successfully.
"},{"location":"features/routers/#router-pairing-and-locking","title":"Router Pairing and Locking","text":"InfoPairing, locking and the more advanced update scripts were introduced with IXP Manager v6.4.0, and there is also a tutorial video linked from the release notes.
For IXPs, route servers are considered a critical production service and most IXPs deploy them in redundant pairs. This is usually implemented with dedicated hardware (servers with dual PSU, hardware RAID, and out-of-band management access) deployed in different points of presence.
When it comes to updating the configuration of these, the older scripts provided by IXP Manager suggested that this be done about four times per day with the timing of the cronjob set so that there is an offset so that each server will not update at the same time. The hope was that if there was an issue, only one server of the resilient pair would be affected, and engineers would have time to react and prevent updates on the other working server. Some IXPs added additional logic to the scripts to check if the other server was functional before performing a reconfiguration, but this was often limited to pings and a simple check to see if Bird was running.
The v6.4.0 release introduced a significant new resilience mechanism by pairing servers. In the IXP Manager router UI, you can now select another router to pair with the one you are editing:
You would select pairs as follows:
Once your pairs are set up, you need to deploy the new router update scripts as follows:
There is no need to use different scripts for route collectors and servers. Traditionally, at INEX, these scripts were developed slightly differently from each other (e.g., the collector script updates both IPv4 and IPv6 versions and provides more informative output, whereas the route server script takes a specific route server handle to update). We may merge these in the future.
You can use these scripts exactly as they are on an Ubuntu server changing only the configuration lines at the top:
APIKEY=\"your-api-key\"\nURLROOT=\"https://ixp.example.com\"\nBIRDBIN=\"/usr/sbin/bird\"\nThe collector script takes an additional configuration option for the handles of the servers to update - e.g.:
HANDLES=\"rc1-ipv4 rc1-ipv6\"\nThese new scripts now work as follows:
/api/v4/router/get-update-lock/$handle, which IXP Manager then processes and returns HTTP code 200 if the lock is acquired and the update can proceed./api/v4/router/updated/$handle to release the lock and update the last updated timestamp.Adding step (5) above (only reload on changes) now allows the update script to be safely run as frequently as every few minutes, which is necessary for the UI-based community filtering to be effective.
You should still offset the updates between router pairs, as the script will give up if a lock cannot be obtained. Future improvements could allow for some retries.
For additional information with UI images, see slides 25-30 in this presentation PDF.
"},{"location":"features/routers/#updated-api","title":"Updated API","text":"It can be useful to know that the scripts for updating the router configuration for AS112, route collector and route server BGP daemons run successfully. At INEX for example, we have three LANs and so 10 individual servers running a total of 30 Bird instances which is unwieldy to check and monitor manually.
When viewing routers in IXP Manager, you may have noticed the Last Updated column which will initially show (unknown). All our update scripts (see above) trigger the updated API call when a route configuration run has completed successfully. Note that this does not mean that a configuration has necessarily changed but rather that the update script ran and executed correctly. In other words: the configuration was successfully pulled from IXP Manager, compared to the running configuration and, if changed, successfully applied.
The API call to update the last updated field to now is a POST as follows:
curl -s -X POST -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixp.example.com/api/v4/router/updated/{handle}\nwhere {handle} should be replaced with the route handle as described above.
The result is a JSON object with the datetime as set and is equivalent to the result of the following API call which fetches the last updated field without setting it:
curl -s -X GET -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixp.example.com/api/v4/router/updated/{handle}\n\n{\"last_updated\":\"2017-05-21T19:14:43+00:00\",\"last_updated_unix\":1495394083}\nThere are two useful additional API endpoints. To get the last updated time of all routers, use:
curl -s -X GET -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixp.example.com/api/v4/router/updated\n\n{\"handle1\":{\"last_updated\":\"2017-05-21T19:14:43+00:00\",\"last_updated_unix\":1495394083},\n \"handle2\":{\"last_updated\":null,\"last_updated_unix\":null},\n ...}\nThe above output shows the format of the reply as well as the fact that routers without a last updated value set will be included as null values.
Lastly, you can request the last updated time of routers where that time exceeds a given number of seconds. In this call, routers without a last updated time will not be returned. This is useful for monitoring applications such as Nagios where you would want a warning / alert on any routers that have not updated in the last day for example:
curl -s -X GET -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixp.example.com/api/v4/router/updated-before/86400\n\n[]\nThis example also shows that an empty JSON object is returned for an empty result. Otherwise the format of the reply is the same as for the call above for all routers:
{\"handle1\":{\"last_updated\":\"2017-05-21T19:14:43+00:00\",\"last_updated_unix\":1495394083},...}\nWe use Travis CI to test IXP Manager before pushing new releases. The primary purpose of this is to ensure that the configuration for routers generated matches known good configurations from the same sample database.
These known good configurations also serve as useful examples of what the standard IXP Manager configuration generates.
See these known good configurations here and:
as112: AS112 router configurations conforming to rfc7534 (AS112 Nameserver Operations) and implementing rfc7535 (AS112 Redirection Using DNAME). There are configs to serve queries over both IPv4 and IPv6. See the AS112 documentation for more details.rc1: route collector configurations. Peering with the route collector is mandatory at many IXPs including INEX. These are incredibly useful for monitoring, diagnosing issues and providing looking glasses. We also use the quarantine version of these for turning up new member connections.rs1: route collector configurations. See below for full details of what these implement. See the route servers documentation for more details.The live status of any configured routers that have API access can be seen in IXP Manager via the Live Status sub-menu option of Routers on the left hand side menu.
Each router is queried twice via AJAX requests to provide:
We filter known transit networks as discussed here: https://bgpfilterguide.nlnog.net/guides/no_transit_leaks/.
There are three configuration options available (>v6.1.0) to allow you to change the default behaviour. These options exist to provide an easier path than skinning the template files directly.
Exclude one of more AS numbers from the default list (see this file on your own deployment of IXP Manager).
(1) Exclude Specific ASNs:
If you just want to exclude one or more ASNs from the default list, then using comma separation, set the following in your .env file:
IXP_NO_TRANSIT_ASNS_EXCLUDE=65501,65502\n(2) Disable This Feature Entirely:
Set an empty configuration option as follows in your .env file:
IXP_NO_TRANSIT_ASNS_OVERRIDE=\n(3) Use Your Own Custom List of ASNs:
Set the following configuration option with a comma separated list as follows in your .env file:
IXP_NO_TRANSIT_ASNS_OVERRIDE=65501,65502,65503\nIXP Manager supports RPKI validation on the router configuration generated for Bird v2. The best way to fully understand RPKI with IXP Manager is to watch our presentation from APRICOT 2019 or read this article on INEX's website.
"},{"location":"features/rpki/#rpki-validator-local-cache","title":"RPKI Validator / Local Cache","text":"IXP Manager uses the RPKI-RTR protocol to feed ROAs to the Bird router instances. We recommend you install two of these validators/local caches from different vendors.
Let IXP Manager know where they are by setting the following .env settings:
# IP address and port of the first RPKI local cache:\nIXP_RPKI_RTR1_HOST=192.0.2.11\nIXP_RPKI_RTR1_PORT=3323\n\n# While not required, we recommend you also install a second validator:\n# IXP_RPKI_RTR2_HOST=192.0.2.12\n# IXP_RPKI_RTR2_PORT=3323\nSee our installation notes for these:
As it stands, Bird v2.0.4 does not support revalidation of prefixes following ROA updates (i.e. a prefix that was accepted as ROA valid that subsequently becomes ROA unknown / invalid will remain learnt as ROA valid). The Bird developers are working on fixing this. In the interim, you need to schedule a revalidation via cron using a /etc/crontab entry such as:
20 11,23 * * * root /usr/sbin/birdc -s /var/run/bird/bird-rs1-ipv4.ctl reload in all >/dev/null\nThe outline procedure to enable RPKI is below. These notes are written from the perspective that you have existing IXP Manager Bird v1 route servers. If this is a green field site, these notes will work just as well by ignoring the upgrade bits. In either case, it's vital you already understand how to configure routers in IXP Manager.
At INEX we started with our route collector which is a non-service affecting administrative tool. Once we were happy with the stability and results of that, we upgraded our two route servers one week apart in planned announced maintenance windows. We also took the opportunity to perform a distribution upgrade from Ubuntu 16.04 to 18.04.
Start by installing two local caches / validator services as linked above. INEX uses Cloudflare's and Routinator 3000. You should also add these to your production monitoring service.
Once your maintenance window starts, stop the target route server you plan to upgrade. You'll then need to to remove the Bird v1 package (dpkg -r bird on Ubuntu). Once the Bird package is removed, you can perform a distribution upgrade if you wish.
Bird v2 is available as a prebuilt package with Ubuntu 20.04 LTS and can be installed with apt install bird2.
There are no Bird v2 packages for Ubuntu 18.04 LTS. As such, you need to install from source if using that older platform. Rather than installing a build environment and compiling on each server, you can do this on a single server (a dedicated build box / admin server / etc) and then distribute the package across your route servers / collector:
# Install Ubuntu build packages and libraries Bird requires:\napt install -y build-essential libssh-dev libreadline-dev \\\n libncurses-dev flex bison checkinstall\n\n# At time of writing, the latest release was v2.0.7.\n# Check for newer versions!\ncd /usr/src\nwget ftp://bird.network.cz/pub/bird/bird-2.0.7.tar.gz\ntar zxf bird-2.0.7.tar.gz\ncd bird-2.0.7/\n./configure --prefix=/usr --sysconfdir=/etc\nmake -j2\ncheckinstall -y\nThe checkinstall tool creates a deb package file: /usr/local/src/bird-2.0.7/bird_2.0.7-1_amd64.deb
NB: for this method to work, you must be running the same operating system and version on the target servers as the build box. For us, it was Ubuntu 18.04 LTS on all systems.
To install on a target machine:
# from build machine\nscp bird_2.0.7-1_amd64.deb target-machine:/tmp\n\n# on target machine\napt install -y libssh-dev libreadline-dev libncurses-dev\ndpkg -i /tmp/bird_2.0.7-1_amd64.deb\nYou now need to update your route server record in IXP Manager:
api/v4/router/server/bird2/standard.Note that the Bird v2 template uses large BGP communities extensively internally. The option Enable Large BGP Communities / RFC8092 only controls whether your members can use large communities for filtering. It's 2020 - you should really enable this.
As mentioned above, you need to let IXP Manager know where your local caching / validators are by setting the following .env settings:
# IP address and port of the first RPKI local cache:\nIXP_RPKI_RTR1_HOST=192.0.2.11\nIXP_RPKI_RTR1_PORT=3323\n\n# While not required, we recommend you also install a second validator:\nIXP_RPKI_RTR2_HOST=192.0.2.12\nIXP_RPKI_RTR2_PORT=3323\nTake a look at the generated configuration within IXP Manager now and sanity check it.
If you have been using our scripts to reload route server configurations, you will need to download the new one (and edit the lines at the top) or update your existing one. The main elements that need to be changed is that the daemon name is not longer named differently for IPv6 (Bird v1 had bird/birdc and bird6/bird6c where as Bird v2 only has bird/birdc).
You should now be able to run this script to pull a new configuration and start an instance of the route server. We would start with one and compare route numbers (just eyeball them) against the route server you have not upgraded.
You're nearly there! If you are using our Bird's Eye looking glass, you will need to upgrade this to >= v1.2.1 for Bird v2 support. At INEX, we tend to clone the repository and so a simple git pull is all that's required. If you're installing from release packages, get the latest one and copy over your configurations.
These notes are valid when using IXP Manager's Bird v2 with RPKI route server configuration.
You can see the status of the RPKI-RTR protocol with:
bird> show protocols \"rpki*\"\nName Proto Table State Since Info\nrpki1 RPKI --- up 2019-05-11 14:51:40 Established\nrpki2 RPKI --- up 2019-05-11 12:44:25 Established\nAnd you can see detailed information with:
bird> show protocols all rpki1\nName Proto Table State Since Info\nrpki1 RPKI --- up 2019-05-11 14:51:40 Established\n Cache server: 10.39.5.123:3323\n Status: Established\n Transport: Unprotected over TCP\n Protocol version: 1\n Session ID: 54059\n Serial number: 122\n Last update: before 459.194 s\n Refresh timer : 440.805/900\n Retry timer : ---\n Expire timer : 172340.805/172800\n Channel roa4\n State: UP\n Table: t_roa\n Preference: 100\n Input filter: ACCEPT\n Output filter: REJECT\n Routes: 72161 imported, 0 exported\n Route change stats: received rejected filtered ignored accepted\n Import updates: 141834 0 0 0 141834\n Import withdraws: 2519 0 --- 0 3367\n Export updates: 0 0 0 --- 0\n Export withdraws: 0 --- --- --- 0\n No roa6 channel\nYou can examine the ROA table with:
bird> show route table t_roa\nTable t_roa:\n58.69.253.0/24-24 AS36776 [rpki1 2019-05-11 14:51:40] * (100)\n [rpki2 2019-05-11 12:45:45] (100)\nNow, using INEX's route collector ASN (2128) as an example here - change for your own collector/server ASN - you can find RPKI invalid and filtered routes via:
bird> show route where bgp_large_community ~ [(2128,1101,13)]\nTable master4:\n136.146.52.0/22 unicast [pb_as15169_vli99_ipv4 2019-05-11 01:00:17] * (100) [AS396982e]\n via 185.6.36.57 on eth1\n...\nAt time of writing, the filtered reason communities are:
define IXP_LC_FILTERED_PREFIX_LEN_TOO_LONG = ( routeserverasn, 1101, 1 );\ndefine IXP_LC_FILTERED_PREFIX_LEN_TOO_SHORT = ( routeserverasn, 1101, 2 );\ndefine IXP_LC_FILTERED_BOGON = ( routeserverasn, 1101, 3 );\ndefine IXP_LC_FILTERED_BOGON_ASN = ( routeserverasn, 1101, 4 );\ndefine IXP_LC_FILTERED_AS_PATH_TOO_LONG = ( routeserverasn, 1101, 5 );\ndefine IXP_LC_FILTERED_AS_PATH_TOO_SHORT = ( routeserverasn, 1101, 6 );\ndefine IXP_LC_FILTERED_FIRST_AS_NOT_PEER_AS = ( routeserverasn, 1101, 7 );\ndefine IXP_LC_FILTERED_NEXT_HOP_NOT_PEER_IP = ( routeserverasn, 1101, 8 );\ndefine IXP_LC_FILTERED_IRRDB_PREFIX_FILTERED = ( routeserverasn, 1101, 9 );\ndefine IXP_LC_FILTERED_IRRDB_ORIGIN_AS_FILTERED = ( routeserverasn, 1101, 10 );\ndefine IXP_LC_FILTERED_PREFIX_NOT_IN_ORIGIN_AS = ( routeserverasn, 1101, 11 );\ndefine IXP_LC_FILTERED_RPKI_UNKNOWN = ( routeserverasn, 1101, 12 );\ndefine IXP_LC_FILTERED_RPKI_INVALID = ( routeserverasn, 1101, 13 );\ndefine IXP_LC_FILTERED_TRANSIT_FREE_ASN = ( routeserverasn, 1101, 14 );\ndefine IXP_LC_FILTERED_TOO_MANY_COMMUNITIES = ( routeserverasn, 1101, 15 );\nCheck the route server configuration as generated by IXP Manager for the current list if you are reading this on a version later than v5.0.
If you want to see if a specific IP is covered by a ROA, use:
bird> show route table t_roa where 45.114.234.0 ~ net\nTable t_roa:\n45.114.234.0/24-24 AS59347 [rpki1 2019-05-11 14:51:40] * (100)\n [rpki2 2019-05-11 12:45:45] (100)\n45.114.232.0/22-24 AS59347 [rpki1 2019-05-11 14:51:40] * (100)\n [rpki2 2019-05-11 12:45:45] (100)\n45.114.232.0/22-22 AS59347 [rpki1 2019-05-11 14:51:41] * (100)\n [rpki2 2019-05-11 12:45:45] (100)\nThe IXP Manager sflow peer-to-peer graphing system depends on the MAC address database system so that point to point traffic flows can be identified. Before proceeding further, this should be configured so that when you click on either the MAC Addresses | Discovered Addresses or MAC Addresses | Configured Addresses links from the admin portal, you should see a MAC address associated with each port. If you cannot see any MAC address in either database, then the sflow peer-to-peer graphing mechanism will not work. This needs to be working properly before any attempt is made to configure sflow peer-to-peer graphing. The sflow p2p graphing system can use either discovered MAC addresses or configured MAC addresses, but not both.
As sflow can put a reasonably high load on a server due to disk I/O for RRD file updates - it is recommended practice to use a separate server (or virtual server) to handle the IXP's sflow system. The sflow server will need:
noatime, nodiratime options, and which has enough disk space. You may also want to consider disabling filesystem journaling.pkg install apache24 sflowtool git databases/rrdtool mrtg\napt-get install apache2 git rrdtool rrdcached mrtg\nsflowtool is not part of the Ubuntu / Debian package archive and must be compiled from source if running on these systems. The source code can be found on Github: https://github.com/sflow/sflowtool.
Once the required packages are installed, the IXP Manager peer-to-peer graphing system can be configured as follows:
git clone https://github.com/inex/IXP-Manager /srv/ixpmanager.tools/runtime/check-perl-dependencies.pl command. These libraries will need to be manually installed.tools/perl-lib/IXPManager directory (perl Makefile.PL; make install)rrdcached. We recommend using journaled mode with the -P FLUSH,UPDATE -m 0666 -l unix:/var/run/rrdcached.sock options enabled. Note that these options allow uncontrolled write access to the RRD files from anyone on the sflow machine, so precautions should be taken to limit access to this server to ensure that this cannot be abused.On FreeBSD it is advisable to set net.inet.udp.blackhole=1 in /etc/sysctl.conf, to stop the kernel from replying to unknown sflow packets with an ICMP unreachable reply.
The following sflow parameters must be set in the <ixp> section:
sflow_rrdcached: set to 0 or 1, depending on whether you want to use rrdcached or not.sflowtool: the location of the sflowtool binary.sflowtool_opts: command-line options to pass to sflowtoolsflow_rrddir: the directory where all the sflow .rrd files will be stored.apikey: a valid API key. Instructions for configuring this can be found in the API configuration documentation.apibaseurl: the base URL of the IXP Manager API. E.g. if you log into IXP Manager using https://ixp.example.com/, then apibaseurl will be https://ixp.example.com/api/v4.macdbtype: configured|discovered - specifies whether the sflow p2p graphing system should pull MAC address information from the Configured MAC address database or the Discovered MAC address database. By default, it uses the Discovered MAC address database. If you wish to use the Configured MAC address database, then this should be set to configured.Note that the <sql> section of ixpmanager.conf will need to be configured either if you are running update-l2database.pl or the sflow BGP peering matrix system. The sflow-to-rrd-handler script uses API calls and does not need SQL access.
An example ixpmanager.conf might look like this:
<sql>\n dbase_type = mysql\n dbase_database = ixpmanager\n dbase_username = ixpmanager_user\n dbase_password = blahblah\n dbase_hostname = sql.example.com\n</sql>\n\n<ixp>\n sflowtool = /usr/bin/sflowtool\n sflowtool_opts = -4 -p 6343 -l\n sflow_rrdcached = 1\n sflow_rrddir = /data/ixpmatrix\n\n apikey = APIKeyFromIXPManager\n apibaseurl = http://www.example.com/ixp/api/v4\n macdbtype = configured\n</ixp>\nThis file should be placed in /usr/local/etc/ixpmanager.conf
The tools/runtime/sflow/sflow-to-rrd-handler command processes the output from sflowtool and injects it into the RRD archive. This command should be configured to start on system bootup.
If you are running on FreeBSD, this command can be started on system bootup by copying the tools/runtime/sflow/sflow_rrd_handler script into /usr/local/etc/rc.d and modifying the /etc/rc.conf command to include:
sflow_bgp_handler_enable=\"YES\"\nThe IXP Manager web GUI requires access to the sflow p2p .rrd files over http or https. This means that the sflow server must run a web server (e.g. Apache), and the IXP Manager GUI must be configured with the URL of the RRD archive on the sflow server.
Assuming that ixpmanager.conf is configured to use /data/ixpmatrix for the RRD directory, these files can be server over HTTP using the following Apache configuration (please consider appropriate access security - this example assumes an internal host on an internal network):
Alias /grapher-sflow /data/ixpmatrix\n<Directory \"/data/ixpmatrix\">\n Options None\n Require all granted \n</Directory>\nThe IXP Manager .env file must be configured with parameters both to enable sflow and to provide the front-end with the HTTP URL of the back-end server. Assuming that the sflow p2p server has IP address 10.0.0.1, then the following lines should be added to .env:
GRAPHER_BACKENDS=\"mrtg|sflow|smokeping\"\nGRAPHER_BACKEND_SFLOW_ENABLED=true\nGRAPHER_BACKEND_SFLOW_ROOT=\"http://10.0.0.1/grapher-sflow\"\nEach IXP edge port will have 4 separate RRD files for recording traffic to each other participant on the same VLAN on the IXP fabric: ipv4 bytes, ipv6 bytes, ipv4 packets and ipv6 packets. This means that the number of RRD files grows very quickly as the number of IXP participants increases. Roughly speaking, for every N participants at the IXP, there will be about 4*N^2 RRD files. As this number can create extremely high I/O requirements on even medium sized exchanges, IXP Manager requires that rrdcached is used.
There are plenty of things which could go wrong in a way which would stop the sflow mechanism from working properly.
update-l2database.pl script, if you are using discovered MAC addresses. If you're using configured MAC addresses, you can ignore update-l2database.pl script completed but you should make sure that there are valid MAC addresses associated with each port you're attempting to monitor.sflow-to-rrd-handler script crashes, this may indicate that the back-end filesystem is overloaded. Installing rrdcached is a first step here. If it crashes with rrdcached enabled, then you need more disk I/O (SSDs, etc).No. All of this runs perfectly well on Ubuntu (or your favourite Linux distribution).
INEX runs its sflow back-end on FreeBSD because we found that the UFS filesystem performs better than the Linux ext3 filesystem when handling large RRD archives. If you run rrdcached, it's unlikely that you will run into performance problems. If you do, you can engineer around them by running the RRD archive on a PCIe SSD.
The tools/runtime/sflow/sflow-to-rrd-handler script from IXP Manager referenced above uses an IXP Manager API endpoint to associate sflow samples (based on source and destination MAC addreesses) with VLAN interfaces.
As IXP Manager supports layer2 / MAC addresses in two ways (learned versus configured), there are two endpoints (using https://ixp.example.com as your IXP Manager installation):
https://ixp.example.com/api/v4/sflow-db-mapper/learned-macshttps://ixp.example.com/api/v4/sflow-db-mapper/configured-macsThe JSON output is structured as per the following example:
{\n \"infrastructure id\": {\n \"vlan tag\": {\n \"mac address\": \"vlan interface id\",\n ...\n },\n ...\n },\n ...\n}\nwhere:
\"macaddress\": \"vlaninterfaceid\"IXP Manager can use sflow data to:
The peer-to-peer traffic graphs show traffic aggregate analysis of bytes/packets, split by VLAN and protocol (IPv4 / IPv6), both for individual IXP peering ports and entire VLANs.
The peering matrix guesses who interconnects with whom on the basis of analysing bgp session flows.
"},{"location":"features/sflow/#helicopter-view","title":"Helicopter View","text":"Sflow needs to be configured with an \"accounting perimeter\". This means that ingress sflow accounting should be enabled on all edge ports, but should not be enabled on any of the core ports. This approach ensures that all packets entering or leaving the IXP are counted exactly once, when they enter the IXP fabric.
All the switches at the IXP should be configured to send sflow packets to the IP address of your sflow collector. This will probably be the same server that you use for your IXP Manager sflow peer-to-peer graphing.
If sflow is enabled on any of the core ports or sflow is enabled in both directions (ingress + egress), traffic will be double-counted and this will lead to incorrect graphs.
Each switch on the network sends sampled sflow packets to an sflow collector. These packets are processed by the \"sflowtool\" command, which converts into an easily-parseable ascii format. IXP Manager provides a script to read the output of the sflowtool command, correlate this against the IXP database and to use this to build up a matrix of traffic flows which are then exported to an RRD database.
The RRD files are stored on disk and can be accessed by using the sflow graphing system included in IXP Manager.
"},{"location":"features/sflow/#sflow-on-switches","title":"Sflow on Switches","text":"Many vendors support sflow, but some do not. There is a partial list on the sflow web site.
Most switches which support sflow will support ingress accounting, because this is what's required in RFC 3176. Some switches (e.g. Dell Force10 running older software) only support egress sflow. If you use these on your IXP alongside other switches which only support ingress sflow, then the sflow graphs will show twice the traffic in one direction for the p2p graphs and zero traffic in the other direction. There is no way for IXP Manager to work around this problem.
If not all of the IXP edge ports are sflow capable, then sflow traffic data will be lost for these ports. This means that some point-to-point traffic graphs will show up with zero traffic, and that the sflow aggregate graphs will be wrong.
Sflow uses data sampling. This means that the results it produces are estimated projections, but on largee data sets, these projections tend to be statistically accurate.
Each switch or switch port needs to be configured with an sflow sampling rate. The exact rate chosen will depend on the traffic levels on the switch, how powerful the switch management plane CPU is, and how much bandwidth is available for the switch management.
On a small setup with low levels of traffic (e.g. 100kpps), it would be sensible to leave the sampling rate low (e.g. 1:1024). Alternatively, a busy 100G port may need a sampling rate of 1:32768 may turn out to be too low if the port is seeing large numbers of packets. If the switch or the entire network is handling very large quantities of traffic, this figure should be high enough that IXP ports with low quantities of traffic will still get good quality graphs, but low enough that the switch management CPU isn't trashed, and that packets are not dropped on the management ethernet port.
Some switches have automatic rate-limiting built in for sflow data export. The sampling rate needs to be chosen so that sflow data export rate limiting doesn't kick in. If it does, samples will be lost and this will cause graph inaccuracies.
"},{"location":"features/sflow/#switch-implementation-limitations","title":"Switch Implementation Limitations","text":""},{"location":"features/sflow/#netflow","title":"Netflow","text":"IXP Manager does not support netflow and support is not on the roadmap. This is because most netflow implementations do not export mac address information, which means that they cannot provide workable mac layer peer-to-peer statistics.
"},{"location":"features/sflow/#cisco-switches","title":"Cisco Switches","text":"Of Cisco's entire product range, only the Nexus 3000 and Nexus 9000 product range support sflow. Also, the sflow support on the Cisco Nexus 3k range is crippled due to the NX-OS software implementation, which forces ingress+egress sflow to be configured on specified ports rather than ingress-only. Functional accounting requires ingress-only or egress-only sflow to be configured on a per-port basis: ingress + egress causes double-counting of packets. It may be possible to work around this limitation using the broadcom shell using something like the following untested configuration:
n3k# conf t\nn3k(config)# feature sflow\nn3k(config)# sflow data-source interface Ethernet1/1\nn3k(config)# ^Z\nn3k# test hardware internal bcm-usd bcm-diag-shell\nAvailable Unit Numbers: 0\nbcm-shell.0> PortSampRate xe0 4096 0\nbcm-shell.0> PortSampRate xe0\n xe0: ingress: 1 out of 4096 packets, egress: not sampling,\nbcm-shell.0> quit\nn3k#\nNote that this command is not reboot persistent, and any time the switch is rebooted, the command needs to be re-entered manually. Note also that this configuration is untested.
"},{"location":"features/sflow/#brocade-turboiron-24x","title":"Brocade TurboIron 24X","text":"By default a TIX24X will export 100 sflow records per second. This can be changed using the following command:
SSH@Switch# dm device-command 2762233\nSSH@Switch# tor modreg CPUPKTMAXBUCKETCONFIG(3) PKT_MAX_REFRESH=0xHHHH\n... where HHHH is the hex representation of the number of sflow records per second. INEX has done some very primitive usage profiling which suggests that going above ~3000 sflow records per second will trash the management CPU too hard, so we use PKT_MAX_REFRESH=0x0BB8. Note that this command is not reboot persistent, and any time a TIX24X is rebooted, the command needs to be re-entered manually.
"},{"location":"features/sflow/#dell-force10","title":"Dell Force10","text":"Earlier versions of FTOS only support egress sflow, but support for ingress sflow was added in 2014. If you intend to deploy IXP Manager sflow accounting on a Dell F10 switch, then you should upgrade to a software release which supports ingress sflow.
"},{"location":"features/sflow/#cumulus-linux","title":"Cumulus Linux","text":"Cumulus Linux uses hsflowd, which does not allow the operator to enable or disable sflow on a per-port basis, nor does it permit the operator to configure ports to use ingress-only sflow. This configuration needs to be handled using the /usr/lib/cumulus/portsamp command, which is not reboot persistent. It is strongly recommended to handle this configuration using orchestration, as it is not feasible to manually maintain this configuration.
The sflow data from all the IXP switches will normally be directed at a single sflow collector. Often it is useful to have multiple copies of this sflow data stream so that the sflow data can be processed in different ways.
IXP Manager uses sflow data for two separate components:
This means that IXP Manager needs two separate sflow feeds. This can be achieved by using the sflowtool fanout facility, which sends an exact copy of all incoming sflow records to a list of destinations. For example, the following command listens for incoming sflow data on port 6343 and send three copies out. Two copies are directed to different ports on the same server, on ports 5500 and 5501. The third copy is sent to 192.0.2.20, port 6343.
# sflowtool -4 -p 6343 -f 127.0.0.1/5500 -f 127.0.0.1/5501 -f 192.0.2.20/6343\nThis example could be used for handling P2P traffic graphs and BGP session detection on one machine, while sending a third sflow data feed to a separate server for IXP development or debugging. The two local sflow feeds can be read using sflowtool:
# sflowtool -4 -p 5500 -l\n# sflowtool -4 -p 5501 -l\nThe sflowtool fanout daemon should be started by the normal operating system daemon startup mechanism, e.g. script in a rc.d or init.d directory, or by a manual entry in /etc/rc.local.
If running sflowtool version 3.23 or greater, it is important to use the -4 command-line parameter in sflowtool because otherwise it will listen on both ipv4 and ipv6 sockets. If you have an sflowtool process attempting to listen on a wildcard socket, it will stop other sflowtool processes from starting.
Remember that v4 is a transition version of IXP Manager from Zend Framework / Smarty to Laravel and so much of the frontend / templating still uses v3 templates and code. As such, how to skin a page will depend on whether the template is found in resources/views (v4) or application/[modules/xxx/]views (v3). Both are covered here.
IXP Manager supports template/view skinning allowing users to substitute any of their own templates in place of the default ones shipped with IXP Manager.
"},{"location":"features/skinning/#skinning-in-version-v4","title":"Skinning in Version >=v4","text":"First, set the following parameter in .env:
VIEW_SKIN=\"example\"\nSkins should then be placed in the resources/skins/example directory (example should be substituted for whatever you want to call your own skin). The default templates can be found in resources/views directory. INEX bundles its own skinned templates in resources/skins/inex as an example.
Once a skin is enabled from .env, then any templates found in the skin directory (using the same directory structure as found under resouces/views) will take precedence over the default template file. This means you do not need to recreate / copy all the default files - just replace the ones you want.
In previous versions of IXP Manager, we used Smarty as the templating engine. This meant that if someone wanted to help improve IXP Manager then they would need to become familiar with PHP and Smarty. In v4 we dropped Smarty and, rather than using another compiled templating engine, we have decided to go with native PHP templates.
For this, we are using Foil - Foil brings all the flexibility and power of modern template engines to native PHP templates. Write simple, clean and concise templates with nothing more than PHP. Also, simulaneously supported are Lavael's own Blade templates which we sometimes use for simple pages.
"},{"location":"features/skinning/#example","title":"Example","text":"The graphing MRTG configuration generator allows for custom configuration content at the top and bottom of the file. In order to have your custom configuration enabled, you need to skin two files.
Here's an example:
# position ourselves in the IXP Manager root directory\ncd ${IXPROOT}\n\n# make the skin directory\nmkdir resources/skins/example\n\n# create the full path required for the MRTG configuration files:\nmkdir -p resources/skins/example/services/grapher/mrtg\n\n# copy over the customisation files:\ncp views/services/grapher/mrtg/custom-header.foil.php resources/skins/example/services/grapher/mrtg\ncp views/services/grapher/mrtg/custom-footer.foil.php resources/skins/example/services/grapher/mrtg\n\n# edit the above files as required\nvi resources/skins/example/services/grapher/mrtg/custom-header.plates.php\nvi resources/skins/example/services/grapher/mrtg/custom-footer.plates.php\nThen, finally, edit .env and set the skin to use:
VIEW_SKIN=\"example\"\nYou can of course skin any file including the non-custom MRTG files as suits your needs.
"},{"location":"features/skinning/#custom-variables-configuration-options","title":"Custom Variables / Configuration Options","text":"When you are skinning your own templates, you may find you need to create custom configuration options for values you do not want to store directly in your own templates. For this, we have a configuration file which is excluded from Git. Initiate it via::
cp config/custom.php.dist config/custom.php\nThis is Laravel's standard configuration file format (which is an associative PHP array). You can also use Laravel's dotenv variables here too.
As an example, if you were to create a configuration option:
<?php\n'example' => [\n 'key' => 'my own config value',\n],\nthen in code this would be accessible as:
<?php\nconfig( \"custom.example.key\", \"default value if not set|null\" )\nwhere the second parameter is a default option if the requested configuration setting has not been defined (which defaults to null). In templates, this can be accessed the same way or rendered in the template with::
<?= config( \"custom.example.key\", \"default\" ) ?>\nThis is still important as IXP Manager v4 still uses most of the previous templates.
To skin files found under application/[modules/xxx/]views, proceed as follows:
set a skin name in .env:
VIEW_SMARTY_SKIN=\"myskin\"\ncreate a directory with a matching name: application/views/_skins/myskin.
Once the above .env option is set, then any pages in its skin directory (using the same directory structure as application/views will take precedence over the default template files. This means you do not need to recreate / copy all the default files - just replace the ones you want.
Usually there is one of two places to find a template:
resources/views/$controller/$actionapplication/views/$controller/$actionIf you're skinning, then there's an extra two places:
resources/skins/$skin/$controller/$actionapplication/views/_skins/$skin/$controller/$actionThe indicated variables above mean:
$controller: typically the first part of the URL (after the main IXP Manager site) for the page you are looking at. Examples include: patch-panel, router but they may also be deeper API paths such as api/v4/router.$action: the last part of the URL such as edit.$skin: the name of your skin as defined above.Typically, following the URL path in the views directory will yield the template file you need.
To help identify if the page you are looking at is from the =v4 code base, we have added a HTML comment to the templates which appears just after the <head> tag as follows:
For >=v4 (new codebase):
<!-- IXP MANAGER - template directory: resources/[views|skins] -->\nFor <v4 (old codebase):
<!-- IXP MANAGER - template directory: application/views -->\nIXP Manager can serve some static pages for you if you wish. The typical use cases for this are:
In IXP Manager, there are four types of users as described in the users page. Static contact can be added which requires a minimum user privilege to access (e.g. priv == 0 would be publicly accessible through to priv == 3 which would require a superadmin).
To create static content, you should first set up skinning for your installation. Let's assume you called your skin example.
To create a publicly accessible static content page called misc-benefits, you would first create a content directory in your skin as follows:
cd $IXPROOT\nmkdir -p resources/skins/example/content/{0,1,2,3}\nwhere the directories 0, 1, 2, 3 represent the minimum required user privilege to access the content. You can now create your content page as follows:
cp resources/views/content/0/example.foil.php resources/skins/example/content/0/misc-benefits.foil.php\nand then edit that page.
It can be accessed using a URL such as: https://ixp.example.com/content/0/misc-benefits where the route template is: content/{priv}/{page}.
{priv} is the minimum required user privilege required to access the page and is used first for testing the user's permissions and second as the directory to check for the file.{page} is the name of the file to load (less .foil.php) and please be aware that this is normalised as follows: preg_replace( '/[^a-z0-9\\-_]/', '', strtolower( $page ) )\n[a-z0-9\\-_] and all lower case. Prior to v4.8.0 the strtolower() mistakenly occurred after the preg_replace().The example.foil.php template copied above should provide the necessary structure for you. Essentially just replace the title and the content.
For publicly accessible documents, there is an alias route:
/public-content/{page} -> treated as: /content/0/{page}\nIXP Manager ships with a link to Support in the main title menu. You should copy and adjust this as necessary via skinning:
cp resources/views/content/0/support.foil.php resources/skins/example/content/0/support.foil.php\nYou can link to your own static contact pages using the Documentation menu by skinning this file:
cp resources/views/layouts/header-documentation.foil.php resources/skins/example/layouts/header-documentation.foil.php\nThe stock version includes a link to the example page and a external link to the IXP Manager website (we would be much obliged if you left this in place!).
INEX's own version of this can be found in the shipped resources/skins/inex/header-documentation.foil.php file which shows how we use it.
IXP Manager can generate formatted lists of user information. The best example of this is for TACACS.
TACACS is used in most IXPs to manage access to switching and routing devices:
IXP Manager comes with a flexible template for generating the user section of a TACACS file.
"},{"location":"features/tacacs/#generating-tacacs-configuration","title":"Generating TACACS Configuration","text":"You can use the IXP Manager API to get the user section of a TACACS file using the following endpoint formats (both GET and POST requests work):
https://ixp.example.com/api/v4/user/formatted\nhttps://ixp.example.com/api/v4/user/formatted/{priv}\nhttps://ixp.example.com/api/v4/user/formatted/{priv}/{template}\nwhere:
priv is an optional user privilege to limit the user selection to. See the available integer values on the AUTH_ constants here. You typically want 3.template is an optional template (rather than $IXPROOT/resources/views/api/v4/user/formatted/default). See below.And example of a user in the response is:
user=joebloggs {\n member=admin\n login = des \"$2y$10$pHln5b4DrPj3uuhgfg45HeWEQLK/3ngRxYgYppbnYzleJ.9EpLAN.\"\n}\nYou can optionally POST any of the following to change elements of the default template:
template: only relevant when you want to specify a specific template without a privilege.priv: same as above.users: a comma-separated list of usernames to return rather than all / all based on privilege.bcrypt: IXP Manager stores bcrypt hashes with the prefix 2y. Some systems, such as TACACS+ on FreeBSD, require 2a. If you set bcrypt=2a, this substitution will be made before the data is returned.group: we put all users in the admin group in the default template. You can change that here.An example of changing these parameters is:
curl --data \"users=bob,alice&group=god&bcrypt=2a\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/user/formatted\nYou can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called mytemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/api/v4/user/formatted\ncp resources/views/api/v4/user/formatted/default.foil.php resources/skins/myskin/api/v4/user/formatted/mytemplate1.foil.php\nYou can now edit this template as required. The only constraint on the template name is it can only contain characters from the classes a-z, 0-9, -. NB: do not use uppercase characters.
All variables available in the template can be seen in the default template.
"},{"location":"features/tacacs/#setting-up-tacacs","title":"Setting Up TACACS","text":"This section explains how to set up TACACS with IXP Manager. We assume you already have an understanding of TACACS.
"},{"location":"features/tacacs/#generating-updating-tacacs","title":"Generating / Updating TACACS","text":"At INEX, we use a script that:
You can find that script in this directory. Alter it to suit your own purposes.
"},{"location":"features/rpki/cloudflare/","title":"Cloudflare's RPKI Toolkit","text":"DangerCloudflare's RPKI toolkit has been deprecated and should not be used.
Cloudflare created their own RPKI toolkit which, similar to RIPE's, is split into two elements:
NB: Before you proceed further, you should read Cloudflare's own introduction to this toolkit.
We use a standard Ubuntu 20.04 installation (selecting the minimal virtual server option), 2 vCPUs, 2GB RAM, 20GB LVM hard drive.
Cloudflare provide pre-built packages for installation - visit the following URLs and download the appropriate packages for your operating system:
As of late November 2020, the following packages are available to install:
wget https://github.com/cloudflare/cfrpki/releases/download/v1.2.2/octorpki_1.2.2_amd64.deb\nwget https://github.com/cloudflare/gortr/releases/download/v0.14.7/gortr_0.14.7_amd64.deb\ndpkg -i octorpki_1.2.2_amd64.deb gortr_0.14.7_amd64.deb\nYou now need to install the ARIN file manually:
/usr/share/octorpki/tals/arin.talYou can now run the validator via the following command:
# start the service:\nsystemctl start octorpki\n\n# see and tail the logs\njournalctl -fu octorpki\n\n# enable to start on server boot:\nsystemctl enable octorpki.service\nNB: OctoRPKI listens as a web service by default on port 8081. It's possible to change this port by adding OCTORPKI_ARGS=-http.addr :8080 to /etc/default/octorpki if required.
As it starts up, there is some info available as JSON under http://[hostname/ip address]:8081/infos and the ROAs can be seen as JSON via http://[hostname/ip address]:8081/output.json after ~5mins.
To start GoRTR (once OctoRPKI is configured and running), we first edit /etc/default/gortr:
GORTR_ARGS=-bind :3323 -verify=false -cache http://localhost:8081/output.json -metrics.addr :8082\nYou can now run the GoRTR daemon via the following command:
# start the service:\nsystemctl start gortr\n\n# see and tail the logs\njournalctl -fu gortr\n\n# enable to start on server boot:\nsystemctl enable gortr.service\nOnce GoRTR starts up, metrics are available from http://[hostname/ip address]:8082/metrics.
"},{"location":"features/rpki/cloudflare/#monitoring","title":"Monitoring","text":"We add Nagios http checks for ports 8081 (OctoRPKI) and 8082 (GoRTR) to our monitoring platform. We also add a check_tcp test for GoRTR port 3323.
The RIPE NCC RPKI Validator 3 has been deprecated and should not be used.
The RIPE NCC RPKI Validator 3 is a RPKI relying party software (aka RPKI Validator). While RIPE's RPKI Validator 3 is a RPKI-RTR implementation we have tested and support, we found it buggy in production (as of April 2019 it consumed increasing amounts of disk space and crashed regularly). These instructions reflect INEX's production installation from early 2019.
RIPE provides CentOS7 RPMs for production builds but as we tend to use Ubuntu LTS for our servers, we will describe an installation using the generic builds here. You can read RIPE's CentOS7 installation details here and their own generic install details here (which are the ones we worked from for these Ubuntu 18.04 LTS instructions).
We use a standard Ubuntu 18.04 installation (selecting the minimal virtual server option), 2 vCPUs, 2GB RAM, 10GB LVM hard drive.
We will use a non-root user to run the daemons:
useradd -c 'RIPE NCC RPKI Validator' -d /srv/ripe-rpki-validator \\\n -m -s /bin/bash -u 1100 ripe\nDownload and extract the latest production releases from here:
cd /srv/ripe-rpki-validator\nwget https://ftp.ripe.net/tools/rpki/validator3/prod/generic/rpki-rtr-server-latest-dist.tar.gz\ntar zxf rpki-rtr-server-latest-dist.tar.gz\nwget https://ftp.ripe.net/tools/rpki/validator3/prod/generic/rpki-validator-3-latest-dist.tar.gz\ntar zxf rpki-validator-3-latest-dist.tar.gz\nWhen you extract these, you'll find they create directories named by their version. As we will reference these in various scripts, we will alias these directories so we do not need to update the scripts on an upgrade of the software. In our example case, the version was 3.0-255 so we do the following (and also ensure the permissions are correct):
ln -s rpki-rtr-server-3.0-355 rpki-rtr-server-3\nln -s rpki-validator-3.0-355 rpki-validator-3\nchown -R ripe: /srv/ripe-rpki-validator\nThe requirements for RPKI Validator 3 are OpenJDK and rsync. For Ubuntu 18.04 that means:
apt install -y openjdk-8-jre rsync curl\nWe will want to keep configuration changes and the database across upgrades. For this we:
# move the config and replace it with a link:\ncd /srv/ripe-rpki-validator\nmv rpki-validator-3/conf/application.properties rpki-validator-3.conf\nln -s /srv/ripe-rpki-validator/rpki-validator-3.conf \\\n /srv/ripe-rpki-validator/rpki-validator-3/conf/application.properties\n\n# And do the same for the datebase:\nmv rpki-validator-3/db .\nln -s /srv/ripe-rpki-validator/db /srv/ripe-rpki-validator/rpki-validator-3/db\n\n# And do the same for rpki-rtr-server-3:\nmv rpki-rtr-server-3/conf/application.properties rpki-rtr-server-3.conf\nln -s /srv/ripe-rpki-validator/rpki-rtr-server-3.conf \\\n /srv/ripe-rpki-validator/rpki-rtr-server-3/conf/application.properties\n\n# again, ensure file ownership is okay\nchown -R ripe: /srv/ripe-rpki-validator\nWe then edit /srv/ripe-rpki-validator/rpki-validator-3.conf and change the following configuration options:
server.port and server.address if you want to access the web interface directly. Commenting server.address out makes it listen on all interfaces.spring.datasource.url to /srv/ripe-rpki-validator/db/rpki-validator.h2.And we edit /srv/ripe-rpki-validator/rpki-rtr-server-3.conf and:
server.port and server.address as required (note this is for the API, not the RTR protocol). server.address= listens on all interfaces.rtr.server.address and rtr.server.port as required (this is the RTR protocol). rtr.server.address=:: listens on all interfaces.You should now be able to start the Validator and RTR daemons:
# as the RIPE user\nsu - ripe\n\ncd /srv/ripe-rpki-validator/rpki-validator-3\n./rpki-validator-3.sh\n\ncd /srv/ripe-rpki-validator/rpki-rtr-server-3\n./rpki-rtr-server.sh\nWe need to manually install the ARIN TAL by:
/srv/ripe-rpki-validator/rpki-validator-3/upload-tal.sh arin-ripevalidator.tal http://localhost:8080/\nWe use systemd to ensure both daemons start automatically:
cat <<ENDL >/etc/systemd/system/rpki-validator-3.service\n[Unit]\nDescription=RPKI Validator\nAfter=network.target\n\n[Service]\nEnvironment=JAVA_CMD=/usr/bin/java\nExecStart=/srv/ripe-rpki-validator/rpki-validator-3/rpki-validator-3.sh\n\n# prevent restart in case there's a problem\n# with the database or binding to socket\nRestartPreventExitStatus=7\n\nUser=ripe\n\n[Install]\nWantedBy=multi-user.target\nENDL\n\nsystemctl enable rpki-validator-3.service\nsystemctl start rpki-validator-3.service\n\n\ncat <<ENDL >/etc/systemd/system/rpki-rtr-server-3.service\n[Unit]\nDescription=RPKI RTR\nAfter=rpki-validator-3.service\n\n[Service]\nEnvironment=JAVA_CMD=/usr/bin/java\nExecStart=/srv/ripe-rpki-validator/rpki-rtr-server-3/rpki-rtr-server.sh\n\n# prevent restart in case there's a problem\n# with the database or binding to socket\nRestartPreventExitStatus=7\n\nUser=ripe\n\n[Install]\nWantedBy=multi-user.target\nENDL\n\nsystemctl enable rpki-rtr-server-3.service\nsystemctl start rpki-rtr-server-3.service\nYou can see log messages using:
cat /var/log/syslog | grep rpki-validator\ncat /var/log/syslog | grep rpki-rtr\nWe separately add the server and the RIPE daemons to our standard monitoring and alerting tools.
"},{"location":"features/rpki/routinator/","title":"Routinator 3000","text":"Routinator 3000 is a RPKI relying party software (aka RPKI Validator) written in Rust by the good folks at NLnet Labs. These instructions reflect Routinator 0.8.2 (on Ubuntu 20.04). This mostly follows their own GitHub instructions and documentation.
We use a standard Ubuntu 20.04 installation (selecting the minimal virtual server option), 2 vCPUs, 2GB RAM, 20GB LVM hard drive.
Add the apt repo to the system by creating a file called /etc/apt/sources.list.d/routinator.list with the following contents:
deb [arch=amd64] https://packages.nlnetlabs.nl/linux/debian/ stretch main\ndeb [arch=amd64] https://packages.nlnetlabs.nl/linux/debian/ buster main\ndeb [arch=amd64] https://packages.nlnetlabs.nl/linux/ubuntu/ xenial main\ndeb [arch=amd64] https://packages.nlnetlabs.nl/linux/ubuntu/ bionic main\ndeb [arch=amd64] https://packages.nlnetlabs.nl/linux/ubuntu/ focal main\nThen add the NLNetLabs package key to the system:
sudo apt update && apt-get install -y gnupg2\nwget -qO- https://packages.nlnetlabs.nl/aptkey.asc | sudo apt-key add -\nsudo apt update\nNote that the first apt update will return a bunch of errors. The second update should run without errors, once the key has been added.
We then install the required software:
sudo apt install routinator\nsudo routinator-init\nAlternatively, if you plan to agree with the ARIN RPA, run:
sudo routinator-init --accept-arin-rpa\nBy default, Routinator listens only on TCP sockets on 127.0.0.1. If you want other devices to be able to access the service, it needs to listen to the wildcard socket.
If you're running Linux, you can configure Routinator to listen to both ipv4 and ipv6 wildcard sockets using the following configuration lines in /etc/routinator/routinator.conf:
rtr-listen = [ \"[::]:3323\" ]\nhttp-listen = [ \"[::]:8080\" ]\nIf you're running an operating system other than Linux, you'll need separate entries for ipv4 and ipv6:
rtr-listen = [ \"127.0.0.1:3323\", \"[::]:3323\" ]\nhttp-listen = [ \"127.0.0.1:8080\", \"[::]:8080\" ]\nYou can then test by running the following command, which prints the validated ROA payloads and increases the log level to show the process in detail:
/usr/bin/routinator --config /etc/routinator/routinator.conf -v vrps\nTo have this service start at boot:
systemctl enable routinator\nsystemctl start routinator\nWe add Nagios http checks for port 8080 (HTTP) to our monitoring platform. We also add a check_tcp test for the RPKI-RTR port 3323.
The following is copied from Routinator's man page. As a future work fixme, this should be used for better monitoring that just check_tcp above.
HTTP SERVICE\n Routinator can provide an HTTP service allowing to fetch the Validated\n ROA Payload in various formats. The service does not support HTTPS and\n should only be used within the local network.\n\n The service only supports GET requests with the following paths:\n\n\n /metrics\n Returns a set of monitoring metrics in the format used by\n Prometheus.\n\n /status\n Returns the current status of the Routinator instance. This is\n similar to the output of the /metrics endpoint but in a more\n human friendly format.\n\n /version\n Returns the version of the Routinator instance.\n\n /api/v1/validity/as-number/prefix\n Returns a JSON object describing whether the route announcement\n given by its origin AS number and address prefix is RPKI valid,\n invalid, or not found. The returned object is compatible with\n that provided by the RIPE NCC RPKI Validator. For more informa-\n tion, see https://www.ripe.net/support/documentation/developer-\n documentation/rpki-validator-api\n\n /validity?asn=as-number&prefix=prefix\n Same as above but with a more form-friendly calling convention.\n\n\n In addition, the current set of VRPs is available for each output for-\n mat at a path with the same name as the output format. E.g., the CSV\n output is available at /csv.\n\n These paths accept filter expressions to limit the VRPs returned in the\n form of a query string. The field filter-asn can be used to filter for\n ASNs and the field filter-prefix can be used to filter for prefixes.\n The fields can be repeated multiple times.\n\n This works in the same way as the options of the same name to the vrps\n command.\nThe OpenBSD project created a free and easy-to-use RPKI validator named rpki-client.
Deployment is split into two elements:
We use a standard Debian Sid (unstable) installation, 2 vCPUs, 2GB RAM, 20GB LVM hard drive. Debian provides pre-built packages for installation.
As of early March 2024, the following packages can easily be installed:
$ sudo apt install rpki-client stayrtr\nYou'll need to confirm whether you'd like to install the ARIN TAL.
You can now run the validator via the following command:
"},{"location":"features/rpki/rpkiclient/#rpki-client","title":"rpki-client","text":"# start the service:\nsystemctl start rpki-client &\n\n# see and tail the logs\njournalctl -fu rpki-client\nRunning rpki-client the first time might take a few minutes.
"},{"location":"features/rpki/rpkiclient/#stayrtr","title":"StayRTR","text":"To start StayRTR (once rpki-client is configured and running), we first edit /etc/default/stayrtr:
STAYRTR_ARGS=-bind :3323 -cache /var/lib/rpki-client/json -metrics.addr :8082\nYou can now run the StayRTR daemon via the following command:
# start the service:\nsystemctl restart stayrtr\n\n# see and tail the logs\njournalctl -fu stayrtr\nOnce rpki-client completed its initial run, and StayRTR starts up, metrics are available from http://[hostname/ip address]:8082/metrics.
"},{"location":"features/rpki/rpkiclient/#monitoring","title":"Monitoring","text":"We add Nagios http checks for and 8082 (StayRTR) to our monitoring platform. We also add a check_tcp test for StayRTR port 3323.
Rpki-client produces a statistics file in OpenMetrics format in /var/lib/rpki-client/metrics for use with Grafana.
This page discusses default permissions required for accessing certain graphs and well as details on how to change that.
"},{"location":"grapher/api/#accessibility-of-aggregate-graphs","title":"Accessibility of Aggregate Graphs","text":"By default, the following graphs are publicly accessible in IXP Manager and available through the top menu under Statistics:
If you wish to limit access to these to a less than or equal user permission, set the following in .env appropriately:
GRAPHER_ACCESS_IXPGRAPHER_ACCESS_INFRASTRUCTUREGRAPHER_ACCESS_LOCATIONGRAPHER_ACCESS_VLANGRAPHER_ACCESS_SWITCHGRAPHER_ACCESS_TRUNK (this also applies to core bundles)For example to limit access to trunks / core bundles to logged in users, set:
GRAPHER_ACCESS_TRUNK=1\nIf you would like to make the aggregate graphs available to logged in users only, set the following .env options:
GRAPHER_ACCESS_IXP=1\nGRAPHER_ACCESS_INFRASTRUCTURE=1\nGRAPHER_ACCESS_VLAN=1\nGRAPHER_ACCESS_SWITCH=1\nGRAPHER_ACCESS_LOCATION=1\nGRAPHER_ACCESS_TRUNK=1\nIf you would prefer to restrict access to these to superusers / admins only, replace =1 above with =3.
Grapher allows API access to graphs via a base URL of the form:
https://ixp.example.com/grapher/{graph}[?id=x][&period=x][&type=x][&category=x] \\\n [&protocol=x][&backend=x]\nHere's two quick examples from INEX's production system:
id=1&type=png).A sample of the JSON output is:
{\n \"class\": \"ixp\",\n \"urls\": {\n \"png\": \"https:\\/\\/www.inex.ie\\/ixp\\/grapher\\/ixp?period=day&type=png&category=bits&protocol=all&id=1\",\n \"log\": \"https:\\/\\/www.inex.ie\\/ixp\\/grapher\\/ixp?period=day&type=log&category=bits&protocol=all&id=1\",\n \"json\": \"https:\\/\\/www.inex.ie\\/ixp\\/grapher\\/ixp?period=day&type=json&category=bits&protocol=all&id=1\"\n },\n \"base_url\": \"https:\\/\\/www.inex.ie\\/ixp\\/grapher\\/ixp\",\n \"statistics\": {\n \"totalin\": 15013439801606864,\n \"totalout\": 15013959560329200,\n \"curin\": 158715231920,\n \"curout\": 158713872624,\n \"averagein\": 125566129180.59367,\n \"averageout\": 125570476225.09074,\n \"maxin\": 222438012592,\n \"maxout\": 222348641336\n },\n \"params\": {\n \"type\": \"json\",\n \"category\": \"bits\",\n \"period\": \"day\",\n \"protocol\": \"all\",\n \"id\": 1\n },\n \"supports\": {\n \"protocols\": {\n \"all\": \"all\"\n },\n \"categories\": {\n \"bits\": \"bits\",\n \"pkts\": \"pkts\"\n },\n \"periods\": {\n \"day\": \"day\",\n \"week\": \"week\",\n \"month\": \"month\",\n \"year\": \"year\"\n },\n \"types\": {\n \"png\": \"png\",\n \"log\": \"log\",\n \"json\": \"json\"\n }\n },\n \"backends\": {\n \"mrtg\": \"mrtg\"\n },\n \"backend\": \"mrtg\"\n}\nYou can see from the above what params were used to create the statistics (and would be used for the image if type=png), what parameters are supported (supports), what backends are available for the given graph type and mix of parameters, etc.
Notes:
json type to see what's supported but remember that IXP Manager will, when configured correctly, chose the appropriate backend;Let's first look at supported graphs:
ixp: aggregate graph for an IXP's overall traffic. id, which defaults to 1, is the primary key of the IXP from the ixp database table. As IXP Manager does not support multiple IXPs, this defaults to id=1. [Currently only supported via MRTG for protocol=all]
infrastructure: aggregate graph for the overall traffic on a specific IXP infrastructure. For many IXPs, they'll just have a single infrastructure and this will go unused as it would be the equivalent of ixp above. id, which is mandatory, is the primary key of the infrastructure from the infrastructure database table. [Currently only supported via MRTG for protocol=all]
vlan: aggregate graph for a specific VLAN. id, which is mandatory, is the primary key of the VLAN from the vlan database table. [Currently only supported via sflow for protocol=ipv4|ipv6 and category=bits|pkts]
location: aggregate graph of all peering traffic being switched by a specific facility (sum of all customer ports not including core ports). id, which is mandatory, is the primary key of the location / facility from the location database table. [Currently only supported via MRTG for protocol=all]. *Note that we are looking at all traffic originating and/or terminating at a location rather than traffic passing through it.
switch: aggregate graph of all peering traffic being switched by a specific switch (sum of all customer ports plus core ports). id, which is mandatory, is the primary key of the switch from the switch database table. [Currently only supported via MRTG for protocol=all]
core-bundle: inter-switch / trunk graphs configured in IXP Manager using the Core Bundles tool. The id is mandatory and is the database ID of the core bundle. An additional parameter is supported also: &side=a or &side=b which determines which side of the core bundle you want to graph. This parameter is optional and defaults to a. Each side of the graph will be about identical (only differing by MRTG polling time) but with tx/rx reversed. Access is determined using the GRAPHER_ACCESS_TRUNK.
trunk: a legacy hold over from Inter-Switch / Trunk Graphs above to be replaced with core bundles.
physicalinterface: traffic for an individual member port - a single physical switch port. id, which is mandatory, is the primary key of the physical interface from the physicalinterface database table. [Currently only supported via MRTG for protocol=all]
virtualinterface: if a member has a single connection (one switch port) then this is the same as physicalinterface above. However, if they have a LAG port then it's the aggregate traffic for all physical ports in the LAG. id, which is mandatory, is the primary key of the virtual interface from the virtualinterface database table. [Currently only supported via MRTG for protocol=all]
customer: the aggregate traffic for all ports belonging to a customer across all infrastructures. id, which is mandatory, is the primary key of the customer from the cust database table. [Currently only supported via MRTG for protocol=all]
vlaninterface: aggregate traffic flowing through a members VLAN interface for a specific protocol. id, which is mandatory, is the primary key of the VLAN interface from the vlaninterface database table. [Currently only supported via sflow for protocol=ipv4|ipv6]
latency: latency graphs (e.g. Smokeping). id, which is mandatory, is the primary key of the VLAN interface from the vlaninterface database table. protocol=ipv4|ipv6 is also mandatory. Periods for Smokeping are different to the default periods and should be one of 3hours|30hours|10days|1year.
p2p: peer to peer traffic between two member VLAN interfaces. The source (svli) and destination (dvli) VLAN interface IDs are required. svli and dvli, which are mandatory, are primary keys of the VLAN interfaces from the vlaninterface database table. [Currently only supported via sflow for protocol=ipv4|ipv6]
For additional options, it's always best to manually or programmatically examine the output for type=json to see what is supported. The following is a general list.
type: one of:
json - as demonstrated and described above;log - MRTG log file type output formatted as a JSON array;rrd - the RRD file for the requested graph type;png - the graph image itself (default).period: one of day, week, month, year (except for latency graphs as described above).
category: one of bits, pkts (packets), errs (errors), discs (discards), bcasts (broadcasts). Bits is measured in bits per second, the rest in packets per second.
protocol: one of all, ipv4 or ipv6.
backend: default is to let IXP Manager decide.
The grapher API can be accessed using the standard API access mechanisms.
Each graph (ixp, infrastructure, etc.) has an authorise() method which determines who is allowed view a graph. For example, see IXP\\Services\\Grapher\\Graph\\VlanInterface::authorise(). The general logic is:
For the supported graph types, default access control is:
Graph Default Access Controlixp public but respects GRAPHER_ACCESS_IXP (see above) infrastructure public but respects GRAPHER_ACCESS_INFRASTRUCTURE (see above) vlan public but respects GRAPHER_ACCESS_VLAN (see above), unless it's a private VLAN (in which case only superuser is supported currently) location public but respects GRAPHER_ACCESS_LOCATION (see above) switch public but respects GRAPHER_ACCESS_SWITCH (see above) core-bundle public but respects GRAPHER_ACCESS_TRUNK (see above) trunk public but respects GRAPHER_ACCESS_TRUNK (see above) physicalinterface superuser or user of the owning customer but respects GRAPHER_ACCESS_CUSTOMER (see Access to Member Graphs below) vlaninterface superuser or user of the owning customer but respects GRAPHER_ACCESS_CUSTOMER (see Access to Member Graphs below) virtualinterface superuser or user of the owning customer but respects GRAPHER_ACCESS_CUSTOMER (see Access to Member Graphs below) customer superuser or user of the owning customer but respects GRAPHER_ACCESS_CUSTOMER (see Access to Member Graphs below) latency superuser or user of the owning customer but respects GRAPHER_ACCESS_LATENCY (see Access to Member Graphs below) p2p superuser or user of the source (svli) owning customer but respects GRAPHER_ACCESS_P2P (see Access to Member Graphs below)"},{"location":"grapher/api/#access-to-member-graphs","title":"Access to Member Graphs","text":"NB: before you read this section, please first read and be familiar with the Accessibility of Aggregate Graphs section above.
A number of IXPs have requested a feature to allow public access to member / customer graphs. To support this we have added the following .env options (beginning in v4.8) with the default value as shown:
GRAPHER_ACCESS_CUSTOMER=\"own_graphs_only\"\nGRAPHER_ACCESS_P2P=\"own_graphs_only\"\nGRAPHER_ACCESS_LATENCY=\"own_graphs_only\"\nThe own_graphs_only setting just means perform the default access checks which are: access is granted to a superuser or a user who belongs to the customer which owns the respective graph. I.e. no one but the customer or a superadmin can access the respective graph.
If you wish to allow access to these to a less than or equal user permission, set the above in .env appropriately.
For example:
then set the following in .env:
GRAPHER_ACCESS_CUSTOMER=0\nGRAPHER_ACCESS_P2P=1\nNote that GRAPHER_ACCESS_LATENCY is omitted as we are not changing the default.
Please note the following:
GRAPHER_ACCESS_CUSTOMER applies to customer aggregate graphs, customer LAG graphs (virtualinterface), customer ports (physicalinterface) and customer vlaninterface. T individually limit these makes little sense and drastically increases complexity (from a UI perspectve).GRAPHER_ACCESS_P2P or GRAPHER_ACCESS_LATENCY without enabling equivalent or less restrictive access to GRAPHER_ACCESS_CUSTOMER. This is because most of the user interface (UI) pathways to access these is via GRAPHER_ACCESS_CUSTOMER pages.IXP Manager generates all of its graphs using its own graphing system called Grapher. This was introduced in v4.
Grapher is a complete rewrite of all previous graphing code and includes:
To date, we have developed the following reference backend implementations:
dummy - a dummy grapher that just provides a placeholder graph for all possible graph types;mrtg - MRTG graphing using either the log or rrd backend. Use cases for MRTG are L2 interface statistics for bits / packets / errors / discards / broadcasts per second. Aggregate graphs for customer LAGs, overall customer traffic, all traffic over a switch / infrastructure / the entire IXP are all supported;sflow - while the MRTG backend looks at layer 2 statistics, sflow is used to provide layer 3 statistics such as per protocol (IPv4/6) graphs and peer to peer graphs;smokeping - (available from v4.8.0) which creates latency graphs and this replaces the previous way we used to access Smokeping graphs.In a typical production environment, you would implement MRTG, Smokeping and sflow to provide the complete set of features.
"},{"location":"grapher/introduction/#configuration","title":"Configuration","text":"There are only a handful of configuration options required and a typical and complete $IXPROOT/.env would look like the following:
GRAPHER_BACKENDS=\"mrtg|sflow|smokeping\"\nGRAPHER_CACHE_ENABLED=true\n\nGRAPHER_BACKEND_MRTG_DBTYPE=\"rrd\"\nGRAPHER_BACKEND_MRTG_WORKDIR=\"/srv/mrtg\"\nGRAPHER_BACKEND_MRTG_LOGDIR=\"/srv/mrtg\"\n\nGRAPHER_BACKEND_SFLOW_ENABLED=true\nGRAPHER_BACKEND_SFLOW_ROOT=\"http://sflow-server.example.com/grapher-sflow\"\n\nGRAPHER_BACKEND_SMOKEPING_ENABLED=true\nGRAPHER_BACKEND_SMOKEPING_URL=\"http://smokeping-server.example.com/smokeping\"\nFor those interested, the complete Grapher configuration file can be seen in $IXPROOT/config/grapher.php. Remember: put your own local changes in .env rather than editing this file directly.
The global (non-backend specific) options are:
GRAPHER_BACKENDS - in a typical production environment this would be \"mrtg|sflow|smokeping\" which means try the MRTG backend first, then sflow and then smokeping. We ship with this set as \"dummy\" so you can see sample graphs working out of the box.GRAPHER_CACHE_ENABLED - the IXP industry standard for graphing is to graph at 5min intervals. With the cache enabled, IXP Manager does not have to regenerate / reload / reprocess log / rrd / image files if we have cached them and they are less than 5mins old. This is enabled by default which is the recommended setting.Backend specific configuration and set-up instructions can be found in their own sections below.
"},{"location":"grapher/mrtg/","title":"Backend: MRTG","text":"MRTG is used to generate interface graphs. MRTG is a particularly efficient SNMP poller as, irrespective of how many times an interface is referenced for different graphs, it is only polled once per run. If you want to understand MRTG related options in this section, please refer to MRTG's own documentation.
Per-second graphs are generated for bits, packets, errors, discards and broadcasts at 5min intervals. IXP Manager's Grapher system can use MRTG to poll switches and create traffic graphs for:
Aggregate IXP and Infrastructure Graphs
The MRTG script creates aggregate graphs for the entire IXP as well as per-infrastructure graphs. These graphs are available from the Statistics menu under Overall Peering Graphs. Also, the graphs on the admin dashboard are versions of these.
IXP and infrastructure graphs are aggregate graphs of edge / member ports only. It is the aggregate of traffic exchanged between the members of the IXP and thus does not include core / trunk ports between switches.
You'll find examples of IXP graphs and infrastructure graphs on INEX's own IXP Manager where they are public be default.
Per-Facility Aggregate Graphs
These are defined and built automatically from the locations / facilities you have defined and the switches you have assigned to them. These graphs are available from the Statistics menu under Facility Aggregate Graphs.
These graphs are the aggregate of all peering ports excluding core/trunk ports in a given location / facility. It is the aggregate of traffic originating and/or terminating in a location rather than traffic simply passing through a location.
You'll find examples of facility graphs on INEX's own IXP Manager where they are public be default.
Switch Aggregate Graphs
These are defined and built automatically from the switches you have defined. These graphs are available from the Statistics menu under Switch Aggregate Graphs.
These graphs are the aggregate of all peering ports and core/trunk ports on a given switch. It is the aggregate of traffic being exchanged across a given switch.
You'll find examples of switch graphs on INEX's own IXP Manager where they are public be default.
Inter-Switch / Trunk Graphs
From IXP Manager v6, this is now handled via Core Bundles. Please see the graphing section of the core bundles page for details.
For older versions of IXP Manager, it can be done manually via the config/grapher_trunks.php.dist file. This is now deprecated and will be removed during the lifetime of the v6 release.
In either case, these graphs will be available in the Statistics menu. You can see examples from INEX here.
Customer Graphs
MRTG creates: per port (physical interface); per LAG (virtual interface); and per customer aggregate graphs for each member / customer.
You need to install some basic packages for MRTG to work - on Ubuntu for example, install:
apt install rrdtool mrtg\nYou also need a folder to store all MRTG files. For example:
mkdir -p /srv/mrtg\nIn your `.env, you need to set the following options:
# The MRTG database type to use - either log or rrd:\nGRAPHER_BACKEND_MRTG_DBTYPE=\"rrd\"\n\n# Where to store log/rrd/png files. This is from the perspective\n# of the mrtg daemon and it is only used when generating the mrtg configuration\n# file so this should be a local path on whatever server mrtg will run:\nGRAPHER_BACKEND_MRTG_WORKDIR=\"/srv/mrtg\"\n\n# Where IXP Manager can fine the GRAPHER_BACKEND_MRTG_WORKDIR above. If mrtg is\n# running on the same server as IXP Manager, this this would just be the same:\nGRAPHER_BACKEND_MRTG_LOGDIR=\"/srv/mrtg\"\n# Note that if you wish to run MRTG on another server, you can expose the\n# WORKDIR on a HTTP server and provide a URL to this option:\n# GRAPHER_BACKEND_MRTG_LOGDIR=\"http://collector.example.com/mrtg\"\nYou can now generate a MRTG configuration by executing a command such as:
# Move to the directory where you have installed IXP Manager (typically: /srv/ixpmanager)\ncd $IXPROOT\n\n# Generate MRTG configuration and output to stdout:\nphp artisan grapher:generate-configuration -B mrtg\n\n# Generate MRTG configuration and output to a named file:\nphp artisan grapher:generate-configuration -B mrtg -O /tmp/mrtg.cfg.candidate\nYou could also combine a syntax check before putting the resultant file live. Here's a complete example that could be run via cron:
#! /usr/bin/env bash\n\n# Set this to the directory where you have installed IXP Manager (typically: /srv/ixpmanager)\nIXPROOT=/srv/ixpmanager\n\n# Temporary configuration file:\nTMPCONF=/tmp/mrtg.cfg.$$\n\n# Synchronize configuration files\n${IXPROOT}/artisan grapher:generate-configuration -B mrtg -O $TMPCONF\n\n# Remove comments and date/time stamps for before comparing for differences\ncat /etc/mrtg.cfg | egrep -v '^#.*$' | \\\n egrep -v '^[ ]+Based on configuration last generated by.*$' >/tmp/mrtg.cfg.filtered\ncat $TMPCONF | egrep -v '^#.*$' | \\\n egrep -v '^[ ]+Based on configuration last generated by.*$' >${TMPCONF}.filtered\ndiff /tmp/mrtg.cfg.filtered ${TMPCONF}.filtered >/dev/null\nDIFF=$?\n\nrm /tmp/mrtg.cfg.filtered\nrm ${TMPCONF}.filtered\n\nif [[ $DIFF -eq 0 ]]; then\n rm ${TMPCONF}\n exit 0\nfi\n\n/usr/bin/mrtg --check ${TMPCONF} \\\n && /bin/mv ${TMPCONF} /etc/mrtg.cfg \\\n && /etc/rc.d/mrtg_daemon restart > /dev/null\nIf your MRTG collector is on a different server, you could use a script such as the following to safely update MRTG via IXP Manager's API.
#! /usr/bin/env bash\n\n# Temporary configuration file:\nTMPCONF=/etc/mrtg.cfg.$$\n\n# Download the configuration via the API. Be sure to replace 'your_api_key'\n# with your actual API key (see API documentation).\ncurl --fail -s -H \"X-IXP-Manager-API-Key: your_api_key\" \\\n https://ixp.example.com/api/v4/grapher/mrtg-config >${TMPCONF}\n\nif [[ $? -ne 0 ]]; then\n echo \"WARNING: COULD NOT FETCH UP TO DATE MRTG CONFIGURATION!\"\n exit -1\nfi\n\ncd /etc\n\n# Remove comments and date/time stamps for before comparing for differences\ncat mrtg.cfg | egrep -v '^#.*$' | \\\n egrep -v '^[ ]+Based on configuration last generated by.*$' >mrtg.cfg.filtered\ncat ${TMPCONF} | egrep -v '^#.*$' | \\\n egrep -v '^[ ]+Based on configuration last generated by.*$' >${TMPCONF}.filtered\ndiff mrtg.cfg.filtered ${TMPCONF}.filtered >/dev/null\nDIFF=$?\n\nrm mrtg.cfg.filtered\nrm ${TMPCONF}.filtered\n\nif [[ $DIFF -eq 0 ]]; then\n rm ${TMPCONF}\n exit 0\nfi\n\n/usr/bin/mrtg --check ${TMPCONF} && /bin/mv ${TMPCONF} /etc/mrtg.cfg\n\n\n\n/usr/bin/mrtg --check ${TMPCONF} \\\n && /bin/mv ${TMPCONF} /etc/mrtg.cfg \\\n && /etc/rc.d/mrtg_daemon restart > /dev/null\nNote that the MRTG configuration that IXP Manager generates instructs MRTG to run as a daemon. On FreeBSD, MRTG comes with an initd script by default and you can kick it off on boot with something like the following in /etc/rc.conf:
mrtg_daemon_enable=\"YES\"\nmrtg_daemon_config=\"/etc/mrtg.cfg\"\nOn Ubuntu it does not but it comes with a /etc/cron.d/mrtg file which kicks it off every five minutes (it will daemonize the first time and further cron jobs will have no effect).
Marco d'Itri provided Ubuntu / Debian compatible systemd configurations for mrtg which you can find detailed in this Github issue.
To start and stop it via the older initd scripts on Ubuntu, use an initd script such as this: ubuntu-mrtg-initd (source):
cp ${IXPROOT}/tools/runtime/mrtg/ubuntu-mrtg-initd /etc/init.d/mrtg\nchmod +x /etc/init.d/mrtg\nupdate-rc.d mrtg defaults\n/etc/init.d/mrtg start\nAnd disable the default cron job for MRTG on Ubuntu (/etc/cron.d/mrtg).
Generally speaking, you should not customize the way IXP Manager generates MRTG configuration as the naming conventions are tightly coupled to how IXP Manager fetches the graphs. However, if there are bits of the MRTG configuration you need to alter, you can do it via skinning. The skinning documentation actually uses MRTG as an example.
"},{"location":"grapher/mrtg/#inserting-traffic-data-into-the-database-reporting-emails","title":"Inserting Traffic Data Into the Database / Reporting Emails","text":"The MRTG backend inserts daily summaries into MySQL for reporting. See the traffic_daily and traffic_daily_phys_ints database tables for this. Essentially, there is a row per day per customer in the first and a row per physical interface in the second for traffic types bits, discards, errors, broadcasts and packets. Each row has a daily, weekly, monthly and yearly value for average, max and total.
From IXP Manager >= v5.0, the task scheduler handles collecting and storing yesterday's data. If you are using an older version, create a cron job such as:
0 2 * * * www-data /srv/ixpmanager/artisan grapher:upload-stats-to-db\n5 2 * * * www-data /srv/ixpmanager/artisan grapher:upload-pi-stats-to-db\nIn the IXP Manager application, the traffic_daily data powers the League Table function and the traffic_daily_phys_int data powers the Utilisation (since v5.5.0) function - both on the left hand menu.
This data is also used to send email reports / notifications of various traffic events. A sample crontab for this would look like the following:
0 4 * * * www-data /srv/ixpmanager/artisan grapher:email-traffic-deltas \\\n --stddev=1.5 -v user1@example.com,user2@example.com\n\n30 10 * * tue www-data /srv/ixpmanager/artisan grapher:email-port-utilisations \\\n --threshold=80 user1@example.com,user2@example.com\n\n31 10 * * * www-data /srv/ixpmanager/artisan grapher:email-ports-with-counts \\\n --discards user1@example.com,user2@example.com\n\n32 10 * * * www-data /srv/ixpmanager/artisan grapher:email-ports-with-counts \\\n --errors user1@example.com,user2@example.com\nWhich, in the order above, do:
traffic_daily_phys_ints table).This generated emails are HTML formatted with embedded graph images.
"},{"location":"grapher/mrtg/#port-utilisation","title":"Port Utilisation","text":"In IXP Manager v5.5.0, we introduced a port utilisation reporting function into IXP Manager's frontend UI. You will find it in the IXP STATISTICS section of the left hand side menu.
The purpose of this tool is to easily identify ports that are nearing or exceeding 80% utilisation. In its default configuration, IXP Manager will iterate over all the physical interface (switch ports) MRTG log files for every member and insert that information into the database at 02:10 (AM).
In the UI, when you select a specific date and period (day/week/month/year), you are shown the maximum port utilisation (in and out) for the given period up to 02:10 on that day.
This feature was introduced in March 2020 during the Coronavirus outbreak. After observing as much as 50% routine traffic increases across IXPs in areas under lock down, we needed a tool that would allow us to rapidly and easily view port utilisations across all members rather than looking at member graphs individually.
"},{"location":"grapher/mrtg/#troubleshooting","title":"Troubleshooting","text":""},{"location":"grapher/mrtg/#general-notes","title":"General Notes","text":"A common issue raised on the mailing list is missing customer graphs. The code which generates MRTG configuration is in the MRTG backend file (see the function getPeeringPorts()).
The conditions for a physical interface allocated to a customer to make the configuration file are:
If you are not sure about how ports are configured in IXP Manager, please see the interfaces document.
You can check the physical interface state by:
You can ensure a switch is active by:
Instructions for configuring the IXP Manager sflow integration can be found on the Sflow Introduction and Sflow peer-to-peer pages.
"},{"location":"grapher/smokeping/","title":"Backend: Smokeping","text":"Latency graphs are a tool for monitoring latency / packet loss to the routers of IXP partipants and they can be an invaluable asset when diagnosing many IXP issues.
While they should never be used as a tool for monitoring IXP latency or packet loss (as routers de-prioritise ICMP requests and/or may not have a suitably powerful management plane), they can act as an extremely useful tool for identifying and diagnosing customer / member issues. What we really look for here is recent changes over time.
IXP Manager can configure Smokeping to monitor member routers and display those graphs in member statistic pages. Presuming it is installed.
"},{"location":"grapher/smokeping/#historical-notes","title":"Historical Notes","text":"If you have used Smokeping on IXP Manager <v4.5 or between v4.5 and v4.7.3, then how the configuration is generated has changed.
This section explains the rules on how a member router (target) is selected to be included in the generated Smokeping configuration.
When generating a list of targets per VLAN and protocol, the API call to IXP Manager will select all VLAN interfaces (member routers) where:
You can use the IXP Manager API to get the Smokeping target configurations for a given VLAN and protocol using the following endpoint format (both GET and POST requests work):
https://ixp.example.com/api/v4/grapher/config?backend=smokeping&vlanid=10&protocol=ipv4\nNote that in versions of IXP Manager between v4.5 and v4.7.3, this was: https://ixp.example.com/api/v4/vlan/smokeping/{vlanid}/{protocol}.
In the above, the parameters are:
vlanid is the database ID (DB ID) of the VLAN. You can find the DB ID in IXP Manager in the VLAN table (select VLANs from the left hand side menu).protocol is either ipv4 or ipv6 (while in versions between v4.5 and v4.7.3, these were just 4 and 6 respectfully).If either of these are invalid, the API will return with a HTTP 404 response.
And example of a Smokeping target in the response is:
# AS112 Reverse DNS / 185.6.36.6\n+++ vlanint_86_ipv4\nmenu = AS112 Reverse DNS (IPv4)\ntitle = Peering VLAN #1 :: AS112 Reverse DNS via 185.6.36.6\nprobe = FPing\nhost = 185.6.36.6\nYou can optionally POST any of the above parameters and none, one or both of the following to change elements of the default template:
level: the Smokeping level / hierarchy of the target. Defaults to +++.probe: the probe to use when measuring latency to the target. Defaults for FPing for IPv4 and FPing6 for IPv6.An example of changing these parameters is:
curl --data \"backend=smokeping&protocol=ipv4&vlanid=10&level=%2B%2B&probe=MyPing\" -X POST \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"X-IXP-Manager-API-Key: my-ixp-manager-api-key\" \\\n https://ixpexample.com/api/v4/grapher/config\nYou can use skinning to make changes to the bundled default template or, preferably, add your own.
Let's say you wanted to add your own template called mytemplate1 and your skin is named myskin. The best way to proceed is to copy the bundled example:
cd $IXPROOT\nmkdir -p resources/skins/myskin/services/grapher/smokeping\ncp resources/views/services/grapher/smokeping/default.foil.php \\\n resources/skins/myskin/services/grapher/smokeping/mytemplate1.foil.php\nYou can now edit this template as required. The only constraint on the template name is it can only contain characters from the classes a-z, 0-9, -. NB: do not use uppercase characters.
The following variables are available in the template:
$t->vlis: array of the VLAN interfaces/targets - it is generated by the Repositories\\VlanInterface::getForProto() function.$t->vlan: instance of the Vlan entity object.$t->protocol: either 4 or 6.$t->probe and $t->level as defined above / passed via a post request.This section explains how to set up Smokeping with IXP Manager. We assume you already have a base install of Smokeping.
"},{"location":"grapher/smokeping/#generating-updating-targets","title":"Generating / Updating Targets","text":"At INEX, we would use a script such as this one which is bundled with IXP Manager to (re)generate our targets by cron and update Smokeping if necessary.
To use this script yourself, you just need to copy it to the appropriate Smokeping server and edit the first few lines:
KEY=\"my-ixp-manager-api-key\"\nURL=\"https://ixp.example.com/api/v4/grapher/config?backend=smokeping\"\nETCPATH=\"/etc/smokeping\"\nSMOKEPING=\"/usr/bin/smokeping\"\nSMOKEPING_RELOAD=\"/etc/rc.d/smokeping reload\"\nVLANS=\"1 2\"\nPROTOCOLS=\"ipv4 ipv6\"\nwhere:
KEY is your IXP Manager API key.URL is the API endpoint as described above.ETCPATH is where the script puts the target files (named $ETCPATH/targets-vlan${vlanid}-${proto}.cfg)SMOKEPING is the Smokeping binary command. Just used to validate the config with --check before reloading.SMOKEPING_RELOAD - the command to reload Smokeping.VLANS - space separated list of VLAN DB IDs as described above. You probably only have one of these typically.PROTOCOLS - the protocols to generate the configuration for.The script iterates over the VLAN IDs and protocols to create the individual configuration files.
"},{"location":"grapher/smokeping/#using-targets-in-smokeping","title":"Using Targets in Smokeping","text":"Once the above target file(s) are created, we can use them in our standard Smokeping configuration file as follows:
+ infra_1\nmenu = IXP Infrastructure 1\ntitle = IXP Infrastructure 1\n\n\n++ vlan_1\nmenu = Peering VLAN 1\ntitle = IXP Infra 1 :: Peering VLAN 1\n\n\n@include targets-vlan1-ipv4.cfg\n@include targets-vlan1-ipv6.cfg\nYou need to be able to configure IXP Manager with the base Smokeping URL such as http://www.example.com/smokeping. This should be the URL to the standard entry page to Smokeping.
IXP Manager will add the trailing slash and assume the directory index is configured for the CGI script. Thus you need an Apache configuration such as:
ScriptAlias /smokeping/smokeping.cgi /usr/lib/cgi-bin/smokeping.cgi\nAlias /smokeping /usr/share/smokeping/www\n\n<Directory \"/usr/share/smokeping/www\">\n Options FollowSymLinks\n DirectoryIndex smokeping.cgi\n</Directory>\nOnce you have configured Smokeping and Apache/web server as above, you really just need to set the following in your IXP Manager .env file:
# Add smokeping to the grapher backends:\nGRAPHER_BACKENDS=\"...|smokeping|...\"\n\n# Mark it as enabled (this just affects whether certain UI elements are shown):\nGRAPHER_BACKEND_SMOKEPING_ENABLED=true\n\n# And set the default location to fetch the Smokeping graphs from:\nGRAPHER_BACKEND_SMOKEPING_URL=\"http://www.example.com/smokeping\"\nwhere the URL is as you set up in Apache above.
There may be instances where you have multiple VLANs where it is not possible to have a single Smokeping instance graph latency for all of them. Particularly as the Smokeping daemon for a given VLAN needs to have an interface / IP address on that VLAN.
INEX has such a situation where we have a regional exchange, INEX Cork, that is located in a different city to the main INEX LANs and IXP Manager. In this situation, you can configure Smokeping URL overrides on a per VLAN basis by creating a file called $IXPROOT/config/grapher_smokeping_overrides.php which returns an array as follows:
<?php\n\nreturn [\n\n 'per_vlan_urls' => [\n 2 => 'http://www.example.com/smokeping',\n 4 => 'http://www.example2.com/smokeping',\n ],\n\n];\nwhere the array index (2 and 4 in the above example) is the VLAN DB ID as explained above.
Any VLANs without a specific override configured in this way will fall back to the GRAPHER_BACKEND_SMOKEPING_URL setting.
When configured correctly, there will be a latency button available (clock icon) in the member graphs in both the member and admin sections.
"},{"location":"grapher/smokeping/#troubleshooting","title":"Troubleshooting","text":"See issue #122 for a discussion on Ubuntu installation and diagnosing issues in general (relates to IXP Manager v3 but may still be useful).
IXP Manager will call something like the following to fetch graphs from Smokeping:
file_get_contents( 'https://www.example.com/smokeping/?.....' )\nYou should see these requests to Smokeping in your Smokeping web server log files. Find these and compare them to the URLs that Smokeping itself generates for its own display of the images to ensure you have everything - and especially the Smokeping URL in IXP configuration set up correctly.
Also, try testing these URLs directly on the IXP Manager server via:
php -r 'echo file_get_contents( \"https://...\" );'\nWe've tried our best to make installing IXP Manager as easy as possible via the install script(s) we provide. These scripts are opinionated about what version of Linux is used and how IXP Manager is installed. It's targeted at people who don't have a huge amount of system administration skills or want to take a quick look to evaluate the product.
If you want to install on your own preferred platform or with your own tweaks, we provide detailed instructions below also but we only offer whatever support you'll find on the public mailing list.
The installation of IXP Manager doesn't end when you have the web interface up and running (which is mostly what we cover in this section and the installation script) - that's really just the beginning. Completing the installation is about all the features that work around and via IXP Manager such as route server configurations, graphing, peer to peer graphs via sflow, etc. Each of these require different amounts of effort and are covered in their individual feature pages.
"},{"location":"install/automated-script/","title":"Automated Installation Script","text":"The available installation script(s) can be found at: https://github.com/inex/IXP-Manager/tree/master/tools/installers.
Even if you choose not to use these, the scripts under the above link show the accurate and complete installation process and should be used as a reference guide.
What next? See our post-install / next steps document here.
"},{"location":"install/automated-script/#video-tutorial","title":"Video Tutorial","text":"We created a video tutorial demonstrating the installation process using the automated script for IXP Manager v5.5.0 (April 2020) on Ubuntu LTS 20.04.
The procedure is similar for v6.0 - just be sure to use the ubuntu-lts-2004-ixp-manager-v6.sh script.
You can find the video here in our YouTube channel. As always, the full catalog of video tutorials is here.
"},{"location":"install/considerations/","title":"Technical Considerations","text":"While most updates of IXP Manager are quick, some may be more involved with schema updates or complicated migration steps. In these cases it's useful and advisable to put IXP Manager in maintenance mode.
Maintenance mode is now handled by Laravel's built in tool for this. You can review their own documentation for this which us copied here.
When your application is in maintenance mode, a custom view will be displayed for all requests into your application. This makes it easy to \"disable\" your application while it is updating or when you are performing maintenance. A maintenance mode check is included in the default middleware stack for your application. If the application is in maintenance mode, a MaintenanceModeException will be thrown with a status code of 503.
To enable maintenance mode, simply execute the down Artisan command:
php artisan down\nYou may also provide message and retry options to the down command. The message value may be used to display or log a custom message, while the retry value will be set as the Retry-After HTTP header's value::
php artisan down --message='Upgrading Database' --retry=60\nTo disable maintenance mode, use the up command::
php artisan up\nWe created a video tutorial demonstrating the manual installation process for IXP Manager v6.0.0 (July 2021) on Ubuntu LTS 20.04. You can find the latest installation videos. As always, the full catalog of video tutorials is here.
"},{"location":"install/manually/#requirements","title":"Requirements","text":"IXP Manager tries to stay current in terms of technology. Typically, this means some element of framework refresh(es) every couple of years and other more incremental package upgrades with minor version upgrades. As well as the obvious reasons for this, there is also the requirement to prevent developer apathy - insisting on legacy frameworks and packages that have been EOL'd provides a major stumbling block for bringing on new developers and contributors.
The current requirements for the web application are:
To complete the installation using the included config/scripts, you will also need to have installed git (apt install git) and a number of PHP extensions (see the example apt install below).
Regrettably the potential combinations of operating systems, versions of same and then versions of PHP are too numerous to provide individual support. As such, we recommend installing IXP Manager on Ubuntu LTS 20.04 and we officially support this platform.
In fact, we provide a complete installation script for this - see the automated installation page for details. If you have any issues with the manual installation, the automated script should be your first reference to compare what you are doing to what we recommend.
For completeness, the IXP Manager installation script for Ubuntu 20.04 LTS installs:
apt install -qy apache2 php8.0 php8.0-intl php8.0-rrd php8.0-cgi php8.0-cli \\\n php8.0-snmp php8.0-curl php8.0-memcached libapache2-mod-php8.0 mysql-server \\\n mysql-client php8.0-mysql memcached snmp php8.0-mbstring php8.0-xml php8.0-gd \\\n php8.0-bcmath bgpq3 php8.0-memcache unzip php8.0-zip git php8.0-yaml \\\n php8.0-ds libconfig-general-perl libnetaddr-ip-perl mrtg libconfig-general-perl \\\n libnetaddr-ip-perl rrdtool librrds-perl curl composer \nDo note that Ubuntu 20.04 LTS comes with PHP 7.4 so you must enable Ond\u0159ej Sur\u00fd's excellent Ubuntu PHP PPA (and maybe buy him a pint). This can be enabled with:
apt-get install -yq software-properties-common\nadd-apt-repository -y ppa:ondrej/php\nIf you are using a different platform, you will need to replicate the above as appropriate for your chosen platform.
"},{"location":"install/manually/#get-the-ixp-manager-source","title":"Get the IXP Manager Source","text":"The code for IXP Manager is maintained on GitHub and the canonical repository is inex/IXP-Manager.
Log into the server where you wish to install IXP Manager. Move to the directory where you wish to store the source (the automated script, our documentation and our examples use /srv/ixpmanager which we refer to as $IXPROOT). Note that it should not be cloned into any web exposed directory (e.g. do not clone to /var/www).
IXPROOT=/srv/ixpmanager\ncd /srv\ngit clone https://github.com/inex/IXP-Manager.git ixpmanager\ncd $IXPROOT # /srv/ixpmanager\ngit checkout release-v6\nchown -R www-data: bootstrap/cache storage\nInstall the required PHP libraries:
First you will need Composer v2 but v1 ships with Ubuntu 20.04. Composer is PHP's package manager and you can download and install it per the copy and paste instructions here (always satisfy yourself with the trustworthiness of the source when downloading and executing scripts).
We assume you downloaded it to $IXPROOT as composer.phar in the following:
cd $IXPROOT\nphp composer.phar install --no-dev --prefer-dist\ncp .env.example .env\nphp artisan key:generate\nUse whatever means you like to create a database and user for IXP Manager. For example:
CREATE DATABASE `ixpmanager` CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_unicode_ci';\nCREATE USER `ixpmanager`@`localhost` IDENTIFIED BY '<pick a password!>';\nGRANT SUPER ON *.* TO `ixpmanager`@`localhost`;\nGRANT ALL ON `ixpmanager`.* TO `ixpmanager`@`localhost`;\nGRANT SUPER ON *.* TO `ixpmanager`@`localhost`;\nFLUSH PRIVILEGES;\nThen edit $IXPROOT/.env and set the database options:
DB_HOST=localhost\nDB_DATABASE=ixpmanager\nDB_USERNAME=ixpmanager\nDB_PASSWORD=<the password you picked above!>\nNow create the database schema:
php artisan migrate\n# Run it twice for completeness\nphp artisan migrate\nSome older scripts still rely on MySQL view tables. Create these with:
# We use root here as the views.sql also contain triggers\nmysql -u root ixpmanager < $IXPROOT/tools/sql/views.sql\nEdit $IXPROOT/.env and review and set/change all parameters. Hopefully this is mostly documented or clear but please start a discussion on the mailing list if you have difficultly and we'll update this and the example file's documentation as appropriate.
Using the settings you edited in .env we'll create some database objects. [Yes, a setup wizard needs to be built!].
First let's create the password for the admin user. The following will create a secure random password and hash it with bcrypt:
cd $IXPROOT\nsource .env\nUSERNAME=admin\nUSEREMAIL=your@email.address\nIXPM_ADMIN_PW=\"$( openssl rand -base64 12 )\"\nADMIN_PW_SALT=\"$( openssl rand -base64 16 )\"\nHASH_PW=$( php -r \"echo escapeshellarg( crypt( '${IXPM_ADMIN_PW}', sprintf( '\\$2a\\$%02d\\$%s', 10, substr( '${ADMIN_PW_SALT}', 0, 22 ) ) ) );\" )\necho Your password is: $IXPM_ADMIN_PW\n\nNAME=\"Joe\"\nIXPNAME=SCIX\nIXPSNAME=SCIX\nIXPASN=65500\nIXPPEEREMAIL=peering@example.com\nIXPNOCPHONE=12345678\nIXPNOCEMAIL=noc@example.com\nIXPWWW=\"http://www.example.com\"\nThe following is taken from the IXP Manager installation script:
mysql -h $DB_HOST -u $DB_USERNAME \"-p${DB_PASSWORD}\" $DB_DATABASE <<END_SQL\nINSERT INTO infrastructure ( name, shortname, isPrimary, created_at, updated_at )\n VALUES ( 'Infrastructure #1', '#1', 1, NOW(), NOW() );\nSET @infraid = LAST_INSERT_ID();\n\nINSERT INTO company_registration_detail ( registeredName, created_at, updated_at ) VALUES ( '${IXPNAME}', NOW(), NOW() );\nSET @crdid = LAST_INSERT_ID();\n\nINSERT INTO company_billing_detail ( billingContactName, invoiceMethod, billingFrequency, created_at, updated_at )\n VALUES ( '${NAME}', 'EMAIL', 'NOBILLING', NOW(), NOW() );\nSET @cbdid = LAST_INSERT_ID();\n\nINSERT INTO cust ( name, shortname, type, abbreviatedName, autsys, maxprefixes, peeringemail, nocphone, noc24hphone,\n nocemail, nochours, nocwww, peeringpolicy, corpwww, datejoin, status, activepeeringmatrix, isReseller,\n company_registered_detail_id, company_billing_details_id, created_at, updated_at )\n VALUES ( '${IXPNAME}', '${IXPSNAME}', 3, '${IXPSNAME}', ${IXPASN}, 100, '${IXPPEEREMAIL}', '${IXPNOCPHONE}',\n '${IXPNOCPHONE}', '${IXPNOCEMAIL}', '24x7', '', 'mandatory', '${IXPWWW}', NOW(), 1, 1, 0, @crdid, @cbdid, NOW(), NOW() );\nSET @custid = LAST_INSERT_ID();\n\nINSERT INTO user ( custid, name, username, password, email, privs, disabled, created_at, updated_at )\n VALUES ( @custid, '${NAME}', '${USERNAME}', ${HASH_PW}, '${USEREMAIL}', 3, 0, NOW(), NOW() );\nSET @userid = LAST_INSERT_ID();\n\nINSERT INTO customer_to_users ( customer_id, user_id, privs, created_at, updated_at )\n VALUES ( @custid, @userid, 3, NOW(), NOW() );\n\nINSERT INTO contact ( custid, name, email, created_at, updated_at )\n VALUES ( @custid, '${NAME}', '${USEREMAIL}', NOW(), NOW() );\nEND_SQL\nAnd finally seed the database:
cd $IXPROOT\nphp artisan db:seed --force --class=IRRDBs\nphp artisan db:seed --force --class=Vendors\nphp artisan db:seed --force --class=ContactGroups\nThe web server needs write access to some directories:
cd $IXPROOT\nchown -R www-data: storage/ bootstrap/cache/\nchmod -R u+rwX storage/ bootstrap/cache/\nHere is a sample virtual hosts file for IXP Manager (replace {$IXPROOT} as appropriate!):
<VirtualHost *:80>\n ServerAdmin webmaster@localhost\n DocumentRoot ${IXPROOT}/public\n <Directory ${IXPROOT}/public>\n Options FollowSymLinks\n AllowOverride None\n Require all granted\n RewriteEngine On\n RewriteCond %{REQUEST_FILENAME} -s [OR]\n RewriteCond %{REQUEST_FILENAME} -l [OR]\n RewriteCond %{REQUEST_FILENAME} -d\n RewriteRule ^.*$ - [NC,L]\n RewriteRule ^.*$ /index.php [NC,L]\n </Directory>\n ErrorLog \\${APACHE_LOG_DIR}/error.log\n CustomLog \\${APACHE_LOG_DIR}/access.log combined\n</VirtualHost>\nYou also need to enable rewrite:
a2enmod rewrite\nservice apache2 restart\nYour new IXP Manager installation should be accessible via your server's IP address using the username ($USERNAME) and password ($IXPM_ADMIN_PW) you set above.
If you plan to use this in production, you should:
operations <at> inex <dot> ie.What next? See our post-install / next steps document here.
"},{"location":"install/next-steps/","title":"Post-Install / Next Steps","text":"So you have installed IXP Manager, congratulations! But now you are wondering what to do next?
Hopefully this document will point you in the right direction to help you start using IXP Manager. Note that we assume you have used the automated installer and so you have a single customer already in the database - the IXP's own customer.
"},{"location":"install/next-steps/#essential-steps-set-up-the-ixp","title":"Essential Steps - Set Up the IXP","text":"We created a video tutorial demonstrating these steps. You can find the video here in our YouTube channel. As always, the full catalog of video tutorials is here.
There are basic elements you need to add to IXP Manager which describe your IXP and are required for standard usage. Most of these actions can be found under the IXP ADMIN ACTIONS on the left hand side menu.
Remember: most of the forms for adding and editing the following entities have context help on each input field via the green Help button.
create your infrastructures. Generally, an infrastructure represents a collection of switches which form an IXP's peering LAN. The best way to think of an infrastructure is to think of it as an IXP.
For example, INEX runs three infrastructures - INEX LAN1, INEX LAN2 and INEX Cork. Each of these consist of a unique set of switches and these infrastructures are not interconnected. They also have unique PeeringDB entries (INEX LAN1, INEX LAN2, INEX Cork) and IX-F entries (INEX LAN1, INEX LAN2, INEX Cork) for each infrastructure.
If you do not have a PeeringDB entry yet, then register and create one. Similarly, if you do not have an IX-F entry, email the IXPDB admins via ixpdb-admin <at> euro-ix.net with your IX's full name, short name, city / region / country, GPS coordinates and website URL.
Add your facilities (points of presence - the data centres where networks can connect to one of your IX switches).
Add your racks. You will need this later to add patch panels and switches for example.
You can now add switches. We have good documentation for this here. It is important to note that the IXP Manager server will need SNMP (v2) access to your switches and your switches should have a domain name registered in DNS. Avoid using IP addresses here.
IXP Manager will query your switch via SNMP and discover its details as well as setting up all the switch ports in the database.
Add your VLAN(s). We would recommend two VLANs per infrastructure for peering purposes:
When adding your production peering VLAN, you will want to check the Include VLAN in the peering matrix (see help) option and the Include VLAN in the peering manager (see help) option.
Add Network Information for the peering LAN also. The Network Information is a submenu under the VLANs menu option.
Add your peering IP addresses. IXP Manager will let you add complete ranges (e.g. /24) and more sensible ranges of IPv6 (i.e. not an entire /64!).
Ensure email is correctly configured.
Now, a very important next step: let us know you are using IXP Manager so we can add you to the community map. You can complete the online form or get more details here.
The above constitutes the basic elements that are required to provision a customer.
For documentation on adding and managing customers, see here. And for details on provisioning interfaces for your customers, see here.
"},{"location":"install/next-steps/#feature-checklist","title":"Feature Checklist","text":"The above section lists the essential set-up elements. Beyond those, IXP Manager has many features that require a little extra effort to set up as there is a manual element to many of them. What follows is a check list of these features:
Graphing (documentation) - at a minimum you will want to set up interface graphs via mrtg. You should also look at peer to peer graphing via sflow and latency graphing via Smokeping.
Routers - see the generic documentation here. Then remember that no IX is complete without route servers with IRRDB and RPKI filtering. We would highly recommend a route collector on each infrastructure.
And while we're talking routers - consider an AS112 service.
You should also set-up the looking glass functionality on these servers. This is used to provide a looking glass to IX operators and members, for monitoring, for prefix filtering tools, etc.
Make sure you have set up IXP Manager's cron job.
Use the cross connect / patch panel management features. As your IX grows and you end up with tens or hundreds of these you will profoundly regret it if you haven't used this feature from day one.
Use IXP Manager to automate your PTR ARPA records for member assigned IP addresses on the peering LAN.
Set-up your IX-F export and let ixpdb-admin (at) euro-ix (dot) net know about it.
If you are not statically configuring / using static l2acls for MAC addresses, then set up MAC address discover.
Configure Nagios monitoring.
Enable the member facing Peering Manager.
Consider setting up BGP session discovery via sflow for the peering matrix.
Set up your PeeringDB account in IXP Manager to enable all features including ease of adding customers.
Allow IXP Manager to maintain your RIR objects automatically.
You may want to skin some of the templates. However, in the main, we would advise keeping this to a minimum or upgrades will become more complicated. Especially if you skin complex / core templates around functionality. There are some templates we do recommend you skin immediately:
the support details page.
Add any static content you require.
Automation - if you're so inclined to look at switch automation, see INEX's templates here (Arista and Cumulus).
As you look through the above, do please note that we have given a lot of presentations over the years and many are linked here with video.
Happy peering!
"},{"location":"install/register/","title":"Join the Community","text":"It really helps the core IXP Manager team at INEX to know that the community is growing. Every new user builds our momentum to keep developing and supporting the platform.
We maintain a a community map and statistics that are updated nightly.
To join our community and get on the map, you can complete this online form.
If you don't have an IX-F ID or a PeeringDB ID that's fine, just leave those blank. You can register with PeeringDB yourself and we'll help out with an IX-F ID when you register with us.
If you have any questions about this, please reach out to us by email to operations <at> inex.ie.
If you are running IXP Manager behind a load balancer / proxy that terminates TLS / SSL connections, you may notice your application sometimes does not generate HTTPS links. Typically this is because your application is being forwarded traffic from your load balancer on port 80 and does not know it should generate secure links.
From v4.7.2, IXP Manager supports trusted proxies via Laravel's support for fideloper/TrustedProxy.
See the above links for complete documentation. To just get it working, you need to:
Publish the default trusted proxies configuration file:
cd $IXPROOT\n./artisan vendor:publish --provider=\"Fideloper\\Proxy\\TrustedProxyServiceProvider\"\nThe above will create a file ${IXPROOT}/config/trustedproxy.php. For the most part, you now just need to change the IP address(es) in the array proxies to those of your own proxy/proxies.
NB: as well as the above, it is also critical that your have correctly set APP_URL in the .env file for URL generation to correctly work.
Controllers can be disabled by setting the following config item in config/ixp_fe.php:
<?php\n[\n // ...,\n\n 'frontend' => [\n 'disabled' => [\n 'xxx' => true,\n ],\n ],\n];\nwhere xxx is the controller name. This name is in kebab-case format including any non-IXP\\Http\\Controllers namespace. Here are some controller - xxx examples:
This action is controlled by the IXP\\Http\\Middleware\\ControllerEnabled middleware.
Note that in the configuration file, we have some pre-defined dotenv settings for commonly disabled controllers. It is a bad idea to manually edit the configuration files. If you find a controller than should be disabled and there there is no dotenv option, please open an issue.
"},{"location":"install/upgrade-v3/","title":"Upgrade From v3","text":"Due to the significant changes between IXP Manager v3 and v4, there is no in place upgrade process. The advised way to handle this is to install v4 in parallel and then switch over (by adjusting your DNS or Apache configuration for example) to the new v4 directory/server.
This documentation was compiled while performing an upgrade on three separate IXP Manager installations.
Before you proceed, please check the requirements listed in the official installation instructions.
If you need help, please contact us via the public mailing list.
If you find that this guide is insufficient, please contribute back to this documentation.
"},{"location":"install/upgrade-v3/#overview","title":"Overview","text":"The upgrade process is quite involved and, depending how many IXP Manager features you use, may take the best part of a day.
The general steps are:
You will note from the above that a number of features have been deprecated in favor of doing it in new ways. Our advice is to keep both v3 and v4 live in parallel and then migrate services piece meal. That way your route server configuration can continue pulling from v3 until you have set-up the v4 method. Just ensure that people do not make customer changes in either IXP Manager during this period (or, if they do, do it in both!).
"},{"location":"install/upgrade-v3/#deprecations-removed-features","title":"Deprecations / Removed Features","text":"As of IXP Manager v4 (certainly >=v4.5), the following are no longer available:
As we're installing in parallel, we want to duplicate the database.
When granting permissions on the new database, use your existing IXP Manager database credentials for ease of configuration.
mysql -u root -pXXX -e 'CREATE DATABASE ixp4 CHARACTER SET = \"utf8mb4\" COLLATE = \"utf8mb4_unicode_ci\";'\n\nmysqldump -u root -pXXX ixp | mysql -u root -pXXX ixp4\n\nmysql -u root -pXXX -e 'GRANT ALL ON ixp4.* TO `ixp`@`localhost` IDENTIFIED BY \"YYY\";'\n\n# and test:\nmysql -u ixp -pYYY -h localhost ixp4\nThis is very much a tl;dr version of the official installation instructions which you should review if you need additional help.
Critically, these upgrade instructions were designed and tested against IXP Manager v4.5.0. You need to upgrade to this version first and then follow the v4 upgrade instructions from there.
The code for IXP Manager is maintained on GitHub and the canonical repository is inex/IXP-Manager.
Log into the server where you wish to install IXP Manager and move to the directory where you wish to install (we use /srv/ixpmanager here as an example and which will be referred to as $IXPROOT below).
Note that it should not be checked out into any web exposed directory (e.g. do not checkout to /var/www).
IXPROOT=/srv/ixpmanager\n\n# get the source / application\ngit clone https://github.com/inex/IXP-Manager.git $IXPROOT\ncd $IXPROOT\ngit checkout v4.5.0\n\n# Using https://getcomposer.org/\ncomposer.phar install\n\n# Using https://bower.io/\nbower install\n\n# Start with the example configuration and edit.\n# Read the official documentation for help.\n# Ensure you configure the database.\n# More notes on this follow below.\ncp .env.example .env\nphp artisan key:generate\njoe .env\n\n# File system permissions\nchown -R www-data: var/ storage/ bootstrap/cache database/Proxies\nIXP Manager v4 uses a new PHP framework (Zend Framework swapped for Laravel). As such, all the older configuration options (from application/configs/application.ini) need to be ported to .env.
The php dotenv file (.env) is where all the new configuration options go. These in turn are used by the configuration files under config/.
NB: Where possible, place local changes into .env rather than changing the config files as these files are under version control. See Laravel's documentation on this and email the mailing list for help.
Once you have worked your way through .env, move into the $IXPROOT/config directory and - as appropriate for your own installation - examine each config file that ends in .dist. If you use / need any features in these files, copy then such as:
cd $IXPROOT/config\ncp xxxx.php.dist xxxx.php\nThen edit the resultant .php file (or, better, where config() options exist, add them to .env).
These .dist files represent v3 functionality that has not yet been fully ported to v4/Laravel.
There's about 50 schema changed between the end of v3 and v4.4.
View the required changes with:
./artisan doctrine:schema:update --sql\nAnd apply with:
./artisan doctrine:schema:update --force\nSince v4.5, we no longer allow plaintext passwords. If you were using plaintext passwords, you need to convert them to bcrypt as follows:
cd $IXPROOT\n\n# dummy run to see what happens:\nphp artisan utils:convert-plaintext-password\n\n# really convert passwords and save to database:\nphp artisan utils:convert-plaintext-password --force\nYou should be able to point Apache / your web server at the new IXP Manager installation and log in.
"},{"location":"install/upgrade-v3/#mrtg-graphing-migration","title":"MRTG Graphing Migration","text":"We've implemented a new graphing backend called Grapher. One of the changes is that the graphing directory structure and file-naming conventions have changed. Primarily, we've replaced non-static handles (such as database fields like customer.shortname, physicalinterface.monitorindex and switcher.name with immutable primary keys).
As such, you need to both rename the statistics directory structure and regenerate the configuration.
It is strongly recommended you copy your existing files and do this in parallel or, at least keep a backup. Also, stop the MRTG daemon before starting.
"},{"location":"install/upgrade-v3/#performing-the-migration","title":"Performing the Migration","text":"First, you'll need to update your local configuration in .env by setting something like:
GRAPHER_BACKENDS=\"mrtg\"\nGRAPHER_BACKEND_MRTG_LOGDIR=\"/path/to/new/mrtg/data\"\nGRAPHER_BACKEND_MRTG_WORKDIR=\"/path/to/new/mrtg/data\"\nGRAPHER_CACHE_ENABLED=true\nSee the Grapher documentation for full details of what these mean.
You'll then need to migrate all your MRTG files to the new naming scheme. Run the commands below twice. Once to verify the output and a second time piped to sh (| sh) to actually execute the commands.
# set a variable for what will become the 'old' files for convenience\nOLDMRTG=/srv/old-mrtg\n\n# position ourselves in the IXP Manager root directory\ncd $IXPROOT\n\n# stop mrtg\nservice mrtg stop # or as appropriate for your platform\n\n# Migrate IXP graphs.\n#\n# In v3 of IXP Manager, the name of this was set by a database\n# parameter in the IXP table called 'aggregate graph name'.\n# You will be able to spot it in the old MRTG files where the\n# old IXP file is named something like: 'ixp_peering-XXXXX-bits.log'.\n# The 'XXXXXX' bit is the aggregate name you need to replace in the below:\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -X --agg-name=XXXXXX\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -X --agg-name=XXXXXX | sh\n\n# Migrate infrastructure graphs.\n#\n# In v3 of IXP Manager, the name of this was set by a database\n# parameter in the infrastructure table called 'aggregate graph name'.\n# You will be able to spot it in the old MRTG files where the\n# old IXP file is named something like: 'ixp_peering-XXXXX-bits.log'.\n# The 'XXXXXX' bit is the aggregate name you need to replace in the below:\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -I\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -I | sh\n\n# Migrate switch graphs\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -S\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -S | sh\n\n# Migrate trunk graphs and configuration.\n# If you had not configured trunk graphs you can skip this. We are\n# planning to (very soon - Q2/3 2017) fully integrate this into IXP\n# Manager.\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -T\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -T | sh\nphp artisan grapher:backend:mrtg:upgrade migrate-trunk-config\n\n# Create member directories\nphp artisan grapher:backend:mrtg:upgrade mkdir -L $OLDMRTG -M\nphp artisan grapher:backend:mrtg:upgrade mkdir -L $OLDMRTG -M | sh\n\n# Migrate member physical interface graphs\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -P\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -P | sh\n\n# Migrate member LAG graphs\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -Q\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -Q | sh\n\n# Migrate member aggregate graphs\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -C\nphp artisan grapher:backend:mrtg:upgrade mv -L $OLDMRTG -C | sh\n\n# Regenerate mrtg configuration\nphp artisan grapher:generate-configuration -B mrtg > path/to/mrtg.conf\n\n# Start mrtg\nservice mrtg start # or as appropriate for your platform\nThe previous version of IXP Manager used a script called sflow-graph.php which was installed on the sflow server to create graphs on demand. IXP Manager v4 does not use this but pulls the required RRD files directly.
If you have this on the same server or can expose it using NFS for example, then set the path accordingly in .env:
GRAPHER_BACKEND_SFLOW_ROOT=\"/srv/ixpmatrix\"\nIf you have implemented this via a web server on the sflow server (as we typically do at INEX), then you need to expose the RRD data directory to IXP Manager using an Apache config such as:
Alias /grapher-sflow /srv/ixpmatrix\n\n<Directory \"/srv/ixpmatrix\">\n Options None\n AllowOverride None\n <RequireAny>\n Require ip 192.0.2.0/24\n Require ip 2001:db8::/32\n </RequireAny>\n</Directory>\nand update .env for this with something like:
GRAPHER_BACKEND_SFLOW_ROOT=\"http://www.example.com/grapher-sflow\"\nThese upgrade instructions relate to upgrading when you are already using IXP Manager v4.x.
We track releases on GitHub.
You will find standard instructions for upgrading IXP Manager below. Note that the release notes for each version may contain specific upgrade instructions including schema changes.
If you have missed some versions, the most sensible approach is to upgrade to each minor release in sequence (4.5.0 -> 4.6.0 -> 4.7.0 -> ...) and then to the latest patch version in the latest minor version.
In the below, we assume the following installation directory - alter this to suit your own situation:
IXPROOT=/srv/ixpmanager\nThe general process is:
Set up some variables and ensure directory permissions are okay:
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\n# fix as appropriate to your operating system\nMY_WWW_USER=www-data\n\n# ensure the web server daemon user can write to necessary directories:\nchown -R $MY_WWW_USER: $IXPROOT/public/bower_components ${IXPROOT}/bower.json \\\n ${IXPROOT}/storage $IXPROOT/vendor\nchmod -R u+rwX $IXPROOT/public/bower_components ${IXPROOT}/bower.json \\\n ${IXPROOT}/storage $IXPROOT/vendor\nEnable maintenance mode:
cd $IXPROOT\n./artisan down\nUsing Git, checkout the next minor / latest patch version up from yours. For IXP Manager v4.
# (assuming we're still in $IXPROOT)\n# pull the latest code\ngit fetch\n# check out the version you are upgrading to\ngit checkout v4.x.y\nInstall latest required libraries from composer (see notes below):
# this assumes composer.phar is in the IXP Manager install directory. YMMV - see notes below.\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && php ./composer.phar install --no-dev --prefer-dist\"\nInstall latest frontend dependencies (see notes below):
# if asked to chose a jquery version, chose the latest / highest version offered\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && \\\n bower --config.interactive=false -f prune\"\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && \\\n bower --config.interactive=false -f update\"\nRestart Memcached and clear the cache. Do not forget / skip this step!
# (assuming we're still in $IXPROOT)\nsystemctl restart memcached.service\n./artisan cache:clear\nUpdate the database schema:
# (assuming we're still in $IXPROOT)\n# review / sanity check first:\n./artisan doctrine:schema:update --sql\n# If in doubt, take a mysqldump of your database first.\n# migrate:\n./artisan doctrine:schema:update --force\nRestart Memcached (yes, again). Do not forget / skip this step!
systemctl restart memcached.service\nEnsure there are no version specific changes required in the release notes.
Ensure file permissions are correct.
chown -R $MY_WWW_USER: $IXPROOT/public/bower_components ${IXPROOT}/bower.json \\\n ${IXPROOT}/storage $IXPROOT/vendor $IXPROOT/var $IXPROOT/bootstrap/cache\nchmod -R u+rwX $IXPROOT/public/bower_components ${IXPROOT}/bower.json \\\n ${IXPROOT}/storage $IXPROOT/vendor $IXPROOT/var $IXPROOT/bootstrap/cache\nFor IXP Manager v4.9 (including upgrading to v4.9) and later:
${IXPROOT}/artisan migrate\nClear out all caches:
${IXPROOT}/artisan cache:clear\n${IXPROOT}/artisan config:clear\n${IXPROOT}/artisan doctrine:clear:metadata:cache\n${IXPROOT}/artisan doctrine:clear:query:cache\n${IXPROOT}/artisan doctrine:clear:result:cache\n${IXPROOT}/artisan route:clear\n${IXPROOT}/artisan view:clear\nDisable maintenance mode:
# (assuming we're still in $IXPROOT)\n./artisan up\nSome older scripts, including the sflow modules, rely on MySQL view tables that may be affected by SQL updates. You can safely run this to recreate them:
mysql -u ixp -p ixp < $IXPROOT/tools/sql/views.sql\nIt is not advisable to run bower as root but how you run it will depend on your own installation. The following options would work on Ubuntu (run these as root and the bower commands themselves will be run as $MY_WWW_USER):
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\nMY_WWW_USER=www-data # fix as appropriate to your operating system\n\n# ensure www-data can write to bower:\nchown -R $MY_WWW_USER: $IXPROOT/public/bower_components ${IXPROOT}/bower.json ${IXPROOT}/storage\nchmod -R u+rwX $IXPROOT/public/bower_components ${IXPROOT}/bower.json ${IXPROOT}/storage\n\n# update bower\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && bower --config.interactive=false -f update\"\nThe above command is structured as it is because typically the www-data user has a nologin shell specified.
This is similar to the bower section above so please read that if you have not already.
Note that we assume here what you have installed Composer (see: https://getcomposer.org/ ) in the ${IXPROOT} directory as composer.phar. This is where and how the IXP Manager installation scripts and documentation instructions install it.
The following options would work on Ubuntu (run these as root and the composer commands themselves will be run as $MY_WWW_USER):
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\nMY_WWW_USER=www-data # fix as appropriate to your operating system\n\n# ensure www-data can write to vendor:\nchown -R $MY_WWW_USER: $IXPROOT/vendor ${IXPROOT}/storage\nchmod -R u+rwX $IXPROOT/vendor ${IXPROOT}/storage\n\n# update composer\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && php ./composer.phar install\"\nNB: If composer is not managed by your package management system, you should keep it up to date via the following (using the same definitions from the composer update example above):
chown -R $MY_WWW_USER: ${IXPROOT}/composer.phar\nchmod -R u+rwx ${IXPROOT}/composer.phar\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && php ./composer.phar selfupdate\"\nBecause of the manual process of database updates, it is possible your database schema may fall out of sync.
If you are having issues, first and foremost, restart Memcached. Doctrine2 caches entities and schema information in Memcached so, after an upgrade, you must restart Memcached.
You can verify and update your schema using the artisan script. The first action should be validation - here is a working example with no database issues:
cd $IXPROOT\n./artisan doctrine:schema:validate\n\nValidating for default entity manager...\n[Mapping] OK - The mapping files are correct.\n[Database] OK - The database schema is in sync with the mapping files.\nIf there are issues, you can use the following to show what SQL commands are required to bring your schema into line:
./artisan doctrine:schema:update --sql\nAnd you can let Doctrine make the changes for you via:
./artisan doctrine:schema:update --force\nDoctrine2 maintains the entities, proxies and repository classes. Ideally you should never need to do the following on a production installation - as we maintain these files with Git - but if you're developing / testing IXP Manager, you may need to.
The process for updating these files with schema changes / updates is:
cd $IXPROOT\nsystemctl restart memcached.service # (or as appropriate for your system)\n./artisan doctrine:generate:entities database\n./artisan doctrine:generate:proxies\nWe created a video tutorial demonstrating the upgrade process for IXP Manager. You can find the video here in our YouTube channel. We also have a video on upgrading a legacy version (v4.9.3 to v5.7.0) - see the video here and some further details in this blog post. As always, the full catalog of video tutorials is here.
"},{"location":"install/upgrade-v5/#instructions","title":"Instructions","text":"We track releases on GitHub.
You will find standard instructions for upgrading IXP Manager below. Note that the release notes for each version may contain specific upgrade instructions including schema changes.
If you have missed some versions, the most sensible approach is to upgrade to each minor release in sequence (5.0.0 -> 5.1.0 -> 5.2.0 -> ...) and then to the latest patch version in the latest minor version.
In the below, we assume the following installation directory - alter this to suit your own situation:
IXPROOT=/srv/ixpmanager\nBefore you start, consider if you need to make a backup. We would expect that most IXP's would have a nightly backup of all their servers at a minimum. If not, or for belt-and-braces, you may want to make a local temporary backup. See our operational notes on backups for an idea on how to do this.
The general process is:
Set up some variables and ensure directory permissions are okay:
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\n# fix as appropriate to your operating system\nMY_WWW_USER=www-data\n\n# ensure the web server daemon user can write to necessary directories:\nchown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nEnable maintenance mode:
php $IXPROOT/artisan down --message='Please wait, currently upgrading...'\nUsing Git, checkout the next minor / latest patch version up from yours. For IXP Manager v4.
cd $IXPROOT\n# pull the latest code\ngit fetch --all\n# check out the version you are upgrading to\ngit checkout v5.x.y\nInstall latest required libraries from composer (see notes below). Note that composer may be in different locations.
# This assumes composer is in the IXP Manager install directory.\n# (Typical for IXP Manager on Ubtuntu 18.04):\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} \\\n && php ./composer.phar install --no-dev --prefer-dist\"\n\n# OR:\n\n# This assumes composer is installed globally.\n# (Typical for IXP Manager on Ubtuntu 20.04):\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} \\\n && composer install --no-dev --prefer-dist\"\nRestart Memcached and clear the cache. Do not forget / skip this step!
systemctl restart memcached.service\nphp $IXPROOT/artisan cache:clear\nUpdate the database schema:
# (you really should take a mysqldump of your database first)\n\n# (optional) see what changes will be made:\nphp $IXPROOT/artisan doctrine:schema:update --sql\nphp $IXPROOT/artisan migrate:status\n\n# migrate:\nphp $IXPROOT/artisan doctrine:schema:update --force\nphp $IXPROOT/artisan migrate\nRestart Memcached (yes, again). Do not forget / skip this step!
systemctl restart memcached.service\nEnsure there are no version specific changes required in the release notes.
Ensure file permissions are still correct.
chown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nClear out all caches:
php ${IXPROOT}/artisan cache:clear\nphp ${IXPROOT}/artisan config:clear\nphp ${IXPROOT}/artisan doctrine:clear:metadata:cache\nphp ${IXPROOT}/artisan doctrine:clear:query:cache\nphp ${IXPROOT}/artisan doctrine:clear:result:cache\nphp ${IXPROOT}/artisan route:clear\nphp ${IXPROOT}/artisan view:clear\nDisable maintenance mode:
php ${IXPROOT}/artisan up\nRecreate SQL views
Some older scripts, including the sflow modules, rely on MySQL view tables that may be affected by SQL updates. You can safely run this to recreate them on versions > v5.5.0:
php ${IXPROOT}/artisan update:reset-mysql-views\nIf you are running <= v5.4.0 then do this as follows using the appropriate MySQL username and password:
mysql -u ixp -p ixp < $IXPROOT/tools/sql/views.sql\nIt is not advisable to run composer as root but how you run it will depend on your own installation. The following options would work on Ubuntu (run these as root and the composer commands themselves will be run as $MY_WWW_USER). Note that we assume here what you have installed Composer (see: https://getcomposer.org/ ) in the ${IXPROOT} directory as composer.phar. This is where and how the IXP Manager installation scripts and documentation instructions install it.
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\nMY_WWW_USER=www-data # fix as appropriate to your operating system\n\n# ensure the web server daemon user can write to necessary directories:\nchown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\n\n# update composer packages\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} \\\n && php ./composer.phar install --prefer-dist --no-dev\"\nNB: If composer is not managed by your package management system, you should keep it up to date via the following (using the same definitions from the composer update example above):
chown -R $MY_WWW_USER: ${IXPROOT}/composer.phar\nchmod -R u+rwx ${IXPROOT}/composer.phar\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && php ./composer.phar selfupdate\"\nBecause of the manual process of database updates, it is possible your database schema may fall out of sync.
If you are having issues, first and foremost, restart Memcached / clear your cache (see upgrade instructions above). Doctrine2 caches entities and schema information in Memcached so, after an upgrade, you must restart Memcached.
You can verify and update your schema using the artisan script. The first action should be validation - here is a working example with no database issues:
cd $IXPROOT\n./artisan doctrine:schema:validate\n\nValidating for default entity manager...\n[Mapping] OK - The mapping files are correct.\n[Database] OK - The database schema is in sync with the mapping files.\nIf there are issues, you can use the following to show what SQL commands are required to bring your schema into line:
./artisan doctrine:schema:update --sql\nAnd you can let Doctrine make the changes for you via:
./artisan doctrine:schema:update --force\nDoctrine2 maintains the entities, proxies and repository classes. Ideally you should never need to do the following on a production installation - as we maintain these files with Git - but if you're developing / testing IXP Manager, you may need to.
The process for updating these files with schema changes / updates is:
cd $IXPROOT\nsystemctl restart memcached.service # (or as appropriate for your system)\n./artisan doctrine:generate:entities database\n./artisan doctrine:generate:proxies\nFor instructions on how to upgrade from v5.8.0 to v6.0.0, please see the release notes for v6.
For instructions on how to upgrade within the v5.x releases, please see this page.
For instructions on how to upgrade within the v4.x releases, please see this page.
For instructions on how to upgrade from v3.x to v4, please see this page.
For instructions on how to upgrade from v4.9.x to v5.0, please see the v5.0 release notes.
We created a video tutorial demonstrating the upgrade process for IXP Manager within the v5.x branch which is not dissimilar to this. You can find the video here in our YouTube channel. We also have a video on upgrading a legacy version (v4.9.3 to v5.7.0) - see the video here and some further details in this blog post. As always, the full catalog of video tutorials is here.
"},{"location":"install/upgrading/#instructions","title":"Instructions","text":"We track releases on GitHub.
You will find standard instructions for upgrading IXP Manager below. Note that the release notes for each version may contain specific upgrade instructions including schema changes.
If you have missed some versions, the most sensible approach is to upgrade to each minor release in sequence (6.0.0 -> 6.1.0 -> 6.2.0 -> ...) and then to the latest patch version in the latest minor version.
In the below, we assume the following installation directory - alter this to suit your own situation:
IXPROOT=/srv/ixpmanager\nBefore you start, consider if you need to make a backup. We would expect that most IXP's would have a nightly backup of all their servers at a minimum. If not, or for belt-and-braces, you may want to make a local temporary backup. See our operational notes on backups for an idea on how to do this.
The general process is:
Set up some variables and ensure directory permissions are okay:
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\n# fix as appropriate to your operating system\nMY_WWW_USER=www-data\n\n# ensure the web server daemon user can write to necessary directories:\nchown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nEnable maintenance mode:
php $IXPROOT/artisan down --message='Please wait, currently upgrading...'\nUsing Git, checkout the next minor / latest patch version up from yours. For IXP Manager v6:
cd $IXPROOT\n# pull the latest code\ngit fetch --all\n# check out the version you are upgrading to\ngit checkout v6.x.y\nInstall latest required libraries from composer (see notes below). Note that composer may be in different locations.
# This assumes composer is installed globally.\n# (Typical for IXP Manager on Ubtuntu 20.04):\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} \\\n && composer install --no-dev --prefer-dist\"\nRestart Memcached and clear the cache.
systemctl restart memcached.service\nphp $IXPROOT/artisan cache:clear\nUpdate the database schema:
# (you really should take a mysqldump of your database first)\n\n# (optional) see what changes will be made:\nphp $IXPROOT/artisan migrate:status\n\n# migrate:\nphp $IXPROOT/artisan migrate\nEnsure there are no version specific changes required in the release notes.
Ensure file permissions are still correct.
chown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nClear out all caches (cache is there twice which is intended):
php ${IXPROOT}/artisan cache:clear\nphp ${IXPROOT}/artisan cache:clear file\nphp ${IXPROOT}/artisan config:clear\nphp ${IXPROOT}/artisan route:clear\nphp ${IXPROOT}/artisan view:clear\nDisable maintenance mode:
php ${IXPROOT}/artisan up\nRecreate SQL views
Some older scripts, including the sflow modules, rely on MySQL view tables that may be affected by SQL updates.
cd ${IXPROOT}\nsource .env\nmysql -h $DB_HOST -u $DB_USERNAME -p$DB_PASSWORD $DB_DATABASE < $IXPROOT/tools/sql/views.sql\nIt is not advisable to run composer as root but how you run it will depend on your own installation. The following options would work on Ubuntu (run these as root and the composer commands themselves will be run as $MY_WWW_USER). Note that we assume here what you have installed Composer (see: https://getcomposer.org/ ) in the ${IXPROOT} directory as composer.phar.
# set this to your IXP Manager installation directory\nIXPROOT=/srv/ixpmanager\n\nMY_WWW_USER=www-data # fix as appropriate to your operating system\n\n# ensure the web server daemon user can write to necessary directories:\nchown -R $MY_WWW_USER: ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\nchmod -R ug+rwX ${IXPROOT}/{bootstrap/cache,composer.lock,storage,vendor}\n\n# update composer packages\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} \\\n && php ./composer.phar install --prefer-dist --no-dev\"\nNB: If composer is not managed by your package management system, you should keep it up to date via the following (using the same definitions from the composer update example above):
chown -R $MY_WWW_USER: ${IXPROOT}/composer.phar\nchmod -R u+rwx ${IXPROOT}/composer.phar\nsudo -u $MY_WWW_USER bash -c \"HOME=${IXPROOT}/storage && cd ${IXPROOT} && php ./composer.phar selfupdate\"\nIXP Manager allows users to login and remain logged in for up to 30 days (by default). Users may also have and maintain multiple login sessions from different browsers.
To enable such a long-lived session, the user must check the Remember me checkbox when logging in.
Active sessions can be seen (and deleted) via the Active Sessions option in the user's My Account menu (top right of screen).
"},{"location":"usage/authentication/#session-lifetimes","title":"Session Lifetimes","text":"There are two configurable options here - both in minutes. The first is the session lifetime which is how long a browser session will stay valid since the last activity. The default value is defined in .env as:
SESSION_LIFETIME=120\nIn other words, your login session (when you do not check remember me) will stay valid for 120 minutes / 2 hours by default. This is two hours since the last request - i.e. the session expiry time updates on each request. If you are curious, the browser cookie managing this is called laravel_session by default.
If the user checks remember me, then a second cookie is sent to and stored on your browser (called remember_web_xxx where xxx is a random string). This references an entry in the user's user_remember_tokens database table.
The default lifetime of this remember me session is defined in .env as:
AUTH_TOKEN_EXPIRE=43200\nSo, your remember me session will last 30 days before you will be forced to login again from a particular browser.
You may notice that the cookie sent to the browser for this has an indefinite lifetime - the expiry is actually controlled by the user_remember_tokens.expires database column.
Two factor authentication (2fa) strengthens access security by requiring two methods (also referred to as factors) to verify your identity. Two factor authentication protects against phishing, social engineering and password brute force attacks and secures your logins from attackers exploiting weak or stolen credentials.
For the avoidance of doubt, 2fa does not apply to API keys or API requests. Treat your API keys with extreme care.
IXP Manager supports a Google Authenticator compatible HMAC-Based One-time Password (HOTP) algorithm as specified in RFC 4226 and the Time-based One-time Password (TOTP) algorithm specified in RFC 6238. In other words, the standard 2fa system that is supported by most apps such as Authy, Google Authenticator, LastPass, 1Password, etc.
User's can enable, view (and test) and disable 2fa via the My Account -> Profile page.
2FA support in IXP Manager is enabled by default from v5.3. To globally disable it set the following .env option:
2FA_ENABLED=false\nYou can enforce the use of 2fa for some (or all) categories of users. Set the following configuration option:
2FA_ENFORCE_FOR_USERS=n\nwhere n is the privilege level of the user (see privs= here). For example to force 2fa for:
3;2; or1.If a user without 2fa enabled tries to login from a privilege category that has been configured to enforce 2fa, they will be required to configure 2fa immediately before being granted access to IXP Manager.
"},{"location":"usage/authentication/#lifetime","title":"Lifetime","text":"A user will not be asked to revalidate their 2fa code during the lifetime of a standard browser session or remember me session (see above).
"},{"location":"usage/authentication/#removing-2fa-restoring-user-access","title":"Removing 2FA / Restoring User Access","text":"We have opted not to implement recovery / backup codes as they are not particularly appropriate to the scope of IXP Manager.
If a user needs to have their 2fa removed (indefinitely or so they can reconfigure it), superadmins can do this via the standard user listing (the Users option in the left hand menu).
Identify the user you wish to remove 2fa from, dropdown the additional actions menu on the far right of the table row and select Remove 2FA.
Once you confirm this action, that user's 2fa configuration will be deleted. The next time they log in, they will either be granted access without 2fa or forced to reconfigure 2fa if you have enforced 2fa for the user's category.
"},{"location":"usage/contacts/","title":"Contacts","text":"The IXP Manager Contacts feature allows you to record and manage contacts on a per customer basis including:
If the roles are not shown when you are editing / adding contacts, ensure you copy the following file to a local version:
cp ${IXPROOT}/config/contact_group.php.dist ${IXPROOT}/config/contact_group.php\nThe latest version of the automatic installation script takes care of this but older versions did not.
"},{"location":"usage/contacts/#contact-groups","title":"Contact Groups","text":"INTRODUCED: 20130410 - V3.0.9 (sponsored by LONAP)
Contacts can be assigned to multiple arbitrary groups. A group is defined by:
You define the group types in config/contact_group.php such as:
return [\n 'types' => [\n 'ROLE' => 'Role',\n 'MARKETING_PREFERENCES' => 'Marketing Preferences',\n ],\n];\nTo activate this feature, you just need to create the configuration file. From the root directory of IXP Manager just:
cp config/contact_group.php.dist config/contact_group.php\nNote that Role is a default option and should not be removed.
In these examples, ROLE will be entered in the database column and Role will be displayed in the interface.
Group options can then be added / edited / deleted via the web interface. This can be reached by clicking Contacts in the left-hand side menu and then the sub-menu option that appears called Contact Groups.
"},{"location":"usage/contacts/#creating-editing-deleting-groups","title":"Creating / Editing / Deleting Groups","text":"A group is defined by:
You define the group types in config/contact_group.php.
In these examples, ROLE will be entered in the database column and Role will be displayed in the interface.
Groups can then be added / edited / deleted via https://www.example/com/ixp-manager/contact-group. This can be reached by clicking Contacts and then Contact Groups in the left menu.
Assigning contacts to groups is done in the contact add / edit page.
"},{"location":"usage/contacts/#exporting-contact-groups","title":"Exporting Contact Groups","text":"Contact groups can be exported using the artisan command, for example:
./artisan contact:export-group --type=ROLE --cid=1 --format=csv\nwhere the possible options are (from ./artisan contact:export-group --help:
$ ./artisan contact:export-group --help\nUsage:\n contact:export-group [options]\n\nOptions:\n --type[=TYPE] Contact group type (e.g. ROLE)\n --name[=NAME] Contact group name (e.g. beer)\n --format[=FORMAT] Output format - one of json (default) or csv [default: \"json\"]\n --cid[=CID] Optionally limit results to given customer id\n\nHelp:\n Export contacts based on group information\nThe default sample configuration file (config/contact_group.php) and the database seeds create a ROLE group type populated with groups Admin, Billing, Technical and Marketing. There is a dedicated form element when editing contacts for any groups defined in the Role type.
If the role type is removed from the configuration, the form element for the contact's roles will not be shown.
"},{"location":"usage/contacts/#historical-perspective","title":"Historical Perspective","text":"IXP Manager of pre-April 2013 had separate contacts and users which - at the time - we felt was quite confusing. LONAP sponsored a rework of this in 2013 to merge the concept of users and contacts with login privileges. Strangely, this actually caused more confusion and also was a developer nightmare with hacked in code to handle the database tables in multiple places. As such, in 2019 with release v4.9, this was undone and contacts and users are now separate entities again.
"},{"location":"usage/cookies/","title":"Cookies and Privacy","text":"IXP Manager is open-source and free software. Any individual or organisation who installs IXP Manager and/or makes it available for use must ensure that they are complying with all appropriate data protection legislation in their jurisdiction as the data controller.
This page details what the developers consider appropriate information to the best of their knowledge for helping such organisations with such compliance. Note also that the information herein is based on IXP Manager's default configuration.
"},{"location":"usage/cookies/#cookies","title":"Cookies","text":"Cookies are small text files that websites place on your device as you are browsing. They are processed and stored by your web browser. Cookies can generally be easily viewed and deleted via your browser's functionality. Each cookie is unique to your web browser and will usually contain information such as the cookie name, a unique identifier, and the website's host name or domain name.
IXP Manager uses a PHP web application framework called Laravel and it generates two encrypted cookies which are required to use the application:
Cookie Name Purpose and Description Classification Lifetimelaravel_session Session management - since HTTP driven applications are stateless, sessions provide a way to store information about the user across multiple requests. These cookies are encrypted by the server and the client browser only receives and stores the encrypted version. Strictly Necessary 120 minutes XSRF-TOKEN Cross-site request forgeries are a type of malicious exploit whereby unauthorized commands are performed on behalf of an authenticated user. Laravel stores the current CSRF token in an encrypted XSRF-TOKEN cookie that is included with each response generated by the framework. Strictly Necessary 120 minutes A third cookie is generated if a user optionally invokes the Remember Me functionality during login / authentication:
Cookie Name Purpose and Description Classification Lifetimeremember_web_xxx Session management cookie to facilitate longer sessions and multiple session functionality. These cookies are encrypted by the server and only the encrypted version exists on the client side browser. These only contain a session ID. The server records the user's IP address and a browser identifier (e.g. Macintosh 10 / Firefox 109.0) so that users can identify and optionally delete long-lived sessions in the user interface. Strictly Necessary 30 days IXP Manager does not generate any other cookies.
"},{"location":"usage/cookies/#strictly-necessary-cookies","title":"Strictly Necessary cookies","text":"Strictly Necessary cookies are essential for you to browse the website and use its features, such as accessing secure areas of the site. For example, these cookies let us recognise that you have an account and you have logged into that account. These necessary cookies also allow the portal to remember you and avoid having to log you in on each site visit, or to prevent cross-site scripting security issues.
IXP Manager uses only first-party strictly necessary cookies. IXP Manager does not use third-party cookies.
"},{"location":"usage/cookies/#cookies-and-eu-eprivacy-and-gdpr-law","title":"Cookies and EU ePrivacy and GDPR Law","text":"As IXP Manager generates only Strictly Necessary cookies, it does not need to receive users' consent for the use of these cookies.
"},{"location":"usage/cookies/#data-protection-and-privacy","title":"Data Protection and Privacy","text":"The following table is a summary of personal data collected by IXP Manager and for what purpose / activity:
Data Collected Purpose / Activity Contact details including name, position and role, phone number, email address, etc. These are stored on a per member basis and customer admins can also add, edit and remove these. To manage and facilitate customers / members of an exchange; usually in the performance of a contract. Usernames and passwords To provide members / customers with access to secure areas of IXP Manager; usually in the performance of a contract. Login history (IP address, date and time) To provide an auditable record of when users logged into IXP Manager; usually in compliance with ISMS policies. Login IP address and browser identifier To enable users to identify and optionally delete long-lived sessions that they opt into. Generic note fields Many records on IXP Manager allow admins to enter free text notes. You should ensure you have appropriate policies for this. Their use would be to manage and facilitate customers / members of an exchange; usually in the performance of a contract. Document store - file uploads Admins can upload files to a central store or to a per customer / member store. You should ensure you have appropriate policies for this. The suggested use case is copies of contracts; service order forms; etc."},{"location":"usage/cookies/#correctness-and-disclaimer","title":"Correctness and Disclaimer","text":"This information is correct as of November 2023 for the IXP Manager application as distributed and unaltered from its official source code repository at inex/IXP-Manager. Some IXPs may install it on domains hosting other web sites / applications which may generate their own domain-scoped cookies.
The cookie lifetimes provided above are the defaults but are configurable.
"},{"location":"usage/core-bundles/","title":"Core Bundles","text":"DRAFT: THIS IS A WORK IN PROGRESS AND NOT READY FOR PRODUCTION USE - BARRYO Dec 2017
This section explains how to manage core bundles - a core bundle is sometimes called an ISL (Inter-Switch Link). It is a link that connects two IXP switches together to carry production IXP traffic.
Before reading this, it is expected that you have read and have a good understanding of the concepts from Customer Connections. Virtual Interfaces (VIs), Physical Interfaces (PIs) and how they relate to Switch Ports (SPs) also apply here.
"},{"location":"usage/core-bundles/#core-bundles-types-and-database-overview","title":"Core Bundles Types and Database Overview","text":"IXP Manager supports three types of core bundles:
From IXP Manager's database perspective, these all are represented as follows:
From this, please note the following terminology, relationships and abbreviations which will be used throughout this document:
The only way to provision a new core bundle is to use the wizard. This can be accessed by:
When you open the wizard, you will see something like the following (note this example represents the options for ECMP):
This can be used to provision a single port standard customer connection. If they customer needs a LAG or other non-standard options, these can be added afterwards.
"},{"location":"usage/core-bundles/#general-interface-settings","title":"General Interface Settings","text":"The customer should be prefilled and read-only as you enter the wizard from a specific customer overview page.
You would normally just select your main / primary peering VLAN from the VLAN dropdown. There are some notable exceptions:
Use 802.1q framing checkbox if the port should be tagged facing the customer. If you are not using any automation tools, this will be informational for you rather than production affecting.This section allows you to select the physical interface / switch port for the connection.
Switch: a dropdown list of all switches. Be careful as at present this list is all active switches rather than switches on the same infrastructure as the selected VLAN from General Interface Settings.Port: the switch port to use. This is dynamically populated when the switch is selected and will only show ports of type Peering or type Unset / Unknown (these are set on a per port basis when adding / editing switches).Status: the port status currently has one of five options. They effectively work as a boolean where Connected means on/enabled and the rest mean disabled as explained below. In practice, we tend to just use three states:
Connected: this is the most important. When a virtual interface has any port with the Connected state, then IXP Manager will consider this connection active and will generate router configuration, monitoring configuration, etc.
Awaiting X-Connect: the customer has requested an upgrade / new port and we are awaiting for the co-location provider / customer to get the cross connect organised.Quarantine: the port is connected and is under going quarantine prior to being moved onto the production peering LAN. During quarantine, INEX checks the port to ensure only ARP, IPv4 and IPv6 packets are received (no *-discovery, STP, etc. as well as a number of other things).The Not Connected and Disabled states have the same effect as (2) and (3) above and can be used as informational settings where (2) and (3) do not apply.
Speed and duplex are self explanatory. These settings in the physical interface entity are informational unless you are doing automation. They also have knock on effects to (for example) graphing - where the MRTG max value on an interface is set to this to prevent weird excessive spikes on counter rollovers.
"},{"location":"usage/core-bundles/#general-vlan-settings","title":"General VLAN Settings","text":"These settings apply to the VLAN interface.
The Max BGP Prefixes is a setting used to determine max prefixes on router BGP peers - please see the global version of this as explained in the customer section for details.
If Apply IRRDB Filtering is not set, then the route servers will accept any prefixes advertised by the customer (note that the default templates will filter martians and apply a max prefix limit). Generally speaking this is a very bad idea and should only be used in exceptional cases. INEX never uses this setting - but demand from other IX's had it added.
Multicast Enabled is informational only. INEX used to support multicast on the peering LAN but removed support in 2015 due to lack of interest and added complexity / cost when purchasing new switches.
If Route Server Client is checked, then IXP Manager will configure a BGP peer for this connection when generating route server configurations. It is also used in other areas to show if a member uses the route servers or not, by the Peering Manager to calculate missing BGP sessions, etc.
Similarly, if AS112 Client is checked, then IXP Manager will configure a BGP peer for this connection when generating AS112 router configurations.
When IPv4 / IPv6 Enabled is checked under General Interface Settings above, these two sections will be available.
The same details apply to IPv4 and IPv6 options so we will document them together.
IP Address: the IP address to assign to this customer. This is taken from available IP addresses for the VLAN selected in General Interface Settings.Hostname: if you use IXP Manager to configure your DNS ARPA entries, the hostname entered here will be returned when a PTR request is made for the assigned IP address. Enter a complete hostname without trailing period such as: www.example.com.BGP MD5 Secret: The will be used for generating router configurations.Can Ping: IXP Manager generates configuration for a number of other tools such as Smokeping and Nagios which ping customer routers. These are invaluable tools for problem solving, monitoring and graphing long term trends. We enable this by default unless a customer specifically asks us not to.Can Monitor RC BGP: this is more of a legacy option for configuration builders that used to check for established route collector BGP sessions and warn if not present. This is deprecated and will be removed.Once an interface has been added as per the above wizard instructions, you can view and edit the interface by selecting the edit icon against the connection you are interested in from the Ports tab on the customer overview page. When you do that, you will see a screen such as the following:
You can see from the layout of this screen how it ties in with the schema explained above.
"},{"location":"usage/core-bundles/#virtual-interface-details","title":"Virtual Interface Details","text":"The screenshot above shows the virtual interface details with the Advanced Options shown. The additional fields here that were not in the wizard are described below.
Link aggregation / LAG framing is mostly informational unless you are doing automation. There are some restrictions. Namely / specifically:
The Virtual Interface Name is again mostly informational unless you are doing automation. It should be the start of the LAG name without the number. On an IOS device this would be Port-channel for example. Matched with this is the Channel Group Number with is tacked onto the end of the Virtual Interface Name. Leave it as 0 and when you check Link aggregation / LAG framing and save the changes, IXP Manager will set this to the next available unused port channel / bundle / LAG number on that switch.
Both Description and MTU are informational.
You can add additional physical interfaces to a connection / virtual interface. This effectively means you are creating a LAG. The form for adding additional physical interfaces is identical to that in the wizard.
"},{"location":"usage/core-bundles/#vlan-interfaces","title":"VLAN Interfaces","text":"The most common use case of more than one VLAN Interface is when your customer may also have private VLANs on their connection.
Other than that, the VLAN interface add / edit form has all the same elements as the wizard with one addition:
Busy host: this flag indicates that the customer's router is unusually slow to reply to ICMP echo requests and that when monitoring, the configuration should allow for warnings after a 5sec RTT rather than 1sec.IXP Manager allows administrators to add notes to customer records via the customer overview page.
Some of the features currently supported include:
The following image shows the standard customer overview page (as per v4.8.0) with the Notes tab selected and two sample notes:
The first note, Sample Private Note, is a note that is only visible to administrators. The second note, Test Public Note, is visible to any user logged in for this customer.
The next image shows the dialog for adding a customer note.
By default, notes are private and you are required to check the Makee note visible to customer to make it a public note.
The Preview table allows you to see what the note will look like when formatted via Markdown:
Existing notes can be edited, deleted and viewed:
"},{"location":"usage/customer-notes/#notifications","title":"Notifications","text":"As mentioned above, administrators can choose to be alerted by email to new / edited / deleted notes in one of four ways:
On an administrator's My Account -> Profile page, you will find the following:
The first of these radio options, Disable all email notifications, corresponds to (1) never above. The last of these radio options, Email me on any change to any customer note corresponds to (2) all notes for all customers above.
The middle option, Email me on changes to only watched customers and notes, is controlled via the bell icon on the customer overview notes tab. If a user had requested notifications as follows:
then all changes to any customer note for AS112 Reverse DNS [AS112] will be emailed to the user because the customer bell (the one on the top right) has been selected.
If the user had not selected the customer bell then:
The order of precedence for determining if a note change should be notified by email is:
If neither (1) nor (2) hold above, then the user has selected the radio option Email me on changes to only watched customers and notes. In which case a notification is sent for the customer whose note is being added / edited / deleted:
a. if the customer bell is selected for the customer in question b. if the note bell is selected for the note in question
Otherwise no notification is sent.
IXP Manager allows administrators to tag customers to indicate specific properties that are not built into IXP Manager by default. Some examples might include:
Tags can be added / edited / deleted by clicking on the Customers option in the left hand side menu and then clicking on the Tags sub-option which appears. The form for adding tags is pretty straight-forward:
While the help text should be self-explanatory, here is some more detail and examples:
Tag: should be something like: commercial, member, 100mb-upgrade-program. Note that these are always lowercase alphanumeric characters and optional dashes.
Display AS: allows you to provide something prettier when displaying the tag within IXP Manager. Examples following from the above might include: Commercial, Member, 100Mb Upgrade Program.
Description: allows you to add some text that may help you remember the specific use-case of a tag in five years time!
Internal Only: if not set, then tags can be optionally including in various public / non-superadmin accessible APIs / pages / exports.
When at least one tag has been created, the customer overview masthead will now provide the option to add tags to customers:
Once one or more tags have been added, they are shown in the masthead such as:
You will also find an option in the Edit menu of the customer overview page to Manage Tags....
"},{"location":"usage/customer-tags/#exporting-tags","title":"Exporting Tags","text":"Tags can be exported as part of the IX-F Member Export process by adding ?withtags=1 to the API URL. For example:
https://ixp.example.com/api/v4/member-export/ixf/0.7?withtags=1\nYou have to specify ?withtags=1 as this is not part of the official IX-F Member Export specification.
When you request this, you will find an empty object with each customer that does not have tags in an ixp_manager namespace of the form:
\"ixp_manager\": {\n \"tags\": []\n}\nAnd for those that do have tags, it will be of the form:
\"ixp_manager\": {\n \"tags\": {\n \"test-tag1\": \"Test Tag1\",\n \"test-tag2\": \"Test Tag2\"\n }\n}\nwhere test-tag2 is the tag and Test Tag2 is the display name.
We created a video tutorial demonstrating these steps. You can find the video here in our YouTube channel. As always, the full catalog of video tutorials is here.
"},{"location":"usage/customers/#adding-customers","title":"Adding Customers","text":"To add a new customer in IXP Manager, select the Customers option from the left hand side admin menu and then click the [+] icon on the top right. You'll find yourself with a form such as (may vary over time):
What follows is an explanation of each section.
"},{"location":"usage/customers/#customer-details","title":"Customer Details","text":"The Name field is the customer's name as you/they typically want it to appear in IXP Manager. It is not necessarily their full legal entity name (that goes elsewhere). The Abbreviated Name is a shorter version of the name that is used in space constrained areas such as graph labels.
The Type field is a dropdown with the following meanings:
Full: this is what you will use most of the time. This is a full / normal trafficking IXP member.Pro-bono: like full but for organisations that you provide IXP access to for the good of the internet / your members. Examples at INEX include the AS112 service, Packet Clearing House's route collector and DNS TLD/root services and other DNS root servers such as the RIPE K root / Verisign, etc.Internal: while not enforced, you should really only have two internal customers which is the IXP itself and, separately, the IXP route servers. Connections / interfaces such as route collectors and core links would be associated with the IXP customer. Because route servers typically have a dedicated ASN, they would have their own customer with their interfaces associated here.Associate: INEX has a concept of associate members which enables those organisations who are involved in the IP and networking industry, but who do not have their own IP traffic to peer, an opportunity to participate in the extensive INEX community. See full details here. Associate customers in IXP Manager have very limited functionality but it allows us to keep track of them.The Shortname field is something we are slowly removing. It is currently visible in some URLs and a couple other areas. It should be a lowercase single word ([a-z0-9]) and it should not be changed after it is set.
The Corporate Website is used when linking the customer name in various customer lists. It must be a valid URL. Try and stick to the scheme: http://www.example.com/ - i.e. include http[s]:// and end with a trailing slash.
The Date Joined is just that and must be set. However, the Date Left has real consequences: setting Date Left effectively closes the customer's account. This means configuration will no longer be included for graphing, router configuration, etc. We tend not to delete customers but mark them as closed by setting this field.
Status yields three options. The most important of which is Normal which is what you'll use nearly 100% of the time. Setting either of the other two options (Suspended / Not Connected) will have the same effect as closing the account as described above: removing route server / collector sessions, graphing configuration, etc.
MD5 Support: this is not something that has been fully integrated into all view screens. You should probably default to Yes for now as this will cover 95+% of cases. It is an informational flag only for member to member bilateral peering.
The AS Number is just the integer value without any AS prefix, etc.
Max Prefixes is known as the global max prefixes value. It is used to work out the appropriate max prefixes value to apply to all router configurations in the stock / default templates (route collector and servers, AS112). The calculated value is also included in emails from the Peering Manager from customer to customer.
There are two issues with max prefixes:
The max prefixes value is worked out in the code when generating router configuration is as follows:
At INEX, we default to 50 for small members, and 250 for medium sized members (who may already have 50 say), and as advised by larger members.
The Peering Email is used in member lists and by the Peering Manager for sending emails. We try and encourage an alias of peering@example.com but this does not always work out.
The IPv4 Peering Macro is used instead of the AS number when set to generate inbound prefix filters for the route servers based on the member's published IRR records. AS-BTIRE in the RIPE database is an example for BT Ireland.
The IPv6 Peering Macro was added for another IX using IXP Manager that had a customer which used a separate macro for v4 and v6. We only know of that single instance of this. In the event that IPv6 Peering Macro is set, this will be used to generate IPv6 inbound prefix filters, otherwise the IPv4 Peering Macro will be used for both. If neither is set, the IRR policy of the AS number will be used. Use AS-NULL to disable one or the other protocol peering macro if only one is required.
It is not possible to have a different ASN for IPv4 and IPv6. We are not aware of any cases where this should be necessary but if it is, create two customers.
The Peering Policy is informational only and is displayed in member lists. Typically speaking, route server members should have an open peering policy but others are possible if you use standard route server communities for controlling the distribution of prefixes.
The IRRDB source sets the database where IXP Manager queries the customer's IRR data from. See the IRRDB feature page for more information.
The checkbox labelled Active Peering Matrix indicates whether or not the customer's route server and bilateral peering sessions should appear in the public peering matrix.
All of this is purely informational and is used by IX staff to contact the member about various issues. It is also available to other customers of the exchange to similarly contact their bilateral peers with any issues.
"},{"location":"usage/customers/#reseller-details","title":"Reseller Details","text":"This section will only be displayed if reseller functionality is enabled.
See the reseller instructions for details on this.
"},{"location":"usage/customers/#welcome-emails","title":"Welcome Emails","text":"When a new customer is provisioned, you can send them a welcome email from IXP Manager which is a useful way to provide all their connectivity details and other on-boarding information for your IX.
From the Customer Overview page, you will find the Send Welcome Email... option under the tools menu on the top right hand corner of the page:
To be useful, you need to skin the welcome email.
From IXP Manager v4.8.0 onwards, its format is Markdown and it is sent as a HTML email. The file you need to skin is (with an example of how to do it):
cd ${IXPROOT}\nmkdir -p resources/skins/example/customer/emails\ncp resources/views/customer/emails/welcome-email.blade.php resources/skins/inex/customer/emails/\nThe example skin name in the above is just an example. Please read the skinning documentation.
Customer users and administrators can upload and manage logos for customers. To enable this functionality, set the following in your ${IXPROOT}/.env file:
IXP_FE_FRONTEND_DISABLED_LOGO=false\nWhen you do this, the ability to manage logos will appear:
Logos will then be shown in the customer overview page and a new admin left-hand-side menu option called Member Logos (which shows all logos).
Logos are stored under ${IXPROOT}/public/logos in a sharded directory structure based on the SHA1 of the image content.
Following a feature request, we have a configuration option which can be set to allow each IXP Manager installation customise how the customer / member name is displayed. E.g. Acme Ltd or Acme Ltd (AS65500) for example.
You can customise this by setting the following option in your .env:
IXP_FE_CUSTOMER_NAME_FORMAT=\"\"%a (AS%i)\"\nThe above is the default which uses the abbreviated name and the customer's ASN. You can see the available options in the config/ixp_fe.php file.
You can also find more detail in this issue thread.
"},{"location":"usage/customers/#registration-and-billing-details","title":"Registration and Billing Details","text":"After you add a new customer (or from the customer overview page from the dropdown edit icon on the right of the title area, you can select Edit Billing/Registration Details), you will get the following form:
All of these details are informative only and only available to administrative users.
"},{"location":"usage/customers/#notification-of-billing-details-changed","title":"Notification of Billing Details Changed","text":"If you want notification of a customer's billing details being changed by email, set the following parameter in your ${IXPROOT}/.env file:
IXP_FE_CUSTOMER_BILLING_UPDATES_NOTIFY=\"mail@example.com\"\nThis can be useful to alert your accounts / billing staff of these changes automatically.
If you need multiple people notified, use an alias address encompassing all the users.
Prior to v4.8, you had to edit the config/ixp_tools.php configuration file and set the billing_updates_notify array element. If this file does not exist, create it from the suggested template: cp config/ixp_tools.php.dist config/ixp_tools.php.
IXP Manager makes customer/member details available publicly (without login) through the Member Information menu item. To disable this, set the following in your .env:
IXP_FE_CUSTOMER_DETAILS_PUBLIC=false\nIn IXP Manager v6, we changed the database access layer to Laravel's Eloquent. As part of this work, we added a new listener for any UI based changes to database objects.
You will find [View logs] buttons through IXP Manager and these will link to the appropriate entries in the Logs controller (which you can find in the left hand menu under IXP UTILITIES).
NB: logs are expunged after six months. We feel this is a useful compromise between: auditing changes; keeping the database from growing unnecessarily large; and data privacy (as logs include user and contact objects).
A sample of the logs list for a rack / cabinet:
As you can see, for the purposes of demonstration, I created, edited and then deleted a rack.
The creation log contains:
The edit log highlights the changes made:
The creation log contains:
And the deletion log retains the data:
"},{"location":"usage/email/","title":"Configuring Email","text":"IXP Manager uses Laravel's mail system to send email. This system allows for many possible email sending drivers (such as Mailgun, Postmark, Amazon SES, etc.). If you wish to use one of these services than please refer to the official documentation. You can also read the config/mail.php configuration file in your IXP Manager installation for further details. NB: we link to the 'master' version of Laravel's documentation above - see IXP Manager's composer.json file and use the appropriate version of Laravel's documentation to match.
This guide will explain how to configure and test IXP Manager to send email using a standard SMTP service.
"},{"location":"usage/email/#configuring-smtp","title":"Configuring SMTP","text":"A sample SMTP configuration block in your IXP Manager .env file would be:
### Email Settings.\n#\n# We use Laravel's mail system - see: https://docs.ixpmanager.org/usage/email/\n#\n# The default setting are as follows:\n#\n# MAIL_MAILER=\"smtp\"\n# MAIL_HOST=\"localhost\"\n# MAIL_PORT=25\n# MAIL_ENCRYPTION=false\n# MAIL_USERNAME=\n# MAIL_PASSWORD=\nThe options that are commented out above show defaults. Under the hood, Laravel currently uses swiftmailer and the parameters above are passed through to that library (this changes from Laravel v9).
The configuration options for SMTP in the .env file are as follows.
MAIL_MAILER=\"smtp\" - this is the mail transport to use. The other available options are outside the scope of this documentation.
MAIL_HOST is the hostname or IP address of your SMTP relay server. We would generally expect an IXP to have an internal SMTP relay server within the management network to handle the sending of email from monitoring systems, cron processes, IXP Manager, etc. This can also be localhost or 127.0.0.1 if you are running a local daemon such as Postfix.
MAIL_PORT is the TCP port which the mail relay server listens for connections. Typical values are 587 for TLS encrypted mail servers and 25 for unencrypted mail servers (these should be on your local network only - if you are using a third party or remote relay service, you should use TLS or SSL encryption).
MAIL_ENCRYPTION can be \"tls\" or \"ssl\" for encryption. If you are using localhost or an internal relay server without encryption, set this to MAIL_ENCRYPTION=false.
Finally, MAIL_USERNAME and MAIL_PASSWORD can be set if your mail relay server requires authentication. If unset, then no authentication is assumed (which is the default).
A local SMTP relay server on the same host as IXP Manager would therefore require no configuration as the defaults mirror:
MAIL_MAILER=\"smtp\"\nMAIL_HOST=\"localhost\"\nMAIL_PORT=\"25\"\nMAIL_ENCRYPTION=false\n# MAIL_USERNAME=\n# MAIL_PASSWORD=\nIXP Manager sends emails using the name and email address configured in the following .env parameters:
IDENTITY_NAME=\"${IDENTITY_LEGALNAME}\"\nIDENTITY_EMAIL=\"ixp@example.com\"\nWhere ${IDENTITY_LEGALNAME} means use the value as configured in the IDENTITY_LEGALNAME .env parameter.
You should set these as appropriate to your IXP.
"},{"location":"usage/email/#testing-smtp","title":"Testing SMTP","text":"A new Artisan SMTP test utility was introduced in IXP Manager >v5.7.0. You can run it as follows:
$ php artisan utils:smtp-mail-test [-v] {recipient-email}\nA example of a working test run looks like this:
$ php artisan utils:smtp-mail-test me@example.com\nThis utility allows you to test your SMTP settings to verify that IXP Manager can send email.\n\nTesting using the following parameters:\n\n+------------+---------------------+\n| Driver | smtp |\n| Host | localhost |\n| Port | 25 |\n| Encryption | |\n| Username | |\n| Password | |\n| From Name | INEX DEV IXP |\n| From Email | test@ixpmanager.org |\n+------------+---------------------+\n\n\n\nTrying to send email...\n\nSUCCESS - email has been sent.\nIf you add the verbose option you will also be shown the SMTP dialog:
$ php artisan utils:smtp-mail-test -v me@example.com\n\n...\n\n========================================\nSMTP Dialog:\n\n++ Starting Swift_SmtpTransport\n<< 220 mail.example.com ESMTP Postfix\n\n>> EHLO [127.0.0.1]\n\n<< 250-mail.example.com\n250-PIPELINING\n250-SIZE 80200000\n250-VRFY\n250-ETRN\n250-STARTTLS\n250-ENHANCEDSTATUSCODES\n250-8BITMIME\n250-DSN\n250 SMTPUTF8\n\n>> STARTTLS\n\n<< 220 2.0.0 Ready to start TLS\n\n...\nIf there is an error sending an email, it will provide the exception thrown and the error message:
...\nTrying to send email...\n\nFAILED TO SEND EMAIL!\n\n\n\nException thrown: ErrorException\nError: stream_socket_enable_crypto(): Peer certificate CN=`mail.example.com' did not match expected CN=`192.0.2.16'\nFile: /tmp/dev/ixpm/vendor/swiftmailer/swiftmailer/lib/classes/Swift/Transport/StreamBuffer.php\nLine: 94\nSimilarly, if you provide the verbose option in the case of an error, you will be provided with a stack trace and the SMTP dialog.
"},{"location":"usage/interfaces/","title":"Customer Interfaces","text":"This section explains how to set up a customer interface.
"},{"location":"usage/interfaces/#video-tutorial","title":"Video Tutorial","text":"We created a video tutorial demonstrating these steps. You can find the video here in our YouTube channel. As always, the full catalog of video tutorials is here.
"},{"location":"usage/interfaces/#database-overview","title":"Database Overview","text":"To fully understand how IXP Manager treats customer interfaces, you need a little background on the database schema. This will also help explain why we have laid out the UI as it is.
The original database schema dates from pre-2005 and has stood the test of time extremely well.
The above is described as follows:
The best way to provision a new interface for a customer is to use the wizard. This can be accessed from the customer's overview page via a menu on the top right:
When you open the wizard, you will see:
This can be used to provision a single port standard customer connection. If they customer needs a LAG or other non-standard options, these can be added afterwards.
"},{"location":"usage/interfaces/#general-interface-settings","title":"General Interface Settings","text":"The customer should be prefilled and read-only as you enter the wizard from a specific customer overview page.
You would normally just select your main / primary peering VLAN from the VLAN dropdown. There are some notable exceptions:
Use 802.1q framing checkbox if the port should be tagged facing the customer. If you are not using any automation tools, this will be informational for you rather than production affecting.This section allows you to select the physical interface / switch port for the connection.
Switch: a dropdown list of all switches. Be careful as at present this list is all active switches rather than switches on the same infrastructure as the selected VLAN from General Interface Settings.Port: the switch port to use. This is dynamically populated when the switch is selected and will only show ports of type Peering or type Unset / Unknown (these are set on a per port basis when adding / editing switches).Status: the port status currently has one of five options. They effectively work as a boolean where Connected means on/enabled and the rest mean disabled as explained below. In practice, we tend to just use three states:
Connected: this is the most important. When a virtual interface has any port with the Connected state, then IXP Manager will consider this connection active and will generate router configuration, monitoring configuration, etc.
Awaiting X-Connect: the customer has requested an upgrade / new port and we are awaiting for the co-location provider / customer to get the cross connect organised.Quarantine: the port is connected and is under going quarantine prior to being moved onto the production peering LAN. During quarantine, INEX checks the port to ensure only ARP, IPv4 and IPv6 packets are received (no *-discovery, STP, etc. as well as a number of other things).The Not Connected and Disabled states have the same effect as (2) and (3) above and can be used as informational settings where (2) and (3) do not apply.
Speed and duplex are self explanatory. These settings in the physical interface entity are informational unless you are doing automation. They also have knock on effects to (for example) graphing - where the MRTG max value on an interface is set to this to prevent weird excessive spikes on counter rollovers.
"},{"location":"usage/interfaces/#general-vlan-settings","title":"General VLAN Settings","text":"These settings apply to the VLAN interface.
The Max BGP Prefixes is a setting used to determine max prefixes on router BGP peers - please see the global version of this as explained in the customer section for details.
If Apply IRRDB Filtering is not set, then the route servers will accept any prefixes advertised by the customer (note that the default templates will filter martians and apply a max prefix limit). Generally speaking this is a very bad idea and should only be used in exceptional cases. INEX never uses this setting - but demand from other IX's had it added.
Multicast Enabled is informational only. INEX used to support multicast on the peering LAN but removed support in 2015 due to lack of interest and added complexity / cost when purchasing new switches.
If Route Server Client is checked, then IXP Manager will configure a BGP peer for this connection when generating route server configurations. It is also used in other areas to show if a member uses the route servers or not, by the Peering Manager to calculate missing BGP sessions, etc.
Similarly, if AS112 Client is checked, then IXP Manager will configure a BGP peer for this connection when generating AS112 router configurations.
When IPv4 / IPv6 Enabled is checked under General Interface Settings above, these two sections will be available.
The same details apply to IPv4 and IPv6 options so we will document them together.
IP Address: the IP address to assign to this customer. This is taken from available IP addresses for the VLAN selected in General Interface Settings.Hostname: if you use IXP Manager to configure your DNS ARPA entries, the hostname entered here will be returned when a PTR request is made for the assigned IP address. Enter a complete hostname without trailing period such as: www.example.com.BGP MD5 Secret: The will be used for generating router configurations.Can Ping: IXP Manager generates configuration for a number of other tools such as Smokeping and Nagios which ping customer routers. These are invaluable tools for problem solving, monitoring and graphing long term trends. We enable this by default unless a customer specifically asks us not to.Can Monitor RC BGP: this is more of a legacy option for configuration builders that used to check for established route collector BGP sessions and warn if not present. This is deprecated and will be removed.If you wish to make Hostname above optional, set the following .env configuration option:
IXP_FE_VLANINTERFACES_HOSTNAME_REQUIRED=false\nOnce an interface has been added as per the above wizard instructions, you can view and edit the interface by selecting the edit icon against the connection you are interested in from the Ports tab on the customer overview page. When you do that, you will see a screen such as the following:
You can see from the layout of this screen how it ties in with the schema explained above.
"},{"location":"usage/interfaces/#virtual-interface-details","title":"Virtual Interface Details","text":"The screenshot above shows the virtual interface details with the Advanced Options shown. The additional fields here that were not in the wizard are described below.
Link aggregation / LAG framing is mostly informational unless you are doing automation. There are some restrictions. Namely / specifically:
The Virtual Interface Name is again mostly informational unless you are doing automation. It should be the start of the LAG name without the number. On an IOS device this would be Port-channel for example. Matched with this is the Channel Group Number with is tacked onto the end of the Virtual Interface Name. Leave it as 0 and when you check Link aggregation / LAG framing and save the changes, IXP Manager will set this to the next available unused port channel / bundle / LAG number on that switch.
Both Description and MTU are informational.
You can add additional physical interfaces to a connection / virtual interface. This effectivily means you are creating a LAG. The form for adding additional physical interfaces is identical to that in the wizard.
"},{"location":"usage/interfaces/#vlan-interfaces","title":"VLAN Interfaces","text":"The most common use case of more than one VLAN Interface is when your customer may also have private VLANs on their connection.
Other than that, the VLAN interface add / edit form has all the same elements as the wizard with one addition:
Busy host: this flag indicates that the customer's router is unusually slow to reply to ICMP echo requests and that when monitoring, the configuration should allow for warnings after a 5sec RTT rather than 1sec.In cases where the IXP provides subrate connectivity, the declared port speed at an IXP may not match the port speed which is configured on the access device. Support for this scenario was included in v6.2.0:
rate_limit column on the database as the actual request for partial port speeds is really a request to honour rate limits on ports. If there are other use cases this can still be used, the actual physical (production) effect is determined by how individual IXPs use this information in their provisioning systems / as they manually configure switches.This page will collect various operational notes, hints and tips and FAQs over time.
"},{"location":"usage/operational-notes/#server-topology","title":"Server Topology","text":"Added 2020-10-28, Nick Hilliard
On the mailing list, we were asked about recommended server topologies. Nick answered:
At INEX, we split services over different physical machines running virtual servers to keep them as separate as possible. This means we can perform maintenance on individual components relatively easily without affecting other components. Currently we have the following configured:
We run route servers on different physical servers. They're kept separate (different hardware, different hypervisor, not attached to the orchestration system) because they're categorised as critical production servers, i.e. if they go down, production IXP traffic may be affected.
It doesn't really matter what hypervisor software you use. We've used ESXi, Xencenter and XCP-ng and they all work fine. Our current preference is for XCP-ng because it provides live migration of VMs on local disk storage without a license (XC and ESXi both need a license for this).
It would be a good idea to use two physically identical servers for the hypervisor, so that you can use services like VM migration and live-migration. For disk storage, we'd recommend RAID with battery backup, so that you can add or replace physically failed disks easily.
One thing that does matter is disk I/O on the sflow server - if you have anything more than about 30 IXP participants, then you need SSD to handle the iops.
"},{"location":"usage/operational-notes/#backup-ixp-manager","title":"Backup IXP Manager","text":"Added 2020-03-24, Barry O'Donovan
On the mailing list, someone asked about backing up IXP Manager before an upgrade. Barry O'Donovan answered this here and the advice was:
It's not something I generally do as we have our production servers backed up nightly. But:
Assuming you have IXP Manager installed at /srv/ixpmanager then I'd proceed as follows (replacing yyyymmdd with today's date):
Put IXP Manager in maintenance mode (php /srv/ixpmanager/artisan down).
Take a MySQL dump:
mysqldump --lock-tables --quick --skip-events --triggers \\\n -h <host> -u <username> -p<password> ixpmanager | \\\n bzip2 -9 >/srv/ixpmanager/db-yyyymmdd.sql.bz2\nDuplicate the IXP Manager directory in its entirety:
rsync -a /srv/ixpmanager/ /srv/ixpmanager-yyyymmdd\nUpgrade IXP Manager per the usual instructions.
If you need to rollback then:
Restore the database from the dump above:
bzcat /srv/ixpmanager/db-yyyymmdd.sql.bz2 | \\\n mysql -h <host> -u <username> -p<password> ixpmanager\nShift the directories around:
mv /srv/ixpmanager /srv/ixpmanager-failed\nmv /srv/ixpmanager-yyyymmdd /srv/ixpmanager\nAdded 2020-04-21, Barry O'Donovan
A common question is will IXP Manager work with Nginx + php-fpm considering the automated installation script uses Apache. The short answer is: yes, of course! Use whichever you're most comfortable with.
From experience, people who install IXP Manager and end up asking for installation help are not overly comfortable with Linux / web servers. The easiest installation and maintainable option (by a measurable distance) is Apache. This is why the installation script uses it.
Do we recommend either / any advantages to one over the other? No and no. IXP Manager is a low volume / transaction application. Whatever typical performance benefits you might expect from Nginx + php-fpm simply won't apply here.
"},{"location":"usage/switches/","title":"Switches","text":"The central element of an IXP is the switches. IXP Manager provides comprehensive management features for switches (and more complex configurations such as VXLAN overlay networks).
We strongly advise against trying to add and manage switches in IXP Manager without SNMP. SNMP v2 is a core element of how switches work within IXP Manager including accurate port discovery, graphing, port states, optic availability, etc.
"},{"location":"usage/switches/#listing-switches","title":"Listing Switches","text":"You access the switch management functionality in IXP Manager via the Switches menu option under IXP Admin Actions in the left hand side control menu. The default action is to list the configured switches:
From the above screenshot, you will notice a number of features:
In the list view above, you will also notice that there are per row / per switch options on the right:
From the list view described above, click the plus button in the top right to add a switch. Switches are added by SNMP poll so the first step is to provide a hostname and SNMP v2 community:
The switch must respond to SNMP queries from the server on which IXP Manager is installed. This can be testing on the command line as follows:
root@ixpmanager:~# snmpget -c yourcommunity -v 2c switch01.mgmt.example.com .1.3.6.1.2.1.1.1.0\niso.3.6.1.2.1.1.1.0 = STRING: \"Arista Networks EOS version 4.18.0F running on an Arista Networks DCS-7280SR-48C6\"\nAfter completing the details and clicking Next >>, IXP Manager will poll the switch and present you with the second (and last) stage in adding a switch:
The important things to note about this are:
The discovery of a switches vendor, model, operating system details and serial number - as well as MAU details - is achieved via a third party package called OSS_SNMP. While this shares an author in common with IXP Manager, it is a separate project.
If your switch is not discovered automatically, you can open a ticket with the OSS_SNMP project directly and ensure you provide the details requested here.
"},{"location":"usage/switches/#managing-switch-ports","title":"Managing Switch Ports","text":"Recall the per row / per switch options on the right hand side of each switch's row when listing switches:
These options allow you to list and manage switch ports. Of these, the most relevant is the View / Edit Ports under SNMP Actions which leads to a page as follows:
The page allows you to:
Note that deleting ports is not a permanent action if the port physically exists and is discovered in a subsequent SNMP poll.
"},{"location":"usage/switches/#switch-port-types","title":"Switch Port Types","text":"While some of these are clear from the name, we will explain each type here for completeness:
Switch and switch port information in the database can go stale very quickly. As such, IXP Manager will poll switches using SNMP every five minutes via the task scheduler. You can do it manually via the Artisan command:
/srv/ixpmanager/artisan switch:snmp-poll\nThe command signature is:
switch:snmp-poll [--log] [--noflush] [-q, --quiet] [<switch>]\nwhere:
[-q, --quiet] does not output anything unless there is an error. Should be used for cron jobs.[--log] outputs detailed SNMP polling information to /srv/ixpmanager/storage/logs/laravel.log. You can tail this file when running it to help diagnose any issues.[--noflush] polls the switch but does not write anything to the database.[<switch>] allows you to optionally limit the polling to a single named switch (the switch's name, not hostname). If not specified, all pollable switches are polled.Not that inactive switches are not polled unless an inactive switch name is explicitly specified.
Similarly, any switch that is not set to poll (Poll checkbox with adding / editing a switch) will be skipped unless explicitly specified.
"},{"location":"usage/switches/#matching-database-ports-to-switch-ports","title":"Matching Database Ports to Switch Ports","text":"When we poll the switch to update the database, we need a method to match ports in the database with those on the switch so we can update, remove and add ports. This is achieved using the ifIndex as reported by SNMP.
We have tried other methods in the past including ifName but there is no perfect solution to this as switch operating system updates can cause any of these data points to change. In the end we settled on ifIndex.
If you find that a switch update had caused the ifIndex to change, then you can reindex the database by updating the ifIndex based on the ifName using the switch:reindex-ifindex Artisan command.
To perform a test run and see what would change, execute it per the following example:
$ ./artisan switch:reindex-ifindex swi2-nwb1-3 --noflush\n - swp1 unchanged, ifIndex remains the same\n ...\n - bond2 unchanged, ifIndex remains the same\n - bond3 ifIndex changed from 10056 to 10178\n ...\n - mgmt unchanged, ifIndex remains the same\n\n*** --noflush parameter set - NO CHANGES MADE TO DATABASE\nIf you are comfortable with the changes proposed, rerun it
Operational Note: if performing switch operating system updates that are known to change the ifIndex, it is strongly advised to disable polling (Poll checkbox when adding / editing a switch) for the duration of the upgrade work and until after you have reindexed the ports.
ifType)","text":"By default, IXP Manager restricts the type of port to ifType ethernetCsmacd, l2vlan and l3ipvlan, because most network operating systems include various types of virtual port which are not relevant to IXP operation. Sometimes, some vendors (e.g. Juniper) use a richer set of ports, and a wider selection of ifTypes. If these ifTypes were enabled in the general case, IXP Manager operators would be presented with lots of port types that were irrelevant to their IXP service.
This is a traditional user interface situation: we need a balance between hiding the inherent complexity of what's going on, while enabling enough flexibility to allow the operator to do what they need, while ensuring that the underlying code base and config is maintainable as a long term proposition.
If you examine the file config/ixp.php you'll find an element called snmp['allowed_interface_types']. The default behaviour is equivalent to creating a .env setting as follows:
IXP_SNMP_ALLOWED_INTERFACE_TYPES=\"6,135,136\"\nwhere 6, 135 and 136 are the SNMP codes for ifType ethernetCsmacd, l2vlan and l3ipvlan respectivily. Note that over time we may add more to the default stack - the configuration file will always represent the default status.
If you wish to have IXP Manager poll additional interface / port types on your switch then set this .env variable. For example, to additionally allow irb interfaces on Juniper (which at time of writing use ifOther) then set it as follows:
IXP_SNMP_ALLOWED_INTERFACE_TYPES=\"1,6,135,136\"\nMore detail may be found in the originating GitHub issue #695).
"},{"location":"usage/switches/#migrating-customers-to-a-new-switch","title":"Migrating Customers to a New Switch","text":"When moving IXP customers from one switch to another, add the new switch into the IXP Manager as described above. The customer port assignments can easily be changed to the new switch using the IXP Manager web interface. It is advisable not to delete the old port assignment and create a new one, because if this happens, then the old customer port graphs will not be preserved.
The process is, for each customer:
When the switch port updates have been completed, it's advisable to rebuild the mrtg configuration using the CLI tool and (if using dynamically discovered MAC addresses) also to update the layer 2 database, otherwise some MRTG and sflow stats may be lost.
"},{"location":"usage/switches/#related-tools","title":"Related Tools","text":""},{"location":"usage/switches/#port-audit","title":"Port Audit","text":"A new feature (adding in v4.9.0) allows IXP Manager administrators to audit port speeds as configured in physical interfaces against what has been discovered in the last SNMP run.
You can run it from Artisan such as the following example:
./artisan audit:port-speeds\n\nAudit of Configured Physical Interface Port Speeds Against SNMP Discovered Speeds\n\n+------------------------------+----------+----------------+-----------------------+----------+------------+\n| Customer | PI DB ID | Switch | Switchport | PI Speed | SNMP Speed |\n+------------------------------+----------+----------------+-----------------------+----------+------------+\n| INEX Route Servers [AS43760] | 14 | swi2-tcy1-2 | GigabitEthernet27 | 0 | 1000 |\n| INEX [AS2128] | 15 | swi1-ix1-2 | X460-48t Port 47 | 0 | 1000 |\n| INEX [AS2128] | 16 | swi2-ix1-1 | GigabitEthernet25 | 0 | 1000 |\n| AS112 Reverse DNS [AS112] | 21 | swi2-nwb1-1 | X670G2-48x-4q Port 15 | 0 | 1000 |\n| INEX [AS2128] | 357 | swic-cix-2 | GigabitEthernet27 | 100 | 1000 |\n| AS112 Reverse DNS [AS112] | 590 | swt-cwt1-edge1 | swp3 | 10000 | 1000 |\n+------------------------------+----------+----------------+-----------------------+----------+------------+\nThe above examples are edge cases as they are not physically connected devices but rather virtual machines. This audit can be added to cron such that it will only make noise if an issue is found with something like:
13 9 * * * www-data /srv/ixpmanager/artisan audit:port-speeds \\\n --cron --ignore-pids 14,15,16,21,357,590\nUser management prior to v5.0 was handled differently - please see this page for the legacy usage.
The IXP Manager Users feature allows you to add and manage users (people who can login to IXP Manager) on a per customer basis including:
For details on session management and two-factor authentication, please see this page. For logging in with PeeringDB OAuth, please see this page.
"},{"location":"usage/users/#types-of-users","title":"Types of Users","text":"There are three types of user:
privs = 1).privs = 2).privs = 3). FULL ACCESS TO ALL CUSTOMERS AND FUNCTIONS. This is only for your IXP staff!If you are a Superuser, you can manage users in one of two ways:
If you are a customer administrator user, you can manage your own users via the Users menu in the top menu bar. In all cases, you will be given a list of users such as:
The available actions include:
Since a user can be associated with multiple customers, the new user you wish to add may already exist on the system. For this reason, the first step of adding a user is to just provide and email address:
If the user does not exist, you will be invited to complete the rest of the standard details:
Note that, as always, the [Help] button will provide context help for each input field. Once you successfully complete the details, the new user will be sent a welcome email (see below for details) and invited to set their password.
If any users do exist with this email, you will be shown the user's name, username (and, if a superadmin, the other customer(s) the user is associated with). Note that it is possible for an email to be associated with more than one username but this should only happen for legacy users that predate the ability to assign a user to more than one customer.
Select the user you wish to add to the customer and set the desired privilege and click [Add User]. The new user will be sent a specific welcome email for users that already exist on the system to let them know they have been added to a new customer account (see below for details).
"},{"location":"usage/users/#deleting-users","title":"Deleting Users","text":"Note that deleting a user results in one of two actions:
There are three command line tools for managing users available since v6:
user:create: create a user.user:find: find and print user(s) detailsuser:set-password: set the user's passwordHere's a sample run of user:set-password:
\u276f ./artisan user:set-password --search john\n+-----+------------+------------+----------------+--------------+-------+\n| ID | Name | Username | Email | Customers | Privs |\n+-----+------------+------------+----------------+--------------+-------+\n| 115 | John Smith | sjohnsmith | js@example.com | Acme Limited | CA |\n| ... | | | | | CA |\n+-----+------------+------------+----------------+--------------+-------+\n\n Enter ID to change password for:\n > 115\n\n Password or (return to have one generated):\n >\n\nGenerated password: 1eHRUoDNiGBlkJEz\nPassword set.\nThis section explains the handling around users with multiple customers.
When logging in, the last customer that the user acted for will be selected. If this customer does not exist / the relationship no longer exists / no previous customer set then a customer will be chosen at random.
If a user is associated with more than one customer, then the facility to switch users can be found under the My Account menu on the top right:
The current customer is highlighted.
"},{"location":"usage/users/#welcome-email","title":"Welcome Email","text":"IXP Manager sends a welcome email to all newly created users.
The default template for new users this can be found at resources/views/user/emails/welcome.blade.php. When an existing user is associated with an additional customer, the following template is used: resources/views/user/emails/welcome-existing.blade.php.
If you wish to change these templates, you can do so via the standard skinning mechanism.
"},{"location":"usage/users/#logging-in-as-another-user","title":"Logging in as Another User","text":"Administrative users (AUTH_SUPERUSER) can switch to other users to see what they see via the user list or the customer overview page.
The purpose of this is for both development and for support staff to replicate issues as reported by users.
"},{"location":"usage/users/#passwords-and-password-hashing","title":"Passwords and Password Hashing","text":"As of v4.5, all passwords are stored as bcrypt with a cost >=10.
As of v4.9, administrative users are unable to set a user's password. User's can set (and reset) their passwords via their Profile page or using the password reset functionality.
"},{"location":"usage/legacy/users/","title":"Users","text":"This page refers to a legacy version of IXP Manager (<v5.0)User management prior to v5.0 was handled differently - please see this page for current usage.
The IXP Manager Users feature allows you to add and manage users (people who can login to IXP Manager) on a per customer basis including:
See the entity definitions here.
There are three types of user:
AUTH_CUSTUSER - a standard customer user with portal access to a specific customer's dashboard (priv == 1).AUTH_CUSTADMIN - a customer administrative user. The only purpose of this account is to allow customers to create, edit and remove their own users. No other access is available through a CUSTADMIN login (priv == 2).AUTH_SUPERUSER - IXP staff only. FULL ACCESS TO ALL CUSTOMERS AND FUNCTIONS. This is only for your IXP staff! (priv == 3)There is a fourth internal permission but no user record exists for it:
AUTH_PUBLIC - a visitor who has not logged into IXP Manager (priv == 0).Additional Historical Perspective: the use of AUTH_CUSTADMIN was modeled on RIPE's equivalent model at the time. RIPE have since abandoned this model and it is our intention to do likewise.
"},{"location":"usage/legacy/users/#welcome-email","title":"Welcome Email","text":"IXP Manager sends a welcome email to all newly created users. The default template for this can be found at resources/views/user/emails/welcome.blade.php. If you wish to change this, you can do so via the standard skinning mechanism.
Administrative users (AUTH_SUPERUSER) can switch to other users to see what they see via the user list or the customer overview page.
The purpose of this is for both development and for support staff to replicate issues as reported by users.
"},{"location":"usage/legacy/users/#planned-work","title":"Planned Work","text":"As IXP Manager v5 evolves, we would like to make a number of changes:
Prior to IXP Manager v4.5, we supported both plaintext and bcrypt password hashing. There was a historical justification at INEX for support plaintext (this may still be documented here). However, IXP Manager is meant to represent the best practices for managing IXP's. As such, plaintext support was removed in v4.5.
As of v4.5, all passwords are stored as bcrypt with a cost >=10.
Prior to IXP Manager v4.9, we allowed administrative users to set a user's password. This has been removed as we believe it to be bad practice - only a user should know their own password. User's can set (and reset) their passwords via their Profile page or using the password reset functionality.
"},{"location":"usage/legacy/users/#historical-perspective","title":"Historical Perspective","text":"IXP Manager of pre-April 2013 had separate contacts and users which - at the time - we felt was quite confusing. LONAP sponsored a rework of this in 2013 to merge the concept of users and contacts with login privileges. Strangely, this actually caused more confusion and also was a developer nightmare with hacked in code to handle the database tables in multiple places. As such, in 2019 with release v4.9, this was undone and contacts and users are now separate entities again.
"}]} \ No newline at end of file