196 lines
6.1 KiB
Markdown
196 lines
6.1 KiB
Markdown
# Network core status and configuration
|
|
|
|
- [`[synit]/protocols/schemas/network.prs`](https://git.syndicate-lang.org/synit/synit/src/branch/main/protocols/schemas/network.prs)
|
|
|
|
[interface monitor]: https://git.syndicate-lang.org/synit/synit/src/branch/main/packaging/packages/synit-config/files/usr/lib/synit/python/synit/daemon/interface_monitor.py
|
|
[wifi daemon]: https://git.syndicate-lang.org/synit/synit/src/branch/main/packaging/packages/synit-config/files/usr/lib/synit/python/synit/daemon/wifi_daemon.py
|
|
[network.pr]: https://git.syndicate-lang.org/synit/synit/src/branch/main/packaging/packages/synit-config/files/etc/syndicate/services/network.pr
|
|
[wifi.pr]: https://git.syndicate-lang.org/synit/synit/src/branch/main/packaging/packages/synit-config/files/etc/syndicate/services/wifi.pr
|
|
[modem.pr]: https://git.syndicate-lang.org/synit/synit/src/branch/main/packaging/packages/synit-config/files/etc/syndicate/services/modem.pr
|
|
|
|
The definitions in this protocol are used by the Synit daemons responsible for detecting and
|
|
responding to changes in the configuration of network devices.
|
|
|
|
**Implementation.** As of October 2022, this protocol is mostly implemented in
|
|
- the [interface monitor][],
|
|
- the [wifi daemon][], and
|
|
- the scripting around [network state changes][network.pr].
|
|
- the scripting around the [wifi subsystem][wifi.pr].
|
|
- the scripting around [mobile data][modem.pr].
|
|
|
|
## Network interface presence and state
|
|
|
|
The [interface monitor][] daemon uses the Linux netlink protocol to monitor changes in
|
|
interface presence and state. In response to netlink messages, it maintains an `Interface`
|
|
assertion for each network interface in the system.
|
|
|
|
```
|
|
Interface = <interface
|
|
@name string
|
|
@index int
|
|
@type InterfaceType
|
|
@administrativeState AdministrativeState
|
|
@operationalState OperationalState
|
|
@carrier CarrierState
|
|
@linkAddr string> .
|
|
```
|
|
|
|
The `InterfaceType` is synthesised by the interface monitor daemon based on somewhat ad-hoc
|
|
heuristics.
|
|
|
|
```
|
|
InterfaceType =
|
|
/ ; `lo` and friends
|
|
=loopback
|
|
/ ; `eth0`, bridges, anything that isn't loopback and isn't wireless
|
|
=normal
|
|
/ ; 'wlan0' and friends
|
|
=wireless
|
|
.
|
|
```
|
|
|
|
The `AdministrativeState` of an interface describes the state that the operator of the machine
|
|
wishes the interface to be in (according to the kernel).
|
|
|
|
```
|
|
AdministrativeState = =unknown / =down / =up .
|
|
```
|
|
|
|
The `OperationalState` and `CarrierState` taken together, by contrast, describe the *actual*
|
|
state of the interface.
|
|
|
|
```
|
|
OperationalState =
|
|
/ =unknown
|
|
/ =down
|
|
/ @lowerLayerDown =lower-layer-down
|
|
/ =testing
|
|
/ =dormant
|
|
/ =up
|
|
.
|
|
|
|
CarrierState =
|
|
/ @noCarrier =no-carrier
|
|
/ =carrier
|
|
.
|
|
```
|
|
|
|
## Route presence and state
|
|
|
|
The [interface monitor][] daemon also listens for netlink messages describing network route
|
|
presence and state changes, maintaining a `Route` assertion for each route present.
|
|
|
|
```
|
|
Route = <route
|
|
@addressFamily AddressFamily
|
|
@destination RouteDestination
|
|
@priority int
|
|
@typeOfService int
|
|
@interfaceName RouteInterface
|
|
@gateway Gateway> .
|
|
|
|
AddressFamily = =ipv4 / =ipv6 / @other int .
|
|
RouteDestination = =default / @prefix <prefix @net string @bits int> .
|
|
RouteInterface = @name string / @none #f .
|
|
Gateway = @addr string / @none #f .
|
|
```
|
|
|
|
## Default route presence
|
|
|
|
The [network.pr][] scripts respond to presence of `Route` records with a `default`
|
|
`destination` field by asserting a `DefaultRoute` record. Applications may use the presence or
|
|
absence of a `DefaultRoute` record to decide whether or not internet access is currently
|
|
present.
|
|
|
|
```
|
|
DefaultRoute = <default-route @addressFamily AddressFamily> .
|
|
```
|
|
|
|
## Wi-fi associations
|
|
|
|
The [wifi.pr][] script starts an instance of the [wifi daemon][] and an instance of
|
|
[`wpa_supplicant`](https://w1.fi/cgit/hostap/tree/README) for each `Interface` of type
|
|
`wireless`. The wifi daemon speaks with the `wpa_supplicant` instance to do network scanning as
|
|
well as managing network attachments. It publishes a `WifiAssociation` for each active
|
|
connection to a wifi access point.
|
|
|
|
```
|
|
WifiAssociation = <wifi-association @interfaceName string @ssid string @state WifiAssociationState> .
|
|
WifiAssociationState = @inProgress =in-progress / =ready .
|
|
```
|
|
|
|
## Hotspots
|
|
|
|
In future, the software will use `HotspotState` assertions to publish the presence and state of
|
|
wifi hotspots hosted by the device.
|
|
|
|
```
|
|
HotspotState = <hotspot-state @interfaceName string @ssid string @stationCount int> .
|
|
```
|
|
|
|
## AP scanning
|
|
|
|
In future, the software will assert `AvailableAccessPoint` with information it learns from
|
|
network scanning.
|
|
|
|
```
|
|
AvailableAccessPoint = <available-ap @interfaceName string @ssid string> .
|
|
```
|
|
|
|
## Network-related user settings
|
|
|
|
A number of user setting assertions control the network.
|
|
|
|
### Mobile Data
|
|
|
|
Asserting `MobileDataApn` and `MobileDataEnabled` causes the [modem.pr][] script to enable a
|
|
cellular data link.
|
|
|
|
```
|
|
MobileDataApn = <mobile-data-apn @apn string> .
|
|
MobileDataEnabled = <mobile-data-enabled> .
|
|
```
|
|
|
|
### Wifi network preferences
|
|
|
|
```
|
|
WifiAuthentication =
|
|
/ ; No authentication necessary: open network
|
|
=open
|
|
/ ; Pre-shared key (WPA2-PSK etc)
|
|
<psk @password string>
|
|
/ ; Other, not-yet-implemented
|
|
@other any
|
|
.
|
|
```
|
|
|
|
Each [wifi daemon][] responds to `SelectedWifiNetwork` assertions for its interface by trying
|
|
to connect to the named SSID using the provided credentials. The daemon asserts a
|
|
`WifiAssociation` in response.
|
|
|
|
```
|
|
SelectedWifiNetwork = <selected-wifi-network
|
|
@interfaceName string
|
|
@ssid string
|
|
@authentication WifiAuthentication> .
|
|
```
|
|
|
|
In future, user `Hotspot` assertions will cause setup of a wifi hotspot, hosted by the device.
|
|
|
|
```
|
|
Hotspot = <hotspot
|
|
@interfaceName string
|
|
@ssid string
|
|
@authentication WifiAuthentication> .
|
|
```
|
|
|
|
In future, `SavedWifiNetwork` assertions will hold records of previously-configured wifi
|
|
connection details.
|
|
|
|
```
|
|
SavedWifiNetwork = <saved-wifi-network
|
|
@ssid string
|
|
@authentication WifiAuthentication
|
|
@priority double> .
|
|
```
|