README.adoc

EdgeOS API Guide

The EdgeOS API is not officially publicly documented. However as the requests and responses can be monitored in a web-browser along with the client-side JavaScript and Python back-end source code being available, a lot of information on how it works can be derived.

Table of Contents

• Authentication
  • Login
  • Logout
• REST API
  • Edge - General
  • Edge - Configuration
  • Edge - Optical Network Unit (ONU)
  • Edge - Operations
  • Optical Line Terminal (OLT) - General
  • Optical Line Terminal (OLT) - Optical Network Unit (ONU)
  • Wizards
• WebSocket API
• Third Party Unofficial API Wrappers

Authentication

Login

A HTTP POST to https://host-or-ip/ with the username and password encoded as a simple application/x-www-form-urlencoded form as the request content will grant you a PHPSESSID cookie that is used to confirm you are authenticated:

username=USERNAME&password=PASSWORD

This will return a HTTP status code 303 See Other with a selection of cookies on success. On failure, a 200 OK is returned with the same login form again, only this time containing the text The username or password you entered is incorrect.

Be careful as some web clients will automatically follow the 303 redirection and therefore the cookies may not be where you expect them to be.

Session ID

The session ID is returned multiple times in the header but the primary header for proving successful authentication is:

Set-Cookie: PHPSESSID=9a00126c5bf04e29835f7c13fe5ab155; secure

Warning

A session is valid for 1440 seconds (24 minutes) and is refreshed on every web request. A session can be periodically artificially extended with a Session Heartbeat request.

Although this appears to be a PHP generated session ID, the backend was switched from PHP to a Python process in EdgeRouter firmware v1.9.7. Sessions are now generated by Beaker (/usr/lib/python2.7/dist-packages/beaker.session.py) using Python’s uuid.uuid4().hex function to create a 32 character (128-bit) hexadecimal string uuid (this is invoked by the web GUI’s views.py function login()).

Session Store

For the session store, the full session details and variables are converted from a Python serialised object to one generated by phpserialize (due to ses-mon.cpp 's reliance on the older PHP style backend for session storage apparently) and are stored in the path /var/run/beaker/container_file.

Sensitive Requests (CSRF Protection)

To be able to call sensitive methods (anything that is not a GET, HEAD, OPTIONS or TRACE request and where the protection is not otherwise explicitly disabled or it is otherwise permitted to turn off protection for requests with the X-Requested-With client header set) a X-CSRF-TOKEN need also be supplied in the request (EdgeOS currently allows this in the querystring and does not mandate this is set as a cookie). This is a 64 character (256-bit) hexadecimal string generated using Python’s os.urandom().

Set-Cookie: X-CSRF-TOKEN=521b05cab373afb31d4c84f521cc1a8afc2dac12288d90e14120fce280d5fcdd

Logout

A HTTP GET to /logout will end the current session.

REST API

The REST API is served from /var/www/python/edgeos_gui/api on the EdgeOS device.

Edge - General

• Authenticate

• Configuration Settings Batch

• Configuration Settings Delete

• Configuration Settings Get Predefined List

• Configuration Settings Get Sections

• Configuration Settings Get Tree

• Configuration Settings Set

• Get Data

• Session Heartbeat

• Upgrade Firmware

• Wizard Feature

• Wizard Setup

Edge - Configuration

• Download Configuration

• Restore Configuration

Edge - Optical Network Unit (ONU)

• Reboot

• Upgrade

Edge - Operations

These are defined as "<op>.json" and are passed to the closed-source ubnt-util:

• Check For Firmware Updates

• Clear Traffic Analysis

• Factory Reset

• Generate Support File

• Reboot

• Release DHCP Lease

• Renew DHCP Lease

• Reset Default Configuration

• Shutdown

Optical Line Terminal (OLT) - General

• Get Connected Optical Network Unit (ONU) Devices

Optical Line Terminal (OLT) - Optical Network Unit (ONU)

• Generate Support File

• Get Connected WiFi Clients

• Locate

• Reset

Wizards

• List All Wizards

• Runtime (referenced in the web UI but is no longer present)

• Setup (referenced in the web UI but is no longer present)

• Specific Wizard Create

• Specific Wizard Download

• Specific Wizard Remove

• Specific Wizard Upload

WebSocket API

• Command Line Interface (CLI)

• Statistics

Third Party Unofficial API Wrappers

There are a few developers who have worked on creating unofficial API wrappers:

• https://github.com/matthew1471/EdgeOS-API (written in C#)

• https://github.com/brontide/aioedgeos (written in Python)

• https://github.com/andrewstuart/edgeos-rest (written in Go)