vintage_net v0.6.2 VintageNet View Source
VintageNet
is network configuration library built specifically for Nerves
Project devices. It has the following features:
- Ethernet and WiFi support included. Extendible to other technologies
- Default configurations specified in your Application config
- Runtime updates to configurations are persisted and applied on next boot (can be disabled)
- Simple subscription to network status change events
- Connect to multiple networks at a time and prioritize which interfaces are used (Ethernet over WiFi over cellular)
- Internet connection monitoring and failure detection (currently slow and simplistic)
See github.com/nerves-networking/vintage_net for more information.
Link to this section Summary
Types
IP addresses in VintageNet can be specified as strings or tuples
Valid options for VintageNet.configure/3
A name for the network interface
The number of bits to use for an IPv4 subnet
The number of bits to use for an IPv6 subnet
The number of IP address bits for the subnet
Functions
Return a list of all interfaces on the system
Check if this is a valid configuration
Update the configuration of a network interface
Return a list of configured interface
Deconfigure settings for a specified interface.
Get the current value of a network property
Get a list of all properties matching the specified prefix
Return the settings for the specified interface
Print the current network status
Run a command on a network interface
Initiate an access point scan on a wireless interface
Subscribe to receive property change messages
Stop subscribing to property change messages
Check that the system has the required programs installed
Link to this section Types
IP addresses in VintageNet can be specified as strings or tuples
While VintageNet uses IP addresses in tuple form internally, it can be cumbersome to always convert to tuple form in practice. The general rule is that VintageNet is flexible in how it accepts IP addresses, but if you get an address from a VintageNet API, it will be in tuple form.
Valid options for VintageNet.configure/3
A name for the network interface
Names depend on the device drivers and any software that may rename them. Typical names on Nerves are:
- "eth0", "eth1", etc. for wired Ethernet interfaces
- "wlan0", etc. for WiFi interfaces
- "ppp0" for cellular modems
- "usb0" for gadget USB virtual Ethernet interfaces
The number of bits to use for an IPv4 subnet
For example, if you have a subnet mask of 255.255.255.0, then the prefix length would be 24.
The number of bits to use for an IPv6 subnet
prefix_length()
View Sourceprefix_length() :: ipv4_prefix_length() | ipv6_prefix_length()
The number of IP address bits for the subnet
Link to this section Functions
Return a list of all interfaces on the system
Check if this is a valid configuration
This runs the validation routines for a settings map, but doesn't try to apply them.
configure(ifname, config, options \\ [])
View Sourceconfigure(ifname(), map(), configure_options()) :: :ok | {:error, any()}
Update the configuration of a network interface
Configurations are validated and normalized before being applied. This means
that type errors and missing required fields will be caught and old or
redundant ways of specifying configurations will be fixed. Call
get_configuration/1
to see how what changes, if any, were made as part of
the normalization process.
After validation, the configuration is optionally persisted and applied.
See the VintageNet
documentation for configuration examples or your
VintageNet.Technology
provider's docs.
Options:
:persist
- set tofalse
to avoid persisting this configuration. System restarts will revert to the previous configuration.
Return a list of configured interface
Deconfigure settings for a specified interface.
Get the current value of a network property
See get_by_prefix/1
to get some or all properties.
get_by_prefix(prefix)
View Sourceget_by_prefix(VintageNet.PropertyTable.property()) :: [ {VintageNet.PropertyTable.property(), VintageNet.PropertyTable.value()} ]
Get a list of all properties matching the specified prefix
To get a list of all known properties and their values, call
VintageNet.get_by_prefix([])
Return the settings for the specified interface
Print the current network status
Run a command on a network interface
Commands are mostly network interface-specific. Also see the VintageNet
PropertyTable fo getting status or registering for status changes.
Initiate an access point scan on a wireless interface
The scan results are posted asynchronously to the ["interfaces", ifname, "access_points"]
property as they come in. It appears that there's some variation in how scanning
is implemented on WiFi adapters. One strategy that seems to work is to call scan/1
every
10 seconds or so while prompting a user to pick a WiFi network.
This is a utility function for calling the :scan
ioctl.
subscribe(name)
View Sourcesubscribe(VintageNet.PropertyTable.property()) :: :ok
Subscribe to receive property change messages
Messages have the form:
{VintageNet, property_name, old_value, new_value, metadata}
unsubscribe(name)
View Sourceunsubscribe(VintageNet.PropertyTable.property()) :: :ok
Stop subscribing to property change messages
Check that the system has the required programs installed
NOTE: This isn't completely implemented yet!