Class: network

Source: network.js, line 653

Classes

Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan

Methods

addNetwork(name, optionsopt) → {Promise.<(null|LuCI.network.Protocol)>}

Adds a new network of the given name and update it with the given uci option values.

If a network with the given name already exist but is empty, then this function will update its option, otherwise it will do nothing.

Parameters:

Name	Type	Attributes	Description
`name`	string		The name of the network to add. Must be in the format `[a-zA-Z0-9_]+`.
`options`	Object.<string, (string\|Array.<string>)>	<optional>	An object of uci option values to set on the new network or to update in an existing, empty network.

Source: network.js, line 921

Returns:

Returns a promise resolving to the Protocol subclass instance describing the added network or resolving to null if the name was invalid or if a non-empty network of the given name already existed.

Type:: Promise.<(null|LuCI.network.Protocol)>

addWifiNetwork(options) → {Promise.<(null|LuCI.network.WifiNetwork)>}

Adds a new wireless network to the configuration and sets its options to the provided values.

Parameters:

Name	Type	Description
`options`	Object.<string, (string\|Array.<string>)>	The options to set for the newly added wireless network. This object must at least contain a `device` property which is set to the radio name the new network belongs to.

Source: network.js, line 1458

Returns:

Returns a promise resolving to a WifiNetwork instance describing the newly added wireless network or null if the given options were invalid or if the associated radio device could not be found.

Type:: Promise.<(null|LuCI.network.WifiNetwork)>

deleteNetwork(name) → {Promise.<boolean>}

Deletes the given network and its references from the network and firewall configuration.

Parameters:

Name	Type	Description
`name`	string	The name of the network to delete.

Source: network.js, line 999

Returns:

Returns a promise resolving to either true if the network and references to it were successfully deleted from the configuration or false if the given network could not be found.

Type:: Promise.<boolean>

deleteWifiNetwork(netname) → {Promise.<boolean>}

Deletes the given wireless network from the configuration.

Parameters:

Name	Type	Description
`netname`	string	The name of the network to remove. This may be either a network ID in the form `radio#.network#` or a Linux network device name like `wlan0` which is resolved to the corresponding configuration section through `ubus` runtime information.

Source: network.js, line 1496

Returns:

Returns a promise resolving to true if the wireless network has been successfully deleted from the configuration or false if it could not be found.

Type:: Promise.<boolean>

flushCache() → {Promise.<Object>}

Flushes the local network state cache and fetches updated information from the remote ubus apis.

Source: network.js, line 765

Returns:

Returns a promise resolving to the internal network state object.

Type:: Promise.<Object>

formatWifiEncryption(encryption) → {null|string}

Converts a given encryption entry into a human readable string such as mixed WPA/WPA2 PSK (TKIP, CCMP) or WPA3 SAE (CCMP).

Parameters:

Name	Type	Description
`encryption`	LuCI.network.WifiEncryption	The wireless encryption entry to convert.

Source: network.js, line 756

Returns:

Returns the description string for the given encryption entry or null if the given entry was invalid.

Type:: null | string

getDSLModemType() → {Promise.<(null|string)>}

Queries the internal DSL modem type from board information.

Source: network.js, line 1760

Returns:

Returns a promise resolving to the type of the internal modem (e.g. vdsl) or to null if no internal modem is present.

Type:: Promise.<(null|string)>

getDevice(name) → {Promise.<(null|LuCI.network.Device)>}

Get a Device instance describing the given network device.

Parameters:

Name	Type	Description
`name`	string	The name of the network device to get, e.g. `eth0` or `br-lan`.

Source: network.js, line 1140

Returns:

Returns a promise resolving to the Device instance describing the network device or null if the given device name could not be found.

Type:: Promise.<(null|LuCI.network.Device)>

getDevices() → {Promise.<Array.<LuCI.network.Device>>}

Get a sorted list of all found network devices.

Source: network.js, line 1163

Returns:

Returns a promise resolving to a sorted array of Device class instances describing the network devices found on the system.

Type:: Promise.<Array.<LuCI.network.Device>>

getHostHints() → {Promise.<LuCI.network.Hosts>}

Queries aggregated information about known hosts.

This function aggregates information from various sources such as DHCP lease databases, ARP and IPv6 neighbour entries, wireless association list etc. and returns a Hosts class instance describing the found hosts.

Source: network.js, line 1777

Returns:

Returns a Hosts instance describing a host known on the system.

Type:: Promise.<LuCI.network.Hosts>

getIfnameOf(obj) → {null|string}

Obtains the network device name of the given object.

Parameters:

Name	Type	Description
`obj`	LuCI.network.Protocol \| LuCI.network.Device \| LuCI.network.WifiDevice \| LuCI.network.WifiNetwork \| string	The object to get the device name from.

Source: network.js, line 1749

Returns:

Returns a string containing the device name or null if the given object could not be converted to a name.

Type:: null | string

getNetwork(name) → {Promise.<(null|LuCI.network.Protocol)>}

Get a Protocol instance describing the network with the given name.

Parameters:

Name	Type	Description
`name`	string	The logical interface name of the network get, e.g. `lan` or `wan`.

Source: network.js, line 958

Returns:

Returns a promise resolving to a Protocol subclass instance describing the network or null if the network did not exist.

Type:: Promise.<(null|LuCI.network.Protocol)>

getNetworks() → {Promise.<Array.<LuCI.network.Protocol>>}

Gets an array containing all known networks.

Source: network.js, line 983

Returns:

Returns a promise resolving to a name-sorted array of Protocol subclass instances describing all known networks.

Type:: Promise.<Array.<LuCI.network.Protocol>>

getProtocol(protoname, netnameopt) → {null|LuCI.network.Protocol}

Instantiates the given Protocol back-end, optionally using the given network name.

Parameters:

Name	Type	Attributes	Default	Description
`protoname`	string			The protocol back-end to use, e.g. `static` or `dhcp`.
`netname`	string	<optional>	__dummy__	The network name to use for the instantiated protocol. This should be usually set to one of the interfaces described in /etc/config/network but it is allowed to omit it, e.g. to query protocol capabilities without the need for an existing interface.

Source: network.js, line 787

Returns:

Returns the instantiated protocol back-end class or null if the given protocol isn't known.

Type:: null | LuCI.network.Protocol

getProtocols() → {Array.<LuCI.network.Protocol>}

Obtains instances of all known Protocol back-end classes.

Source: network.js, line 802

Returns:

Returns an array of protocol class instances.

Type:: Array.<LuCI.network.Protocol>

getSwitchTopologies() → {Promise.<Object.<string, LuCI.network.SwitchTopology>>}

Returns the topologies of all swconfig switches found on the system.

Source: network.js, line 1654

Returns:

Returns a promise resolving to an object containing the topologies of each switch. The object keys correspond to the name of the switches such as switch0, the values are SwitchTopology objects describing the layout.

Type:: Promise.<Object.<string, LuCI.network.SwitchTopology>>

getWAN6Networks() → {Promise.<Array.<LuCI.network.Protocol>>}

Get IPv6 wan networks.

This function looks up all networks having a default ::/0 route and returns them as an array.

Source: network.js, line 1605

Returns:

Returns a promise resolving to an array of Protocol subclass instances describing the found IPv6 default route interfaces.

Type:: Promise.<Array.<LuCI.network.Protocol>>

getWANNetworks() → {Promise.<Array.<LuCI.network.Protocol>>}

Get IPv4 wan networks.

This function looks up all networks having a default 0.0.0.0/0 route and returns them as an array.

Source: network.js, line 1580

Returns:

Returns a promise resolving to an array of Protocol subclass instances describing the found default route interfaces.

Type:: Promise.<Array.<LuCI.network.Protocol>>

getWifiDevice(devname) → {Promise.<(null|LuCI.network.WifiDevice)>}

Get a WifiDevice instance describing the given wireless radio.

Parameters:

Name	Type	Description
`devname`	string	The configuration name of the wireless radio to look up, e.g. `radio0` for the first mac80211 phy on the system.

Source: network.js, line 1365

Returns:

Returns a promise resolving to the WifiDevice instance describing the underlying radio device or null if the wireless radio could not be found.

Type:: Promise.<(null|LuCI.network.WifiDevice)>

getWifiDevices() → {Promise.<Array.<LuCI.network.WifiDevice>>}

Obtain a list of all configured radio devices.

Source: network.js, line 1385

Returns:

Returns a promise resolving to an array of WifiDevice instances describing the wireless radios configured in the system. The order of the array corresponds to the order of the radios in the configuration.

Type:: Promise.<Array.<LuCI.network.WifiDevice>>

getWifiNetwork(netname) → {Promise.<(null|LuCI.network.WifiNetwork)>}

Get a WifiNetwork instance describing the given wireless network.

Parameters:

Name	Type	Description
`netname`	string	The name of the wireless network to look up. This may be either an uci configuration section ID, a network ID in the form `radio#.network#` or a Linux network device name like `wlan0` which is resolved to the corresponding configuration section through `ubus` runtime information.

Source: network.js, line 1414

Returns:

Returns a promise resolving to the WifiNetwork instance describing the wireless network or null if the corresponding network could not be found.

Type:: Promise.<(null|LuCI.network.WifiNetwork)>

getWifiNetworks() → {Promise.<Array.<LuCI.network.WifiNetwork>>}

Get an array of all WifiNetwork instances describing the wireless networks present on the system.

Source: network.js, line 1428

Returns:

Returns a promise resolving to an array of WifiNetwork instances describing the wireless networks. The array will be empty if no networks are found.

Type:: Promise.<Array.<LuCI.network.WifiNetwork>>

isIgnoredDevice(name) → {boolean}

Test if a given network device name is in the list of patterns for device names to ignore.

Ignored device names are usually Linux network devices which are spawned implicitly by kernel modules such as tunl0 or hwsim0 and which are unsuitable for use in network configuration.

Parameters:

Name	Type	Description
`name`	string	The device name to test.

Source: network.js, line 1348

Returns:

Returns true if the given name is in the ignore-pattern list, else returns false.

Type:: boolean

maskToPrefix(netmask, v6opt) → {null|number}

Converts the given netmask to a prefix size in bits.

Parameters:

Name	Type	Attributes	Default	Description
`netmask`	string			The netmask to convert into a bits count.
`v6`	boolean	<optional>	false	Whether to parse the given netmask as IPv4 (`false`) or IPv6 (`true`) address.

Source: network.js, line 701

Returns:

Returns the number of prefix bits contained in the netmask or null if the given netmask value was invalid.

Type:: null | number

prefixToMask(bits, v6opt) → {null|string}

Converts the given prefix size in bits to a netmask.

Parameters:

Name	Type	Attributes	Default	Description
`bits`	number			The prefix size in bits.
`v6`	boolean	<optional>	false	Whether to convert the bits value into an IPv4 netmask (`false`) or an IPv6 netmask (`true`).

Source: network.js, line 683

Returns:

Returns a string containing the netmask corresponding to the bit count or null when the given amount of bits exceeds the maximum possible value of 32 for IPv4 or 128 for IPv6.

Type:: null | string

registerErrorCode(code, message) → {boolean}

Registers a new human readable translation string for a Protocol error code.

Parameters:

Name	Type	Description
`code`	string	The `ubus` protocol error code to register a translation for, e.g. `NO_DEVICE`.
`message`	string	The message to use as a translation for the given protocol error code.

Source: network.js, line 890

Returns:

Returns true if the error code description has been added or false if either the arguments were invalid or if there already was a description for the given code.

Type:: boolean

registerPatternVirtual(pat)

Registers a new regular expression pattern to recognize virtual interfaces.

Parameters:

Name	Type	Description
`pat`	RegExp	A `RegExp` instance to match a virtual interface name such as `6in4-wan` or `tun0`.

Source: network.js, line 870

registerProtocol(protoname, methods) → {LuCI.network.Protocol}

Registers a new Protocol subclass with the given methods and returns the resulting subclass value.

This function internally calls baseclass.extend() on the Network.Protocol base class.

Parameters:

Name	Type	Description
`protoname`	string	The name of the new protocol to register.
`methods`	Object.<string, *>	The member methods and values of the new `Protocol` subclass to be passed to `baseclass.extend()`.

Source: network.js, line 829

Returns:

Returns the new Protocol subclass.

Type:: LuCI.network.Protocol

renameNetwork(oldName, newName) → {Promise.<boolean>}

Rename the given network and its references to a new name.

Parameters:

Name	Type	Description
`oldName`	string	The current name of the network.
`newName`	string	The name to rename the network to, must be in the format `[a-z-A-Z0-9_]+`.

Source: network.js, line 1079

Returns:

Returns a promise resolving to either true if the network was successfully renamed or false if the new name was invalid, if a network with the new name already exists or if the network to rename could not be found.

Type:: Promise.<boolean>

Type Definitions

SwitchTopology

Describes a swconfig switch topology by specifying the CPU connections and external port labels of a switch.

Type:

Object.<string, (Object|Array)>

Properties

Name Type Description

Name	Type	Description
`netdevs`	Object.<number, string>	The `netdevs` property points to an object describing the CPU port connections of the switch. The numeric key of the enclosed object is the port number, the value contains the Linux network device name the port is hardwired to.
`ports`	Array.<Object.<string, (boolean\|number\|string)>>	The `ports` property points to an array describing the populated ports of the switch in the external label order. Each array item is an object containing the following keys: `num` - the internal switch port number `label` - the label of the port, e.g. `LAN 1` or `CPU (eth0)` `device` - the connected Linux network device name (CPU ports only) `tagged` - a boolean indicating whether the port must be tagged to function (CPU ports only)

netdevs

Object.<number, string>

The netdevs property points to an object describing the CPU port connections of the switch. The numeric key of the enclosed object is the port number, the value contains the Linux network device name the port is hardwired to.

ports

Array.<Object.<string, (boolean|number|string)>>

The ports property points to an array describing the populated ports of the switch in the external label order. Each array item is an object containing the following keys:

num - the internal switch port number
label - the label of the port, e.g. LAN 1 or CPU (eth0)
device - the connected Linux network device name (CPU ports only)
tagged - a boolean indicating whether the port must be tagged to function (CPU ports only)

Source: network.js, line 1620

WifiEncryption

An encryption entry describes active wireless encryption settings such as the used key management protocols, active ciphers and protocol versions.

Type:

Object.<string, (boolean|Array.<(number|string)>)>

Properties

Name	Type	Attributes	Description
`enabled`	boolean		Specifies whether any kind of encryption, such as `WEP` or `WPA` is enabled. If set to `false`, then no encryption is active and the corresponding network is open.
`wep`	Array.<string>	<optional>	When the `wep` property exists, the network uses WEP encryption. In this case, the property is set to an array of active WEP modes which might be either `open`, `shared` or both.
`wpa`	Array.<number>	<optional>	When the `wpa` property exists, the network uses WPA security. In this case, the property is set to an array containing the WPA protocol versions used, e.g. `[ 1, 2 ]` for WPA/WPA2 mixed mode or `[ 3 ]` for WPA3-SAE.
`authentication`	Array.<string>	<optional>	The `authentication` property only applies to WPA encryption and is defined when the `wpa` property is set as well. It points to an array of active authentication suites used by the network, e.g. `[ "psk" ]` for a WPA(2)-PSK network or `[ "psk", "sae" ]` for mixed WPA2-PSK/WPA3-SAE encryption.
`ciphers`	Array.<string>	<optional>	If either WEP or WPA encryption is active, then the `ciphers` property will be set to an array describing the active encryption ciphers used by the network, e.g. `[ "tkip", "ccmp" ]` for a WPA/WPA2-PSK mixed network or `[ "wep-40", "wep-104" ]` for an WEP network.

Source: network.js, line 703

WifiPeerEntry

A wireless peer entry describes the properties of a remote wireless peer associated with a local network.

Type:

Object.<string, (boolean|number|string|LuCI.network.WifiRateEntry)>

Properties

Name	Type	Attributes	Description
`mac`	string		The MAC address (BSSID).
`signal`	number		The received signal strength.
`signal_avg`	number	<optional>	The average signal strength if supported by the driver.
`noise`	number	<optional>	The current noise floor of the radio. May be `0` or absent if not supported by the driver.
`inactive`	number		The number of milliseconds the peer has been inactive, e.g. due to power-saving.
`connected_time`	number		The number of milliseconds the peer is associated to this network.
`thr`	number	<optional>	The estimated throughput of the peer, May be `0` or absent if not supported by the driver.
`authorized`	boolean		Specifies whether the peer is authorized to associate to this network.
`authenticated`	boolean		Specifies whether the peer completed authentication to this network.
`preamble`	string		The preamble mode used by the peer. May be `long` or `short`.
`wme`	boolean		Specifies whether the peer supports WME/WMM capabilities.
`mfp`	boolean		Specifies whether management frame protection is active.
`tdls`	boolean		Specifies whether TDLS is active.
`mesh_llid`	number	<optional>	The mesh LLID, may be `0` or absent if not applicable or supported by the driver.
`mesh_plid`	number	<optional>	The mesh PLID, may be `0` or absent if not applicable or supported by the driver.
`mesh_plink`	string	<optional>	The mesh peer link state description, may be an empty string (`''`) or absent if not applicable or supported by the driver. The following states are known: `LISTEN` `OPN_SNT` `OPN_RCVD` `CNF_RCVD` `ESTAB` `HOLDING` `BLOCKED` `UNKNOWN`
`mesh_local_PS`	number	<optional>	The local power-save mode for the peer link, may be an empty string (`''`) or absent if not applicable or supported by the driver. The following modes are known: `ACTIVE` (no power save) `LIGHT SLEEP` `DEEP SLEEP` `UNKNOWN`
`mesh_peer_PS`	number	<optional>	The remote power-save mode for the peer link, may be an empty string (`''`) or absent if not applicable or supported by the driver. The following modes are known: `ACTIVE` (no power save) `LIGHT SLEEP` `DEEP SLEEP` `UNKNOWN`
`mesh_non_peer_PS`	number	<optional>	The power-save mode for all non-peer neighbours, may be an empty string (`''`) or absent if not applicable or supported by the driver. The following modes are known: `ACTIVE` (no power save) `LIGHT SLEEP` `DEEP SLEEP` `UNKNOWN`
`rx`	LuCI.network.WifiRateEntry		Describes the receiving wireless rate from the peer.
`tx`	LuCI.network.WifiRateEntry		Describes the transmitting wireless rate to the peer.

Source: network.js, line 4028

WifiRateEntry

A wireless rate entry describes the properties of a wireless transmission rate to or from a peer.

Type:

Object.<string, (boolean|number)>

Properties

Name	Type	Attributes	Description
`drop_misc`	number	<optional>	The amount of received misc. packages that have been dropped, e.g. due to corruption or missing authentication. Only applicable to receiving rates.
`packets`	number		The amount of packets that have been received or sent.
`bytes`	number		The amount of bytes that have been received or sent.
`failed`	number	<optional>	The amount of failed transmission attempts. Only applicable to transmit rates.
`retries`	number	<optional>	The amount of retried transmissions. Only applicable to transmit rates.
`is_ht`	boolean		Specifies whether this rate is an HT (IEEE 802.11n) rate.
`is_vht`	boolean		Specifies whether this rate is an VHT (IEEE 802.11ac) rate.
`mhz`	number		The channel width in MHz used for the transmission.
`rate`	number		The bitrate in bit/s of the transmission.
`mcs`	number	<optional>	The MCS index of the used transmission rate. Only applicable to HT or VHT rates.
`40mhz`	number	<optional>	Specifies whether the transmission rate used 40MHz wide channel. Only applicable to HT or VHT rates. Note: this option exists for backwards compatibility only, and its use is discouraged. The `mhz` field should be used instead to determine the channel width.
`short_gi`	boolean	<optional>	Specifies whether a short guard interval is used for the transmission. Only applicable to HT or VHT rates.
`nss`	number	<optional>	Specifies the number of spatial streams used by the transmission. Only applicable to VHT rates.
`he`	boolean	<optional>	Specifies whether this rate is an HE (IEEE 802.11ax) rate.
`he_gi`	number	<optional>	Specifies whether the guard interval used for the transmission. Only applicable to HE rates.
`he_dcm`	number	<optional>	Specifies whether dual concurrent modulation is used for the transmission. Only applicable to HE rates.
`eht`	boolean	<optional>	Specifies whether this rate is an EHT (IEEE 802.11be) rate.
`eht_gi`	number	<optional>	Specifies whether the guard interval is used for the transmission. Only applicable to EHT rates.
`eht_dcm`	number	<optional>	Specifies whether dual concurrent modulation is used for the transmission. Only applicable to EHT rates.

Source: network.js, line 4138

WifiScanResult

A wireless scan result object describes a neighbouring wireless network found in the vicinity.

Type:

Object.<string, (number|string|LuCI.network.WifiEncryption)>

Properties

Name	Type	Description
`ssid`	string	The SSID / Mesh ID of the network.
`bssid`	string	The BSSID if the network.
`mode`	string	The operation mode of the network (`Master`, `Ad-Hoc`, `Mesh Point`).
`channel`	number	The wireless channel of the network.
`signal`	number	The received signal strength of the network in dBm.
`quality`	number	The numeric quality level of the signal, can be used in conjunction with `quality_max` to calculate a quality percentage.
`quality_max`	number	The maximum possible quality level of the signal, can be used in conjunction with `quality` to calculate a quality percentage.
`encryption`	LuCI.network.WifiEncryption	The encryption used by the wireless network.

Source: network.js, line 3526