Skip to content

IXP Manager v5.0.0
Compare
Choose a tag to compare
@barryo barryo released this 21 May 19:05
· 1350 commits to master since this release
v5.0.0
2c87997

Welcome, finally, to the release of IXP Manager v5. Thanks for your patience to date - this is a BIG release! You are going to need about four hours to work through everything properly - so probably get a few ☕️'s before you hit the 🍻.

Dedication

IXP Manager 5.0 is dedicated to the memory of Barry Rhodes, who died in September 2018 and was Chief Executive of INEX for 15 years.

In 2005, IXP Manager was first envisioned and created by the INEX operations team, Nick Hilliard and Barry O'Donovan, to provide a robust and scalable management platform to run INEX's internet exchange in Dublin. Barry Rhodes put his full support behind the project, which enabled the code to be developed to the point that it could be open-sourced and released to the community. Today, more than 70 IXPs use IXP Manager as their management platform.

The INEX team are proud to honour Barry Rhodes' legacy by dedicating this significant release to his memory.

Release Summary

$ git --no-pager diff --shortstat release-v4 release-v5
 970 files changed, 79020 insertions(+), 87488 deletions(-)

A brief summery of the biggest changes in IXP Manager v5 include:

  • Bird v2 support for route servers, route collectors and AS112 services (AS112 not used in production at INEX yet).
  • RPKI support for Bird2! We have also updating the route server filtering mechanism - to fully understand RPKI and the updated filtering mechanism with IXP Manager is to watch our presentation from APRICOT 2019 or read this article on INEX's website.
  • The looking glass has been overhauled from a look and feel perspective. Also, when using Bird v2 it will now also show filtered routes and the reason for filtering.
  • The Route Server Prefix Analysis tool has been deprecated (but not removed). It has been replaced with a new tool that queries all Bird v2 route servers live to give a complete and accurate report on filtered prefixes.
  • Mandatory PHP >= 7.3 requirement (some reasoning discussed here and note that only >= 7.2 are in active support. This is quite easy on Ubuntu via this PPA and we've written a short how-to here.
  • Laravel framework upgraded from 5.5 to 5.8.
  • Bower as a frontend package management system has been replaced with Yarn and Laravel Mix. What this means is that the frontend assets ship with IXP Manager and no action required from you anymore!
  • Bootstrap frontend upgraded to v4.3 (from 3.x) and TailwindCSS added. There are still some rough edges but these will get sanded and smoothed over the coming weeks and months.

Upgrade Instructions

If you are upgrading to IXP Manager v5, this is where to start. We assume that you are upgrading from v4.9.x. No other upgrade paths are supported or recommended.

Prerequisite: ensure you have PHP >= v7.3 installed. If you are using Ubuntu, we recommend this PPA and we've written a short how-to here. We would also recommend that you upgrade to Ubuntu 18.04 LTS as part of this process if you are using an older version of Ubuntu (however it will work fine on 16.04 with PHP 7.3).

The process we describe here is based on the new instructions for upgrading within IXP Manager v5 and you should read that document now but follow the instructions as set out here for upgrading from v4.9.x.

We have created a Gist which shows a sample v4.9.3 to v5.0.0 upgrade to help illustrate the instructions below and the output / results you should see.

We will assume your installation of IXP Manager is installed at a location identified by the shell variable IXPROOT. This is set in step (1) below.

  1. Set up some variables and ensure directory permissions are okay:

    # set this to your IXP Manager installation directory
IXPROOT=/srv/ixpmanager

# fix as appropriate to your operating system. ubuntu/debian is fine with this:
MY_WWW_USER=www-data

# ensure the web server daemon user can write to necessary directories:
chown -R $MY_WWW_USER: ${IXPROOT}/storage $IXPROOT/vendor
chmod -R u+rwX ${IXPROOT}/storage $IXPROOT/vendor

  2. Enable maintenance mode to let your users know what's happening:

    cd $IXPROOT
php artisan down --message='Upgrading to IXP Manager v5. This will take sometime.' --retry=900

  3. Using Git, checkout the v5.0.0 release of IXP Manager:

    # (assuming we're still in $IXPROOT)
# pull the latest code
git fetch --all
# check out the version you are upgrading to
git checkout v5.0.0

  4. Install latest required libraries from composer (read the notes on the new instructions for upgrading within IXP Manager v5. NB: ensure you are running Composer >=1.8.0 - see the composer website for install/upgrade instructions.

    # this assumes composer.phar is in the IXP Manager install directory. YMMV - see notes on the upgrade instructions.
# Upgrade composer first:
php ./composer.phar selfupdate

# And update the libraries
sudo -u $MY_WWW_USER bash -c "HOME=${IXPROOT}/storage && cd ${IXPROOT} && php ./composer.phar install --no-dev --prefer-dist"

  5. Restart Memcached and clear the cache. Do not forget / skip this step!

    # (assuming we're still in $IXPROOT)
systemctl restart memcached.service
php artisan cache:clear

  6. Update the database schema:

    # (assuming we're still in $IXPROOT)
# (you really should take a mysqldump of your database first)
# see what will change:
php artisan doctrine:schema:update --sql
# migrate:
php artisan doctrine:schema:update --force
php artisan migrate --force

  7. Restart Memcached (yes, again). Do not forget / skip this step!

    systemctl restart memcached.service

  8. Ensure file permissions are still correct.

    chown -R $MY_WWW_USER: ${IXPROOT}/storage $IXPROOT/vendor $IXPROOT/bootstrap/cache
chmod -R u+rwX ${IXPROOT}/storage $IXPROOT/vendor $IXPROOT/bootstrap/cache

  9. Clear out all caches:

    php artisan cache:clear
php artisan config:clear
php artisan doctrine:clear:metadata:cache
php artisan doctrine:clear:query:cache
php artisan doctrine:clear:result:cache
php artisan route:clear
php artisan view:clear

  10. Now work through the rest of the release notes before proceeding and disabling maintenance mode.

  11. Disable maintenance mode:

    # (assuming we're still in $IXPROOT)
./artisan up

  12. Recreate 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:

    mysql -u $DB_USER -p $DB_DATABASE < $IXPROOT/tools/sql/views.sql

  13. Housekeeping:

  • you should have taken care of this in previous upgrades but if not, the var/ directory can be deleted.
  • we have moved away from Bower as a frontend package manager so you can delete this directory: public/bower_components/.

Route Server / Configuration Changes

IXP Manager v5 adds support for Bird v2 but maintains support for Bird v1. The only changes to the Bird v1 configuration is:

  • setting the use of standardised time formats (iso long);
  • IRRDB prefixes and ASNs are now sorted.

You will need to upgrade Bird's Eye to v1.2.1 for full support for this on your routers.

Upgrading to Bird v2 and RPKI support is a separate task and this is covered in our online documentation here.

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 had been using the Route Server Prefix Analysis tool with Bird v1 and you want to keep using it for now, enable it by setting the following in your .env file:

IXP_FE_FRONTEND_DISABLED_RS_PREFIXES=false

Looking Glass

Upgrade to Bird's Eye v1.2.1 due to the following additions to Bird's configuration file:

# standardise time formats:
timeformat base         iso long;
timeformat log          iso long;
timeformat protocol     iso long;
timeformat route        iso long;

Users

V5 changes user management in a number of ways - essentially implementing most of the ideas from the RFC in issue #354. We have rewritten the documentation for this and you should read that now. The changes include:

  1. Allow an user to be linked to more than one customer / network.
  2. Unshackle contacts from users - this was done in v4.9.0.
  3. Change the authorisation system from the current roles of CUSTADMINs and and CUSTUSERs. The current forms of CUSTADMINs date from equivalent functionality in the old RIPE LIR portal where identical roles existing. Instead, we would like CUSTADMIN to mean read/write/admin access and CUSTUSER to mean read-only access. All existing CUSTADMINs would be deleted (these users can only manage accounts and have no other purpose, they are usually role email addresses such as peering@/noc@). All existing CUSTUSERs would be elevated to CUSTADMINs.

To make these changes, carry out the following commands:

# expunge login logs >6 months 
php artisan utils:expunge-logs -v

# refactor user/customer entries for n:1 to n:m (customer:user)
# (you'll get warnings but as long as you are doing this as part of the V5.0.0 upgrade, it is safe)
php artisan update:customer2users

# delete CUSTADMIN users (optional but recommended)
php artisan update:remove-custadmins

# promote `CUSTUSER`s to `CUSTADMIN`s (optional but highly recommended)
php artisan update:promote-custusers

You will probably want to communicate these changes to your members. A draft of the email INEX sent to its members can be seen in this Gist.

New User Templates: As usual, new users will receive a welcome email. There is now a second version of this for existing users added to another customer ([documented here]https://docs.ixpmanager.org/usage/users/#welcome-email). You may want to review the content of this and consider skinning it.

Task Scheduler

Prior to IXP Manager v5, many cron jobs had to be configured manually. From v5.0 onwards, most required cron jobs are handled by Laravel's task scheduler. As such, you typically just need a single cron job entry such as:

* * * * *    www-data    cd /srv/ixpmanager && php artisan schedule:run >> /dev/null 2>&1

Please review the official documentation for this here as it lists what entries are covered by this.

At time of writing, the only ones which are not covered are:

  • the Grapher email updates (any Artisan command starting grapher:email- - documentation).
  • the port speeds auditor (audit:port-speeds - documentation).
  • the RIR object updater (rir:generate-object - documentation).

Third Party Integrations

We have added MANRS API integration and now highlight members that are part of the MANRS program (documentation).

We have also fixed the ASN lookup by using PeeringDB's whois integration and we have written new PeeringDB documentation to show all the integrations we use (documentation).

Templates

Due to the upgrade to Bootstrap 4, you may need to look at the CSS in some of your templated files. Common files that you may have templated include:

  • resources/skins/x/footer-content.foil.php -> moved to the layouts directory: resources/skins/x/layouts/footer-content.foil.php and note that the footer has been complete changed.
  • resources/skins/x/header-documentation.foil.php -> moved to the layouts directory: resources/skins/x/layouts/header-documentation.foil.php and the CSS has changed significantly (see the example under resources/views/layouts/header-documentation.foil.php).
  • CSS for the support page needs updating: resources/skins/x/content/0/support.foil.php (see INEX's for reference under resources/skins/inex/content/0/support.foil.php.

Development Updates

  • Laravel Telescope has been added.
  • Front end asset management now uses Yarn / Laravel mix. Updates for development are built via yarn run dev and for production releases via yarn run prod.
Assets 2
Loading