Control Plane announcements via REST API

Control Plane announcements via REST API

We offer a secondary way to make BGP announcements, via a web browser or an API request. This way of performing announcements is faster and straightforward without the need to maintain an active VPN connection. To make the announcements you need to create a json file (experiment file), with the description of the announcements and the order in which they will be executed, and send it via API or form in a web page. Despite the simplicity, the web-based announcements have some limitations.

Pros

• No need to request an experiment proposal or wait for its approval to perform lightweight experiments.
• Easy integration of scripts to generate announcements via Rest API.
• No need to create or maintain an active VPN connection with muxes.
• Announcements can be pre-calculated and made in batch.

Cons

• Announcements are not executed as soon as they are requested, there is a demand queue that obeys the order of arrival.
• Each sequence of announcements is executed in a 90 minutes interval.
• Once a sequence of advertisements is started, it cannot be canceled until the experiment is finished.
• There is no support for data plane.

Experiment File

For the creation of an experiment file you need to know that the announcements are made per round. In each round one or more prefix announcement will be made, and they will be active in a 90-minute interval. After 90 minutes the next round will be executed, and so on, until the experiment is complete.

Example:

...
{
    "A": {
	"announce": [
	    {
	        "muxes": [
		    "amsterdam01"
		],
		"origin": 47065
	    }
	]
    },
    "B": {
        "announce": [
	    {
	        "muxes": [
		    "amsterdam01"
		],
		"origin": 47065
	    }
	]
    }
},
{
    "A": {
        "announce": [
	    {
	        "muxes": [
		    "ufmg01"
		],
		"origin": 47065
	    }
	]
    },
    "B": {
        "withdraw": [
	    "amsterdam01"	
	]
    }
},
            
...

In this example we describe two rounds, the first round has two announcements with two different prefixes (A, B) that will be announced simultaneously by amsterdam01 mux. After this round, the next round will be executed, which contains prefixes (A, B) announced by ufmg01 mux. For the creation of an experiment file, additional information is needed such as contact email and description as you can see here.

Prefix announcement

We can describe prefixes in two different ways.

1. Using letters: Prefixes can be described as letters, this means that the user has no preference which prefixes will be chosen for the advertisements. This way the prefixes will be chosen according to availability, the chosen prefixes will be informed to the user at the beginning of the experiment. The list of letters available for use can be seen here. Note that matching letters will be mapped to matching prefixes.
2. CIDR Notation: It is also possible to specify a prefix statically, as long as it is in the list of prefixes that are available for use in the platform. The prefix list can be seen here

Constraints

• Each experiment can only use one type of prefix announcement (Letters or CIDR Notation). This means that an experiment that have prefixes described as letters along with CIDR notation (e.g. A and 138.185.228.0/24) will not be accepted by the platform.

• All rounds must have the same set of prefixes. If you use a set of prefixes in the first round (e.g. A, B, C or 138.185.228.0/24, 138.185.229.0/24) these same prefixes must be present in the next rounds, otherwise the experiment will not be accepted by the platform.

• The first round must contain at least one announcement operation. Only withdrawal operations will not be accepted.

Scheduling

The choice of experiments to be run is on a FIFO basis. When an experiment is started it will run completely until its conclusion, without any interruption in its execution. At the moment we cannot guarantee or specify at what time the experiment will be started.

Details

After the experiment request, the information presented to the user is:

1. State: Experiment status. Whether the rounds of the experiment have been started, are in progress, or completed. An experiment can have four states:
   • queued: The experiment is in the queue and has not yet been started.
   • changing configuration: The experiment is preparing for the execution of the next round.
   • round ongoing: There is a round in progress.
   • completed: The experiment was finished.
2. Time issued: Experiment start time.
3. Prefix mapping: In case prefixes are used as letters, this field shows the mapping to real prefixes.
4. Number of rounds: Number of rounds in an experiment.
5. Number of prefixes: Number of prefixes in an experiment.
6. Round start times: list of the starting times of each round.

Web access and API access

Both forms of access need authorization and require the user to have permission to use the Rest API. The difference between the two, is that the web platform requires the user to be logged into the system to make requests. The API requires the use of a token that is available on the dashboard of the PEERING website.