Class: network

Classes

Device

Hosts

Protocol

WifiDevice

WifiNetwork

Methods

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

network.js, line 906

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.

Name	Type	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.

Returns:

Type	Description
Promise.<(null|LuCI.network.Protocol)>	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.

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

network.js, line 1364

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

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.

Returns:

Type	Description
Promise.<(null|LuCI.network.WifiNetwork)>	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.

deleteNetwork(name){Promise.<boolean>}

network.js, line 984

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

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

Returns:

Type	Description
Promise.<boolean>	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.

deleteWifiNetwork(netname){Promise.<boolean>}

network.js, line 1402

Deletes the given wireless network from the configuration.

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.

Returns:

Type	Description
Promise.<boolean>	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.

flushCache(){Promise.<Object>}

network.js, line 750

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

Returns:

Type	Description
Promise.<Object>	Returns a promise resolving to the internal network state object.

formatWifiEncryption(encryption){null|string}

network.js, line 741

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

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

Returns:

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

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

network.js, line 1115

Get a Device instance describing the given network device.

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

Returns:

Type	Description
Promise.<(null|LuCI.network.Device)>	Returns a promise resolving to the Device instance describing the network device or null if the given device name could not be found.

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

network.js, line 1138

Get a sorted list of all found network devices.

Returns:

Type	Description
Promise.<Array.<LuCI.network.Device>>	Returns a promise resolving to a sorted array of Device class instances describing the network devices found on the system.

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

network.js, line 1664

Queries the internal DSL modem type from board information.

Returns:

Type	Description
Promise.<(null|string)>	Returns a promise resolving to the type of the internal modem (e.g. vdsl) or to null if no internal modem is present.

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

network.js, line 1681

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.

Returns:

Type	Description
Promise.<LuCI.network.Hosts>	Returns a Hosts instance describing host known on the system.

getIfnameOf(obj){null|string}

network.js, line 1653

Obtains the the network device name of the given object.

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.

Returns:

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

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

network.js, line 943

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

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

Returns:

Type	Description
Promise.<(null|LuCI.network.Protocol)>	Returns a promise resolving to a Protocol subclass instance describing the network or null if the network did not exist.

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

network.js, line 968

Gets an array containing all known networks.

Returns:

Type	Description
Promise.<Array.<LuCI.network.Protocol>>	Returns a promise resolving to a name-sorted array of Protocol subclass instances describing all known networks.

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

network.js, line 772

Instantiates the given Protocol backend, optionally using the given network name.

Name	Type	Default	Description
protoname	string		The protocol backend to use, e.g. static or dhcp.
netname	string	__dummy__	optional 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.

Returns:

Type	Description
null | LuCI.network.Protocol	Returns the instantiated protocol backend class or null if the given protocol isn't known.

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

network.js, line 787

Obtains instances of all known Protocol backend classes.

Returns:

Type	Description
Array.<LuCI.network.Protocol>	Returns an array of protocol class instances.

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

network.js, line 1558

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

Returns:

Type	Description
Promise.<Object.<string, LuCI.network.SwitchTopology>>	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.

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

network.js, line 1509

Get IPv6 wan networks.

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

Returns:

Type	Description
Promise.<Array.<LuCI.network.Protocol>>	Returns a promise resolving to an array of Protocol subclass instances describing the found IPv6 default route interfaces.

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

network.js, line 1484

Get IPv4 wan networks.

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

Returns:

Type	Description
Promise.<Array.<LuCI.network.Protocol>>	Returns a promise resolving to an array of Protocol subclass instances describing the found default route interfaces.

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

network.js, line 1271

Get a WifiDevice instance describing the given wireless radio.

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.

Returns:

Type	Description
Promise.<(null|LuCI.network.WifiDevice)>	Returns a promise resolving to the WifiDevice instance describing the underlying radio device or null if the wireless radio could not be found.

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

network.js, line 1291

Obtain a list of all configured radio devices.

Returns:

Type	Description
Promise.<Array.<LuCI.network.WifiDevice>>	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.

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

network.js, line 1320

Get a WifiNetwork instance describing the given wireless network.

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.

Returns:

Type	Description
Promise.<(null|LuCI.network.WifiNetwork)>	Returns a promise resolving to the WifiNetwork instance describing the wireless network or null if the corresponding network could not be found.

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

network.js, line 1334

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

Returns:

Type	Description
Promise.<Array.<LuCI.network.WifiNetwork>>	Returns a promise resolving to an array of WifiNetwork instances describing the wireless networks. The array will be empty if no networks are found.

isIgnoredDevice(name){boolean}

network.js, line 1254

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.

Name	Type	Description
name	string	The device name to test.

Returns:

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

maskToPrefix(netmask, v6){null|number}

network.js, line 686

Converts the given netmask to a prefix size in bits.

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

Returns:

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

prefixToMask(bits, v6){null|string}

network.js, line 668

Converts the given prefix size in bits to a netmask.

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

Returns:

Type	Description
null | string	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.

registerErrorCode(code, message){boolean}

network.js, line 875

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

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.

Returns:

Type	Description
boolean	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.

registerPatternVirtual(pat)

network.js, line 855

Registers a new regular expression pattern to recognize virtual interfaces.

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

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

network.js, line 814

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.

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

Returns:

Type	Description
LuCI.network.Protocol	Returns the new Protocol subclass.

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

network.js, line 1054

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

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_]+.

Returns:

Type	Description
Promise.<boolean>	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 Definitions

LuCI.network.SwitchTopologyObject.<string, (Object|Array)>

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

Properties:

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)

LuCI.network.WifiEncryptionObject.<string, (boolean|Array.<(number|string)>)>

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

Properties:

Name	Type	Argument	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.

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

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

Properties:

Name	Type	Argument	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.

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

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

Properties:

Name	Type	Argument	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.

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

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

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.