ixgen

Ixgen is yet another open-source, multi-platform generator for peering configurations on IXs incorporating the global peering DB API. It can also spin up its own "compatible" server for faster results. Ixgen is configured by an INI- or JSON-style format, producing custom template-driven or fixed JSON-style configurations that can be printed on the terminal, to a file, or served by HTTP. Direct access to routers REST-APIs and ssh/scp-upload is planned.

Ixgen is shipped with cross-compiled executables for Darwin, Linux, and Windows. Only Linux and Darwin currently support the prefix filter generator.

ixgen on docker

Running ixgen from Docker

Run ixgen from docker with your peering configuration as volume parameter:

docker run -v /path/to/peering.ini:/ixgen/configuration/peering.ini joerg/ixgen:latest

Building from source with Docker

Build ixgen from source using the Dockerfile.git:

# Build without API key (skips buildcache)
docker build -f docker/Dockerfile.git -t ixgen:git .

# Build with API key (runs buildcache during build)
docker build --build-arg PEERINGDB_APIKEY=your-api-key -f docker/Dockerfile.git -t ixgen:git .

# Run buildcache at runtime (alternative, avoids storing API key in image)
docker run -e PEERINGDB_APIKEY=your-api-key ixgen:git /ixgen/ixgen -buildcache

Using the built image

# Run with your configuration
docker run -v /path/to/peering.ini:/ixgen/configuration/peering.ini ixgen:git

# Run with custom cache directory
docker run -v /path/to/peering.ini:/ixgen/configuration/peering.ini \
           -v /path/to/cache:/ixgen/cache \
           -e PEERINGDB_APIKEY=your-api-key \
           ixgen:git

how it works

Ixgen works by querying the peering DB-API or its local API service for peering members and specific network configurations and populating learned things with a custom router template.

ini-style configuration

Ixgen is configured by configuration/peering.ini, which contains a list of Internet Exchanges and peering as numbers that the user wants to configure on his router.

peeringdb client and server

Ixgen has a peering DB client module and can start a limited fast peering DB-lookalike server, which can also be queried from the network. By default, it creates an embedded HTTP API server for its usage.

apiserver

Also, you can start up a standalone version called apiserver. Apiserver can answer limited peering DB-API-queries but also generate router configuration via HTTP-POST.

flavor / templating

Ixgen can use different templates for generating router configurations; by default, Extreme and Juniper style command line syntax is shipped. The flavor is given on the command line or in the HTTP query with the -style argument; else, it's always Brocade MLXE (Netiron) by default. You can create your templates in the templates-directory. Please see the section Default output and templates for more information.

Quickstart

Populating the cache

Before the first usage, you may want to download the peering DB start files; else, we won't benefit from the fast local cache. To populate the store, you need to start up ixgen with the -buildcache parameter, please also specify your API-Key since 2022/08.

ixgen -buildcache -apikey "$YOUR_PEERING_DB_API_KEY"

peering.ini

The peering.ini is a straightforward configuration file, that uses sectors and lists.

For every Internet Exchange that needs to be configured, a section head combined with the original record name of the Exchange and a possible network name, that can be both found on the peering DB database or website has to be specified.

Several subsections with general options for the Exchange configuration or the peering list can be added.

Example configuration

If you need to connect to the DE-CIX in Frankfurt, you will add the "DE-CIX Frankfurt" name and the network name [Main or Jumbo] separated with a || as a section head in squared brackets.

[DE-CIX Frankfurt||Main]

Now you can add a subsection for available options or the peering list.

[DE-CIX Frankfurt||Main]
[peers]
[options]

Add peer to list

If you want to peer with the AS196922-routers (hint: that is me!) on DE-CIX, you need to add the right numbers on a new line after the [peers]-section.

[DE-CIX Frankfurt||Main]
[peers]
196922
[options]

Run ixgen

Starting ixgen with default options will now print out the peering BGP configuration for DE-CIX with the wished neighbor statements for all ipv4 and ipv6 routers.

./ixgen.mac

The call will print out my DECIX-configuration for Frankfurt:

router bgp
neighbor 80.81.194.25 remote-as 196922
neighbor 80.81.194.25 peer-group decix-peer
address-family ipv4 unicast
neighbor 80.81.194.25 maximum-prefix 64
no neighbor 80.81.194.25 shutdown
exit-address-family
address-family ipv6 unicast
neighbor 2001:7f8::3:13a:0:1 remote-as  196922
neighbor 2001:7f8::3:13a:0:1 peer-group decix-peer6
neighbor 2001:7f8::3:13a:0:1 maximum-prefix 10
no neighbor 2001:7f8::3:13a:0:1 shutdown
exit-address-family

Or a call to output the native format in JSON:

 ./ixgen -style native/json_pretty
 {
   "additionalconfig": null,
   "ixname": "DE-CIX Frankfurt||Main",
   "options": {},
   "peeringgroups": {},
   "peers_configured": {
      "DE-CIX Frankfurt||Main": {
         "196922": [
            {
               "active": true,
               "asn": "196922",
               "group": "",
               "group6": "",
               "groupenabled": true,
               "group6_enabled": true,
               "infoprefixes4": 0,
               "infoprefixes6": 0,
               "ipv4addr": "",
               "ipv6addr": "",
               "ipv4enabled": true,
               "ipv6enabled": true,
               "irrasset": "",
               "isrs": false,
               "isrsper": false,
               "localpreference": 0,
               "prefixfilter": false
            }
         ]
      }
   },
   "peersready": [
      {
         "active": true,
         "asn": "196922",
         "group": "",
         "group6": "",
         "groupenabled": false,
         "group6_enabled": false,
         "infoprefixes4": 64,
         "infoprefixes6": 10,
         "ipv4addr": "80.81.194.25",
         "ipv6addr": "2001:7f8::3:13a:0:1",
         "ipv4enabled": true,
         "ipv6enabled": true,
         "irrasset": "AS-HOFMEIR",
         "isrs": false,
         "isrsper": false,
         "localpreference": 0,
         "prefixfilter": false
      }
   ],
   "routeserverready": null
 }

Default output and templates

By default, IXgen will output on the standard output channel. The output can be also redirected to a file with the _ -output_ parameter. Be aware that peers' ASN always sorts the result.

Default syntax and more info for Extreme Netiron

The default output syntax is Netiron command line syntax because this is my home box :D. If you are on Netiron platforms (MLX, CER, MLXE), you can also use my tool mlxsh ( https://github.com/ipcjk/mlxsh) to automatically upload the configuration into your router, such as with an extra cronjob.

REST-APIs

Newer routers like the Brocade SLX or JunOS 16.X support a configuration with REST, and I will keep it as soon as I get my hands on it.

Incorporate your templates

To use your router, you need to create or use one of the provided templates in the templates-folder and set the _ -style_ parameter to your flavor, e.g., -juniper/set for Junos set exchange format.

Particular output like Juniper JSON is integrated into code.

templates for router snippets

The templates directory is straightforward structured and has a separate layer for vendors and devices:

native
- json
- json_pretty
extreme
- netiron
juniper
- set
- json (fixed in code, no template)
cisco
- (currently almost an one-to-one-copy from the Extreme-template)
The last layer always has a router.tt-, an optional header.tt- and footer.tt-file.

router.tt is the main file, the peergenerator-module supplies that. The header.tt-file is a custom file that will be injected before the peering-code, the footer.tt file after. If you need to initialize peering groups or set any other significant value, then header.tt is the right place to be.

Exported structures to the template engine

Exported to the template is the type "IX", which is a struct of the member variables:

AdditionalConfig (array of strings)
IxName (name of the IX)
Options (hash map of IX-options from the ini-file)
PeeringGroups (used peering groups for that IX, generated from the INI)
PeersINI (Peers as read from the INI-file [dont use this!])
PeersReady (Peers that have processed and are ready for the templating)
RouteServerReady (Routeserver records that have been processed and are ready)

INI-Configuration

exchange configuration parameters

When adding an exchange, there are several options and parameters you can add each on a separate line in the [options]-subsection. Please avoid special characters or whitespaces/tabs inside strings.

ixid

some Ixes change their names too frequently; with the ixid= option, you can pin it to the peering-DB id

ipv4

routeserver_group=$rs_group (group used for peering with $rs_group )
peer_group=$peer_group (group used for peering with neighbors for the [peers]-list)

Ixgen

Install / Use

README