Class: Network

LuCI. Network

The LuCI.Network class combines data from multiple ubus apis to provide an abstraction of the current network configuration state.

It provides methods to enumerate interfaces and devices, to query current configuration details and to manipulate settings.

new LuCI.Network()

network.js, line 628

Classes

Device
Hosts
Protocol
WifiDevice
WifiNetwork

Methods

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

network.js, line 884

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 1352

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 962

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 1390

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 728

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 719

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 1087

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 1110

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 1594

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 1611

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 1583

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 921

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 946

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 750

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 765

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 1538

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 1493

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 1472

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 1240

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 1260

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 1289

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.

isIgnoredDevice(name){boolean}

network.js, line 1223

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 664

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 646

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 853

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 833

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 792

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 1026

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.