.. | ||
.cargo | ||
conf | ||
debian | ||
src | ||
.gitignore | ||
.travis.yml | ||
Cargo.toml | ||
notes.txt | ||
README.md |
peach-network
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