Class luci.ip
LuCI IP calculation and netlink access library.
Functions
| new (address, netmask) | Construct a new luci.ip.cidr instance and autodetect the address family. |
| IPv4 (address, netmask) | Construct a new IPv4 luci.ip.cidr instance. |
| IPv6 (address, netmask) | Construct a new IPv6 luci.ip.cidr instance. |
| MAC (address, netmask) | Construct a new MAC luci.ip.cidr instance. |
| checkip4 (address) | Verify an IPv4 address. |
| checkip6 (address) | Verify an IPv6 address. |
| checkmac (address) | Verify an ethernet MAC address. |
| route (address) | Determine the route leading to the given destination. |
| routes (filter, callback) | Fetch all routes, optionally matching the given criteria. |
| neighbors (filter, callback) | Fetches entries from the IPv4 ARP and IPv6 neighbour kernel table |
| link (device) | Fetch basic device information |
Functions
- new (address, netmask)
-
Construct a new luci.ip.cidr instance and autodetect the address family.
Throws an error if the given strings do not represent a valid address or
if the given optional netmask is of a different family.
Parameters
- address: String containing a valid IPv4 or IPv6 address, optionally with prefix size (CIDR notation) or netmask separated by slash.
-
netmask: String containing a valid IPv4 or IPv6 netmask or number
containing a prefix size in bits (
0..32for IPv4,0..128for IPv6). Overrides mask embedded in the first argument if specified. (optional)
Usage:
addr = luci.ip.new("10.24.0.1/24") addr = luci.ip.new("10.24.0.1/255.255.255.0") addr = luci.ip.new("10.24.0.1", "255.255.255.0") -- separate netmask addr = luci.ip.new("10.24.0.1/24", 16) -- override netmask addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64") addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/ffff:ffff:ffff:ffff::") addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17", "ffff:ffff:ffff:ffff::") addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64", 128) -- override netmaskReturn value:
Aluci.ip.cidrobject representing the given address/mask range.See also:
- IPv4 (address, netmask)
-
Construct a new IPv4 luci.ip.cidr instance.
Throws an error if the given string does not represent a valid IPv4 address or
if the given optional netmask is of a different family.
Parameters
- address: String containing a valid IPv4, optionally with prefix size (CIDR notation) or netmask separated by slash.
-
netmask: String containing a valid IPv4 netmask or number
containing a prefix size between
0and32bit. Overrides mask embedded in the first argument if specified. (optional)
Usage:
addr = luci.ip.IPv4("10.24.0.1/24") addr = luci.ip.IPv4("10.24.0.1/255.255.255.0") addr = luci.ip.IPv4("10.24.0.1", "255.255.255.0") -- separate netmask addr = luci.ip.IPv4("10.24.0.1/24", 16) -- override netmaskReturn value:
Aluci.ip.cidrobject representing the given IPv4 range.See also:
- IPv6 (address, netmask)
-
Construct a new IPv6 luci.ip.cidr instance.
Throws an error if the given string does not represent a valid IPv6 address or
if the given optional netmask is of a different family.
Parameters
- address: String containing a valid IPv6, optionally with prefix size (CIDR notation) or netmask separated by slash.
-
netmask: String containing a valid IPv4 netmask or number
containing a prefix size between
0and128bit. Overrides mask embedded in the first argument if specified. (optional)
Usage:
addr6 = luci.ip.IPv6("fe80::221:63ff:fe75:aa17/64") addr6 = luci.ip.IPv6("fe80::221:63ff:fe75:aa17/ffff:ffff:ffff:ffff::") addr6 = luci.ip.IPv6("fe80::221:63ff:fe75:aa17", "ffff:ffff:ffff:ffff::") addr6 = luci.ip.IPv6("fe80::221:63ff:fe75:aa17/64", 128) -- override netmaskReturn value:
Aluci.ip.cidrobject representing the given IPv6 range.See also:
- MAC (address, netmask)
-
Construct a new MAC luci.ip.cidr instance.
Throws an error if the given string does not represent a valid ethernet MAC
address or if the given optional mask is of a different family.
Parameters
- address: String containing a valid ethernet MAC address, optionally with prefix size (CIDR notation) or mask separated by slash.
-
netmask: String containing a valid MAC address mask or number
containing a prefix size between
0and48bit. Overrides mask embedded in the first argument if specified. (optional)
Usage:
intel_macs = luci.ip.MAC("C0:B6:F9:00:00:00/24") intel_macs = luci.ip.MAC("C0:B6:F9:00:00:00/FF:FF:FF:0:0:0") intel_macs = luci.ip.MAC("C0:B6:F9:00:00:00", "FF:FF:FF:0:0:0") intel_macs = luci.ip.MAC("C0:B6:F9:00:00:00/24", 48) -- override maskReturn value:
Aluci.ip.cidrobject representing the given MAC address range.See also:
- checkip4 (address)
-
Verify an IPv4 address.
Checks whether given argument is a preexisting luci.ip.cidr IPv4 address
instance or a string literal convertible to an IPv4 address and returns a
plain Lua string containing the canonical representation of the address.
If the argument is not a valid address, returns nothing. This function is
intended to aid in safely verifying address literals without having to deal
with exceptions.
Parameters
- address: String containing a valid IPv4 address or existing luci.ip.cidr IPv4 instance.
Usage:
ipv4 = luci.ip.checkip4(luci.ip.new("127.0.0.1")) -- "127.0.0.1" ipv4 = luci.ip.checkip4("127.0.0.1") -- "127.0.0.1" ipv4 = luci.ip.checkip4("nonesense") -- nothing ipv4 = luci.ip.checkip4(123) -- nothing ipv4 = luci.ip.checkip4(nil) -- nothing ipv4 = luci.ip.checkip4() -- nothingReturn value:
A string representing the given IPv4 address.See also:
- checkip6 (address)
-
Verify an IPv6 address.
Checks whether given argument is a preexisting luci.ip.cidr IPv6 address
instance or a string literal convertible to an IPv6 address and returns a
plain Lua string containing the canonical representation of the address.
If the argument is not a valid address, returns nothing. This function is
intended to aid in safely verifying address literals without having to deal
with exceptions.
Parameters
- address: String containing a valid IPv6 address or existing luci.ip.cidr IPv6 instance.
Usage:
ipv6 = luci.ip.checkip6(luci.ip.new("0:0:0:0:0:0:0:1")) -- "::1" ipv6 = luci.ip.checkip6("0:0:0:0:0:0:0:1") -- "::1" ipv6 = luci.ip.checkip6("nonesense") -- nothing ipv6 = luci.ip.checkip6(123) -- nothing ipv6 = luci.ip.checkip6(nil) -- nothing ipv6 = luci.ip.checkip6() -- nothingReturn value:
A string representing the given IPv6 address.See also:
- checkmac (address)
-
Verify an ethernet MAC address.
Checks whether given argument is a preexisting luci.ip.cidr MAC address
instance or a string literal convertible to an ethernet MAC and returns a
plain Lua string containing the canonical representation of the address.
If the argument is not a valid address, returns nothing. This function is
intended to aid in safely verifying address literals without having to deal
with exceptions.
Parameters
- address: String containing a valid MAC address or existing luci.ip.cidr MAC address instance.
Usage:
mac = luci.ip.checkmac(luci.ip.new("00-11-22-cc-dd-ee")) -- "00:11:22:CC:DD:EE" mac = luci.ip.checkmac("00:11:22:cc:dd:ee") -- "00:11:22:CC:DD:EE" mac = luci.ip.checkmac("nonesense") -- nothing mac = luci.ip.checkmac(123) -- nothing mac = luci.ip.checkmac(nil) -- nothing mac = luci.ip.checkmac() -- nothingReturn value:
A string representing the given MAC address.See also:
- route (address)
-
Determine the route leading to the given destination.
Parameters
-
address: A
luci.ip.cidrinstance or a string containing a valid IPv4 or IPv6 range as specified byluci.ip.new().
Usage:
- Find default gateway by getting route to Google's public NS server
rt = luci.ip.route("8.8.8.8") if rt ~= nil then print("gateway is", rt.gw) end - Determine IPv6 upstream interface
rt = luci.ip.route("2001::/7") if rt ~= nil then print("ipv6 upstream device is", rt.dev) end
Return value:
Table containing the fields described below.
Field Description typeRoute type with one of the following numeric values:
1RTN_UNICAST- Gateway or direct route2RTN_LOCAL- Accept locally3RTN_BROADCAST- Accept locally as broadcast send as broadcast4RTN_ANYCAST- Accept locally as broadcast but send as unicast5RTN_MULTICAST- Multicast routefamilyNumber containing the route family, 4for IPv4 or6for IPv6destDestination luci.ip.cidrinstancegwGateway luci.ip.cidrinstance (optional)fromSource address luci.ip.cidrinstance (optional)srcPreferred source luci.ip.cidrinstance (optional)devString containing the name of the outgoing interface iifString containing the name of the incoming interface (optional) tableNumber of the associated routing table ( 0..65535)protoNumber of the associated routing protocol scopeNumber describing the scope of the route, most commonly 0for global or253for on-linkmetricNumber describing the route metric (optional) expiresNumber of seconds the prefix is valid (IPv6 only, optional) errorRoute destination error code (optional) See also:
-
address: A
- routes (filter, callback)
-
Fetch all routes, optionally matching the given criteria.
Parameters
-
filter:
Table containing one or more of the possible filter critera described below (optional)
Field Description familyNumber describing the address family to return - 4selects IPv4 routes,6IPv6 ones. Any other value selects both.iifString containing the incoming route interface to match. oifString containing the outgoing route interface to match. typeNumeric type to match, e.g. 1for unicast.scopeNumeric scope to match, e.g. 253for onlink.protoNumeric protocol to match, e.g. 2for boot.tableNumeric routing table to match ( 0..65535).gwString containing the gateway address to match. Can be in any notation specified by luci.ip.new(). Prefix matching is performed when comparing the routes, e.g. "192.168.1.0/24" would select routes with gateway addresses192.168.1.1 .. 192.168.1.255.destString containing the destination to match. Prefix matching is performed. fromString containing the source address to match. Prefix matching is performed. srcString containing the preferred source address to match. Prefix matching is performed. dest_exactString containing the destination to match. Exact matching is performed, e.g. dest = "0.0.0.0/0"would match any IPv4 route whiledest_exact = "0.0.0.0/0"will only match the default route.from_exactString containing the source address to match. Exact matching is performed. -
callback:
Callback function to invoke for each found route instead of returning one table of route objects (optional)
Usage:
- Find all IPv4 default routes:
luci.ip.routes({ dest_exact = "0.0.0.0/0" }, function(rt) print(rt.type, rt.gw, rt.dev) end) - Find all global IPv6 prefixes on the current system:
luci.ip.routes({ from = "2001::/7" }, function(rt) print(rt.from) end) - Fetch all IPv4 routes:
routes = luci.ip.routes({ family = 4 }) for _, rt in ipairs(routes) do print(rt.dest, rt.gw, rt.dev) end
Return value:
If no callback function is provided, a table of routes as specified byluci.ip.route()is returned. If a callback function is given, it is invoked for each route and nothing is returned.See also:
-
filter:
- neighbors (filter, callback)
-
Fetches entries from the IPv4 ARP and IPv6 neighbour kernel table
Parameters
-
filter:
Table containing one or more of the possible filter critera described below (optional)
Field Description familyNumber describing the address family to return - 4selects IPv4 ARP,6select IPv6 neighbour entries. Any other value selects both.devString containing the associated interface to match. destString containing the associated address to match. Can be in any notation specified by luci.ip.new(). Prefix matching is performed when comparing the addresses, e.g. "192.168.1.0/24" would select ARP entries for192.168.1.1 .. 192.168.1.255.macString containing MAC address to match. -
callback:
Callback function to invoke for each found neighbour entry instead of returning one table of neighbour entries (optional)
Usage:
- Find all ARP neighbours in the LAN:
luci.ip.neighbors({ dest = "192.168.0.0/16" }, function(n) print(n.dest, n.mac) end) - Find all active IPv6 addresses of host with given MAC:
luci.ip.neighbors({ family = 6, mac = "00:21:63:75:aa:17" }, function(n) print(n.dest) end)
Return value:
If no callback function is provided, a table of neighbour entries is returned. If a callback function is given, it is invoked for each entry and nothing is returned. A neighbour entry is a table containing the following fields:Field Description familyNumber containing the neighbour entry family, 4for IPv4 ARP or6for IPv6 NDPdevString containing the associated device of the neighbour entry destIP address luci.ip.cidrinstancemacMAC address luci.ip.cidrinstancerouterBoolean "true" if the neighbour entry is a router (IPv6, optional) proxyBoolean "true" if this is a proxy entry (optional) incompleteBoolean "true" if the entry is in incomplete state (optional) reachableBoolean "true" if the entry is in reachable state (optional) staleBoolean "true" if the entry is stale (optional) delayBoolean "true" if the entry is delayed (optional) probeBoolean "true" if the entry is in probe state (optional) failedBoolean "true" if the entry is in failed state (optional) noarpBoolean "true" if the entry is not caused by NDP or ARP (optional) permanentBoolean "true" if the entry was statically configured from userspace (optional) -
filter:
- link (device)
-
Fetch basic device information
Parameters
- device: String containing the network device to query
Usage:
- Test whether device br-lan exists:
print(luci.ip.link("br-lan").name ~= nil) - Query MAC address of eth0:
print(luci.ip.link("eth0").mac)
Return value:
If the given interface is found, a table containing the fields described below is returned, else an empty table.Field Description upBoolean indicating whether the device is in IFF_RUNNING state typeNumeric value indicating the type of the device, e.g. 1for ethernet.nameString containing the name of the device masterIf queried device is a bridge port, string containing the name of parent bridge device (optional) mtuNumber containing the current MTU of the device qlenNumber containing the TX queue length of the device macMAC address luci.ip.cidrinstance representing the device ethernet address