JSDoc: Class: Network

Source:

network.js, line 628

Classes

Device
Hosts
Protocol
WifiDevice
WifiNetwork

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 884

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 1352

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 962

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 1390

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 728

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 719

Returns:

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

Type: 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 1087

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 1110

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>>

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

Queries the internal DSL modem type from board information.

Source:

network.js, line 1594

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)>

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 1611

Returns:

Returns a Hosts instance describing host known on the system.

Type: Promise.<LuCI.Network.Hosts>

getIfnameOf(obj) → {null|string}

Obtains the 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 1583

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 921

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 946

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 backend, optionally using the given network name.

Parameters:

Name	Type	Attributes	Default	Description
`protoname`	string			The protocol backend 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 750

Returns:

Returns the instantiated protocol backend 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 backend classes.

Source:

network.js, line 765

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 1538

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 array.

Source:

network.js, line 1493

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 array.

Source:

network.js, line 1472

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 lookup, e.g. `radio0` for the first mac80211 phy on the system.

Source:

network.js, line 1240

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 1260

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 lookup. 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 1289

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)>

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 1223

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 bit count.
`v6`	boolean	<optional>	false	Whether to parse the given netmask as IPv4 (`false`) or IPv6 (`true`) address.

Source:

network.js, line 664

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 646

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 translation for the given protocol error code.

Source:

network.js, line 853

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 833

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

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

This functions internally calls Class.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 `Class.extend()`.

Source:

network.js, line 792

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 1026

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 an 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 containg 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 containg 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 1504

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 666

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 amount of milliseconds the peer has been inactive, e.g. due to powersave.
`connected_time`	number		The amount 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 powersafe 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 powersafe 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 powersafe mode for all non-peer neigbours, 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 3581

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 tranmission 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 tranmission 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.

Source:

network.js, line 3691

WifiScanResult

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

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 3105