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

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

  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 1418

  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 1680

  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 1697

  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 1669

  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 1574

  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 1525

  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 1500

  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 1287

  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 1307

  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 1336

  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 1350

  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 1270

  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.