Skip to content

Latest commit

 

History

History
582 lines (433 loc) · 13.4 KB

NetworkControlPlugin.md

File metadata and controls

582 lines (433 loc) · 13.4 KB
Raw

Network Control Plugin

Version: 1.0

Status: ⚫⚫⚫

A NetworkControl plugin for Thunder framework.

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the NetworkControl plugin. It includes detailed specification about its configuration, methods and properties provided, as well as notifications sent.

Case Sensitivity

All identifiers of the interfaces described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym Description
API Application Programming Interface
HTTP Hypertext Transfer Protocol
JSON JavaScript Object Notation; a data interchange format
JSON-RPC A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term Description
callsign The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID Description
HTTP HTTP specification
JSON-RPC JSON-RPC 2.0 specification
JSON JSON specification
Thunder Thunder API Reference

Description

The Network Control plugin provides functionality for network interface management.

The plugin is designed to be loaded and executed within the Thunder framework. For more information about the framework refer to [Thunder].

Configuration

The table below lists configuration options of the plugin.

Name Type Description
callsign string Plugin instance name (default: NetworkControl)
classname string Class name: NetworkControl
locator string Library name: libWPEFrameworkNetworkControl.so
autostart boolean Determines if the plugin shall be started automatically along with the framework
configuration object (optional)
configuration?.dnsfile string (optional) Path to DNS resolve file (default: /etc/resolv.conf)
configuration?.response number (optional) Maximum response time out of the DHCP server
configuration?.retries number (optional) Maximum number of retries to the DHCP server

Interfaces

This plugin implements the following interfaces:

Methods

The following methods are provided by the NetworkControl plugin:

NetworkControl interface methods:

Method Description
reload Reloads a static or non-static network interface adapter
request Reloads a non-static network interface adapter
assign Reloads a static network interface adapter
flush Flushes a network interface adapter

reload method

Reloads a static or non-static network interface adapter.

Parameters

Name Type Description
params object
params.interface string Network interface name

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Unavailable network interface

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "NetworkControl.1.reload",
    "params": {
        "interface": "eth0"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": null
}

request method

Reloads a non-static network interface adapter.

Also see: connectionchange

Parameters

Name Type Description
params object
params.interface string Network interface name

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Unavaliable network interface

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "NetworkControl.1.request",
    "params": {
        "interface": "eth0"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": null
}

assign method

Reloads a static network interface adapter.

Parameters

Name Type Description
params object
params.interface string Network interface name

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Unavaliable network interface

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "NetworkControl.1.assign",
    "params": {
        "interface": "eth0"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": null
}

flush method

Flushes a network interface adapter.

Parameters

Name Type Description
params object
params.interface string Network interface name

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Unavaliable network interface

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "NetworkControl.1.flush",
    "params": {
        "interface": "eth0"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": null
}

Properties

The following properties are provided by the NetworkControl plugin:

NetworkControl interface properties:

Property Description
network Network information
dns DNS addresses
up Interface up status

network property

Provides access to the network information.

Value

Name Type Description
(property) array Network information
(property)[#] object
(property)[#]?.interface string (optional) Network interface name
(property)[#]?.mode string (optional) Mode (must be one of the following: Manual, Static, Dynamic)
(property)[#]?.address string (optional) IP address
(property)[#]?.mask number (optional) Network interface mask
(property)[#]?.gateway string (optional) Gateway address
(property)[#]?.broadcast string (optional) Broadcast IP
(property)[#]?.dns array (optional) DNS addresses
(property)[#]?.dns[#] string (optional) DNS addresses

The interface argument shall be passed as the index to the property, e.g. NetworkControl.1.network@eth0. If network interface is not given, all network interfaces are returned.

Errors

Code Message Description
2 ERROR_UNAVAILABLE Unavailable network interface

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "NetworkControl.1.network@eth0"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": [
        {
            "interface": "eth0",
            "mode": "dynamic",
            "address": "192.168.1.158",
            "mask": 24,
            "gateway": "192.168.1.1",
            "broadcast": "192.168.1.255",
            "dns": [
                "['192.168.1.1', 'www.google.com', '8.8.8.8']"
            ]
        }
    ]
}

Set Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "NetworkControl.1.network@eth0",
    "params": [
        {
            "interface": "eth0",
            "mode": "dynamic",
            "address": "192.168.1.158",
            "mask": 24,
            "gateway": "192.168.1.1",
            "broadcast": "192.168.1.255",
            "dns": [
                "['192.168.1.1', 'www.google.com', '8.8.8.8']"
            ]
        }
    ]
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

dns property

Provides access to the DNS addresses.

Value

Name Type Description
(property) array DNS addresses
(property)[#] string DNS addresses

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "NetworkControl.1.dns"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": [
        "['192.168.1.1', 'www.google.com', '8.8.8.8']"
    ]
}

Set Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "NetworkControl.1.dns",
    "params": [
        "['192.168.1.1', 'www.google.com', '8.8.8.8']"
    ]
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

up property

Provides access to the interface up status.

Value

Name Type Description
(property) boolean Interface up status

The interface argument shall be passed as the index to the property, e.g. NetworkControl.1.up@eth0.

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Unavailable network interface

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "NetworkControl.1.up@eth0"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": false
}

Set Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "NetworkControl.1.up@eth0",
    "params": false
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

Notifications

Notifications are autonomous events, triggered by the internals of the implementation, and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] for information on how to register for a notification.

The following events are provided by the NetworkControl plugin:

NetworkControl interface events:

Event Description
connectionchange Notifies about connection status (created, updated, removed, connected, ipassigned and connectionfailed)

connectionchange event

Notifies about connection status (created, updated, removed, connected, ipassigned and connectionfailed).

Parameters

Name Type Description
params object
params.name string Network interface name
params.address string IP Address of network interface, if it is connected
params.status string Status of the interface, update, connected or not (must be one of the following: created, updated, removed, connected, ipassigned, connectionfailed)

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.1.connectionchange",
    "params": {
        "name": "eth0",
        "address": "192.168.1.10",
        "status": "connected"
    }
}