Tagged by CORD Jenkins version-tag job: 35, for Gerrit patchset: 32986
Release app version 1.2.1 with API version 1.2.1

Change-Id: Ie060efb46d45764caa18d476cdcb0b8cd7f7ee45
3 files changed
tree: b961d334d0fa1a6ae68c4a52be7051c165406d92
  1. .gitignore
  2. .gitreview
  3. README.md
  4. api/
  5. app/
  6. pom.xml
  7. spotbugs-security-exclude.xml
  8. spotbugs-security-include.xml

PppoeAgent : PPPoE Intermediate Agent application

What is a PPPoE Intermediate Agent?

As described in TR-101 Issue 2 - 3.9.2, the PPPoE Intermediate Agent supports the PPPoE access method and is a function placed on the Access Node in order to insert access loop identification.


The PPPoE Agent intercepts all upstream PPPoED packets, i.e. the PADI, PADR and upstream PADT packets, but does not modify the source or destination MAC address of these PPPoE discovery packets. Upon receipt of a PADI or PADR packet sent by the PPPoE client, the Intermediate Agent adds a Vendor Specific PPPoE Tag to the packet to be sent upstream. The TAG contains the identification of the access loop (circuit-id) on which the PADI or PADR packet was received and the value of "remoteId" field if defined on subscriber's Sadis.

The circuit-id is generated following the format: "[OLT-SN] [SLOT]/[PON-PORT]:[ONU-SN]", i.e:

EC1724000150 0/2:ALPHe3132051

If a PADI or PADR packet exceeds the Ethernet MTU after adding the access loop identification TAG, the Intermediate Agent must drop the packet, and issue the corresponding PADO or PADS response with a Generic-Error TAG to the sender.

PPPoE agent keeps track of the client's connect point saving it along other information (i.e: MAC address, session-id, last received packet type and etc) in a storage available through the CLI "pppoe-users". With that at hand, the agent also intercepts the downstream PPPoED packets, such as PADO, PADS and PADT from server. These responses are processed and delivered to the connect point associated with the destination MAC address. If the destination MAC address is not known for PPPoE Agent, the packet is dropped.

Component Configuration

 "org.opencord.pppoeagent.impl.PppoeAgent": {
      "pppoeMaxMtu": 1500,
      "enableCircuitIdValidation": true,
      "packetProcessorThreads": 10

Component Configuration Parameters


The allowed MTU size (in bytes) for upstream packet forwarding.


Flag to control the circuit-id validation mechanism: when configured as 'true' it checks if the Sadis "circuitId" field matches with the circuit-id generated by PPPoE Agent, if not the packet is dropped. When Sadis "circuitId" is not set for the PPPoE client, the validation is not performed whatsoever.


Reference to create a thread pool with a fixed number of threads for packet processing.

PPPoE Configuration in org.opencord.olt app:

In order to PPPoE Agent receive the packets, Onos has to trap the PPPoED frames. A way to obtain that is configuring Olt app to install PPPoED trap rules as it follows:

"org.opencord.olt.impl.OltFlowService": {
      "enablePppoe": true

How to install the PPPoE Intermediate Agent on Onos

Since this app is not available on "voltha-onos" image, first it's necessary to generate the .oar file. To do it so, you can follow the steps below:

-> Clone this repository

git clone "https://gerrit.opencord.org/pppoeagent" && cd pppoeagent

-> Build it using Maven

mvn clean install

After these steps, the .oar file should be available at "pppoeagent/app/target/pppoeagent-app-1.0.0.oar".

Now you can upload and install the .oar in the Onos running instance using the onos-app shell utility

Usage example: "onos-app [ONOS_ADDRESS] install! [OAR_FILE_PATH]"