peach-network

GitHub logo Build Status Version badge

Networking microservice module for PeachCloud. Query and configure device interfaces using JSON-RPC over HTTP.

Interaction with wireless interfaces occurs primarily through the wpactrl crate which provides "a pure-Rust lowlevel library for controlling wpasupplicant remotely". This approach is akin to using wpa_cli (a WPA command line client).

Note: This module is a work-in-progress.

JSON-RPC API

Methods for retrieving data:

MethodParametersDescription
available_networksifaceList SSID, flags (security), frequency and signal level for all networks in range of given interface
idiface, ssidReturn ID of given SSID
ipifaceReturn IP of given network interface
pingRespond with success if microservice is running
rssiifaceReturn average signal strength (dBm) for given interface
rssi_percentifaceReturn average signal strength (%) for given interface
saved_networksList all networks saved in wpasupplicant config
ssidifaceReturn SSID of currently-connected network for given interface
stateifaceReturn state of given interface
statusifaceReturn status parameters for given interface
trafficifaceReturn network traffic for given interface

Methods for modifying state:

MethodParametersDescription
activate_apActivate WiFi access point (stop wpa_supplicant and start hostapd and dnsmasq)
activate_clientActivate WiFi client connection (stop hostapd and dnsmasq and start wpa_supplicant)
addssid, passAdd WiFi credentials to wpa_supplicant.conf
check_ifaceRun AP / client-mode configuration script
connectid, ifaceDisable other networks and attempt connection with AP represented by given id
deleteid, ifaceRemove WiFi credentials for given network id and interface
disableid, ifaceDisable connection with AP represented by given id
disconnectifaceDisconnect given interface
modifyid, iface, passwordSet a new password for given network id and interface
reassociateifaceReassociate with current AP for given interface
reconfigureForce wpa_supplicant to re-read its configuration file
reconnectifaceDisconnect and reconnect given interface
saveSave configuration changes to wpa_supplicant.conf

API Documentation

API documentation can be built and served with cargo doc --no-deps --open. This set of documentation is intended for developers who wish to work on the project or better understand the API of the src/network.rs module.

Directory Tree

.
├── Cargo.lock
├── Cargo.toml
├── README.md
├── src
│   ├── error.rs        // custom NetworkError type & From implementations
│   ├── lib.rs          // RPC server, methods & tests
│   ├── main.rs         // init logger, call run() & catch application errors
│   └── network.rs      // logic for network methods exposed via RPC

Setup

Clone this repo:

git clone https://github.com/peachcloud/peach-network.git

Move into the repo and compile:

cd peach-network
cargo build --release

Run the binary (sudo needed to satisfy permission requirements):

sudo ./target/release/peach-network

Environment

The JSON-RPC HTTP server address and port can be configured with the PEACH_NETWORK_SERVER environment variable:

export PEACH_NETWORK_SERVER=127.0.0.1:5000

When not set, the value defaults to 127.0.0.1:5110.

Logging is made available with env_logger:

export RUST_LOG=info

Other logging levels include debug, warn and error.

Example Usage

Retrieve IP address for wlan0

With microservice running, open a second terminal window and use curl to call server methods:

curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "get_ip", "params" : {"iface": "wlan0" }, "id":1 }' 127.0.0.1:5000

Server responds with:

{"jsonrpc":"2.0","result":"192.168.1.21","id":1}

Retrieve SSID of connected access point for wlan1

curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "get_ssid", "params" : {"iface": "wlan1" }, "id":1 }' 127.0.0.1:5000

Server response when interface is connected:

{"jsonrpc":"2.0","result":"Home","id":1}

Server response when interface is not connected:

{"jsonrpc":"2.0","error":{"code":-32003,"message":"Failed to retrieve SSID for wlan1. Interface may not be connected."},"id":1}

Retrieve list of SSIDs for all networks in range of wlan0

curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "scan_networks", "params" : {"iface": "wlan0" }, "id":1 }' 127.0.0.1:5000

Server response when interface is connected:

{"jsonrpc":"2.0","result":"[\"Home\",\"TP-LINK_254700\"]","id":1}

Server response when interface is not connected:

{"jsonrpc":"2.0","error":{"code":-32006,"message":"No networks found in range of wlan0"},"id":1}

Retrieve network traffic statistics for wlan1

curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "get_traffic", "params" : {"iface": "wlan1" }, "id":1 }' 127.0.0.1:5000

Server response if interface exists:

{"jsonrpc":"2.0","result":"{\"received\":26396361,\"transmitted\":22352530}","id":1}

Server response when interface is not found:

{"jsonrpc":"2.0","error":{"code":-32004,"message":"Failed to retrieve network traffic for wlan3. Interface may not be connected"},"id":1}

Licensing

AGPL-3.0