peach-workspace/peach-network
2021-11-05 13:34:34 +02:00
..
.cargo First workspace commit 2021-08-06 13:58:40 -04:00
conf First workspace commit 2021-08-06 13:58:40 -04:00
debian First workspace commit 2021-08-06 13:58:40 -04:00
src move jsonrpc test to dev deps for network 2021-11-05 13:34:34 +02:00
.gitignore First workspace commit 2021-08-06 13:58:40 -04:00
.travis.yml First workspace commit 2021-08-06 13:58:40 -04:00
Cargo.toml move jsonrpc test to dev deps for network 2021-11-05 13:34:34 +02:00
notes.txt First workspace commit 2021-08-06 13:58:40 -04:00
README.md First workspace commit 2021-08-06 13:58:40 -04:00

peach-network

Build Status Generic 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:

Method Parameters Description
available_networks iface List SSID, flags (security), frequency and signal level for all networks in range of given interface
id iface, ssid Return ID of given SSID
ip iface Return IP of given network interface
ping Respond with success if microservice is running
rssi iface Return average signal strength (dBm) for given interface
rssi_percent iface Return average signal strength (%) for given interface
saved_networks List all networks saved in wpasupplicant config
ssid iface Return SSID of currently-connected network for given interface
state iface Return state of given interface
status iface Return status parameters for given interface
traffic iface Return network traffic for given interface

Methods for modifying state:

Method Parameters Description
activate_ap Activate WiFi access point (start wpa_supplicant@ap0.service)
activate_client Activate WiFi client connection (start wpa_supplicant@wlan0.service)
add ssid, pass Add WiFi credentials to wpa_supplicant-wlan0.conf
check_iface Activate WiFi access point if client mode is active without a connection
connect id, iface Disable other networks and attempt connection with AP represented by given id
delete id, iface Remove WiFi credentials for given network id and interface
disable id, iface Disable connection with AP represented by given id
disconnect iface Disconnect given interface
modify id, iface, password Set a new password for given network id and interface
reassociate iface Reassociate with current AP for given interface
reconfigure Force wpa_supplicant to re-read its configuration file
reconnect iface Disconnect and reconnect given interface
save Save configuration changes to wpa_supplicant-wlan0.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.

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.

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

Debian Packaging

A systemd service file and Debian maintainer scripts are included in the debian directory, allowing peach-network to be easily bundled as a Debian package (.deb). The cargo-deb crate can be used to achieve this.

Install cargo-deb:

cargo install cargo-deb

Move into the repo:

cd peach-network

Build the package:

cargo deb

The output will be written to target/debian/peach-network_0.2.4_arm64.deb (or similar).

Build the package (aarch64):

cargo deb --target aarch64-unknown-linux-gnu

Install the package as follows:

sudo dpkg -i target/debian/peach-network_0.2.4_arm64.deb

The service will be automatically enabled and started.

Uninstall the service:

sudo apt-get remove peach-network

Remove configuration files (not removed with apt-get remove):

sudo apt-get purge peach-network

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": "ip", "params" : {"iface": "wlan0" }, "id":1 }' 127.0.0.1:5110

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": "ssid", "params" : {"iface": "wlan1" }, "id":1 }' 127.0.0.1:5110

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": "available_networks", "params" : {"iface": "wlan0" }, "id":1 }' 127.0.0.1:5110

Server response when interface is connected:

{"jsonrpc":"2.0","result":"[{\"frequency\":\"2412\",\"signal_level\":\"-72\",\"ssid\":\"Home\",\"flags\":\"[WPA2-PSK-CCMP][ESS]\"},{\"frequency\":\"2472\",\"signal_level\":\"-56\",\"ssid\":\"podetium\",\"flags\":\"[WPA2-PSK-CCMP+TKIP][ESS]\"}]","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": "traffic", "params" : {"iface": "wlan1" }, "id":1 }' 127.0.0.1:5110

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}

Retrieve status information for wlan0

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

Server response if interface exists:

{"jsonrpc":"2.0","result":"{\"address\":\"b8:27:eb:9b:5d:5f\",\"bssid\":\"f4:8c:eb:cd:31:81\",\"freq\":\"2412\",\"group_cipher\":\"CCMP\",\"id\":\"0\",\"ip_address\":\"192.168.0.162\",\"key_mgmt\":\"WPA2-PSK\",\"mode\":\"station\",\"pairwise_cipher\":\"CCMP\",\"ssid\":\"Home\",\"wpa_state\":\"COMPLETED\"}","id":1}

Server response when interface is not found:

{"jsonrpc":"2.0","error":{"code":-32013,"message":"Failed to open control interface for wpasupplicant: No such file or directory (os error 2)"},"id":1}

Licensing

AGPL-3.0