1047 lines
32 KiB
Plaintext
1047 lines
32 KiB
Plaintext
--- LuCI IP calculation and netlink access library.
|
|
module "luci.ip"
|
|
|
|
---[[
|
|
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.
|
|
@class function
|
|
@sort 1
|
|
@name new
|
|
@param address String containing a valid IPv4 or IPv6 address, optionally
|
|
with prefix size (CIDR notation) or netmask separated by slash.
|
|
@param netmask String containing a valid IPv4 or IPv6 netmask or number
|
|
containing a prefix size in bits (`0..32` for IPv4,
|
|
`0..128` for IPv6). Overrides mask embedded in the first argument
|
|
if specified. (optional)
|
|
@return A `luci.ip.cidr` object representing the given
|
|
address/mask range.
|
|
@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 netmask`
|
|
@see IPv4
|
|
@see IPv6
|
|
@see MAC
|
|
]]
|
|
|
|
---[[
|
|
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.
|
|
@class function
|
|
@sort 2
|
|
@name IPv4
|
|
@param address String containing a valid IPv4, optionally with prefix size
|
|
(CIDR notation) or netmask separated by slash.
|
|
@param netmask String containing a valid IPv4 netmask or number
|
|
containing a prefix size between `0` and `32` bit.
|
|
Overrides mask embedded in the first argument if specified. (optional)
|
|
@return A `luci.ip.cidr` object representing the given IPv4 range.
|
|
@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 netmask`
|
|
@see IPv6
|
|
@see MAC
|
|
]]
|
|
|
|
---[[
|
|
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.
|
|
@class function
|
|
@sort 3
|
|
@name IPv6
|
|
@param address String containing a valid IPv6, optionally with prefix size
|
|
(CIDR notation) or netmask separated by slash.
|
|
@param netmask String containing a valid IPv4 netmask or number
|
|
containing a prefix size between `0` and `128` bit.
|
|
Overrides mask embedded in the first argument if specified. (optional)
|
|
@return A `luci.ip.cidr` object representing the given IPv6 range.
|
|
@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 netmask`
|
|
@see IPv4
|
|
@see MAC
|
|
]]
|
|
|
|
---[[
|
|
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.
|
|
@class function
|
|
@sort 4
|
|
@name MAC
|
|
@param address String containing a valid ethernet MAC address, optionally with
|
|
prefix size (CIDR notation) or mask separated by slash.
|
|
@param netmask String containing a valid MAC address mask or number
|
|
containing a prefix size between `0` and `48` bit.
|
|
Overrides mask embedded in the first argument if specified. (optional)
|
|
@return A `luci.ip.cidr` object representing the given MAC address range.
|
|
@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 mask`
|
|
@see IPv4
|
|
@see IPv6
|
|
]]
|
|
|
|
---[[
|
|
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.
|
|
@class function
|
|
@sort 5
|
|
@name checkip4
|
|
@param address String containing a valid IPv4 address or existing
|
|
luci.ip.cidr IPv4 instance.
|
|
@return A string representing the given IPv4 address.
|
|
@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() -- nothing`
|
|
@see checkip6
|
|
@see checkmac
|
|
]]
|
|
|
|
---[[
|
|
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.
|
|
@class function
|
|
@sort 6
|
|
@name checkip6
|
|
@param address String containing a valid IPv6 address or existing
|
|
luci.ip.cidr IPv6 instance.
|
|
@return A string representing the given IPv6 address.
|
|
@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() -- nothing`
|
|
@see checkip4
|
|
@see checkmac
|
|
]]
|
|
|
|
---[[
|
|
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.
|
|
@class function
|
|
@sort 7
|
|
@name checkmac
|
|
@param address String containing a valid MAC address or existing luci.ip.cidr
|
|
MAC address instance.
|
|
@return A string representing the given MAC address.
|
|
@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() -- nothing`
|
|
@see checkip4
|
|
@see checkip6
|
|
]]
|
|
|
|
---[[
|
|
Determine the route leading to the given destination.
|
|
@class function
|
|
@sort 8
|
|
@name route
|
|
@param address A `luci.ip.cidr` instance or a string containing
|
|
a valid IPv4 or IPv6 range as specified by `luci.ip.new()`.
|
|
@return <p>Table containing the fields described below.</p>
|
|
<table id="routetable">
|
|
<tr><th>Field</th><th>Description</th></tr>
|
|
<tr><td>`type`<td>
|
|
<p>Route type with one of the following numeric values:</p>
|
|
<table>
|
|
<tr>
|
|
<td>`1`</td>
|
|
<td>`RTN_UNICAST` - Gateway or direct route</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`2`</td>
|
|
<td>`RTN_LOCAL` - Accept locally</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`3`</td>
|
|
<td>`RTN_BROADCAST` -
|
|
Accept locally as broadcast send as broadcast</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`4`</td>
|
|
<td>`RTN_ANYCAST` -
|
|
Accept locally as broadcast but send as unicast</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`5`</td>
|
|
<td>`RTN_MULTICAST` - Multicast route</td>
|
|
</tr>
|
|
</table>
|
|
</td></tr>
|
|
<tr>
|
|
<td>`family`</td>
|
|
<td>Number containing the route family, `4` for IPv4 or
|
|
`6` for IPv6</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`dest`</td>
|
|
<td>Destination `luci.ip.cidr` instance</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`gw`</td>
|
|
<td>Gateway `luci.ip.cidr` instance (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`from`</td>
|
|
<td>Source address `luci.ip.cidr` instance (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`src`</td>
|
|
<td>Preferred source `luci.ip.cidr` instance (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`dev`</td>
|
|
<td>String containing the name of the outgoing interface</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`iif`</td>
|
|
<td>String containing the name of the incoming interface (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`table`</td>
|
|
<td>Number of the associated routing table (`0..65535`)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`proto`</td>
|
|
<td>Number of the associated routing protocol</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`scope`</td>
|
|
<td>Number describing the scope of the route, most commonly
|
|
`0` for global or `253` for on-link</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`metric`</td>
|
|
<td>Number describing the route metric (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`expires`</td>
|
|
<td>Number of seconds the prefix is valid (IPv6 only, optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`error`</td>
|
|
<td>Route destination error code (optional)</td>
|
|
</tr>
|
|
</table>
|
|
@usage <ul>
|
|
<li>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`</li>
|
|
<li>Determine IPv6 upstream interface `rt = luci.ip.route("2001::/7")
|
|
if rt ~= nil then
|
|
print("ipv6 upstream device is", rt.dev)
|
|
end`</li>
|
|
</ul>
|
|
@see routes
|
|
]]
|
|
|
|
---[[
|
|
Fetch all routes, optionally matching the given criteria.
|
|
@class function
|
|
@sort 9
|
|
@name routes
|
|
@param filter <p>Table containing one or more of the possible filter
|
|
criteria described below (optional)</p><table>
|
|
<tr><th>Field</th><th>Description</th></tr>
|
|
<tr><td>`family`</td><td>
|
|
Number describing the address family to return - `4` selects
|
|
IPv4 routes, `6` IPv6 ones. Any other value selects both.
|
|
</td></tr>
|
|
<tr><td>`iif`</td><td>
|
|
String containing the incoming route interface to match.
|
|
</td></tr>
|
|
<tr><td>`oif`</td><td>
|
|
String containing the outgoing route interface to match.
|
|
</td></tr>
|
|
<tr><td>`type`</td><td>
|
|
Numeric type to match, e.g. `1` for unicast.
|
|
</td></tr>
|
|
<tr><td>`scope`</td><td>
|
|
Numeric scope to match, e.g. `253` for onlink.
|
|
</td></tr>
|
|
<tr><td>`proto`</td><td>
|
|
Numeric protocol to match, e.g. `2` for boot.
|
|
</td></tr>
|
|
<tr><td>`table`</td><td>
|
|
Numeric routing table to match (`0..65535`).
|
|
</td></tr>
|
|
<tr><td>`gw`</td><td>
|
|
String 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
|
|
addresses `192.168.1.1 .. 192.168.1.255`.
|
|
</td></tr>
|
|
<tr><td>`dest`</td><td>
|
|
String containing the destination to match. Prefix matching is performed.
|
|
</td></tr>
|
|
<tr><td>`from`</td><td>
|
|
String containing the source address to match. Prefix matching is performed.
|
|
</td></tr>
|
|
<tr><td>`src`</td><td>
|
|
String containing the preferred source address to match.
|
|
Prefix matching is performed.
|
|
</td></tr>
|
|
<tr><td>`dest_exact`</td><td>
|
|
String containing the destination to match. Exact matching is performed,
|
|
e.g. `dest = "0.0.0.0/0"` would match <em>any</em> IPv4 route
|
|
while `dest_exact = "0.0.0.0/0"` will <em>only</em> match the
|
|
default route.
|
|
</td></tr>
|
|
<tr><td>`from_exact`</td><td>
|
|
String containing the source address to match. Exact matching is performed.
|
|
</td></tr>
|
|
</table>
|
|
@param callback <p>Callback function to invoke for each found route
|
|
instead of returning one table of route objects (optional)</p>
|
|
@return If no callback function is provided, a table of routes
|
|
<a href="#routetable">as specified by `luci.ip.route()`</a>
|
|
is returned. If a callback function is given, it is invoked for each route
|
|
and nothing is returned.
|
|
@see route
|
|
@usage <ul>
|
|
<li>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)`</li>
|
|
<li>Find all global IPv6 prefixes on the current system:
|
|
`luci.ip.routes({ from = "2001::/7" }, function(rt)
|
|
print(rt.from)
|
|
end)`</li>
|
|
<li>Fetch all IPv4 routes:
|
|
`routes = luci.ip.routes({ family = 4 })
|
|
for _, rt in ipairs(routes) do
|
|
print(rt.dest, rt.gw, rt.dev)
|
|
end`</li>
|
|
</ul>
|
|
]]
|
|
|
|
---[[
|
|
Fetches entries from the IPv4 ARP and IPv6 neighbour kernel table
|
|
@class function
|
|
@sort 10
|
|
@name neighbors
|
|
@param filter <p>Table containing one or more of the possible filter
|
|
criteria described below (optional)</p><table>
|
|
<tr><th>Field</th><th>Description</th></tr>
|
|
<tr><td>`family`</td><td>
|
|
Number describing the address family to return - `4` selects
|
|
IPv4 ARP, `6` select IPv6 neighbour entries. Any other value
|
|
selects both.
|
|
</td></tr>
|
|
<tr><td>`dev`</td><td>
|
|
String containing the associated interface to match.
|
|
</td></tr>
|
|
<tr><td>`dest`</td><td>
|
|
String 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
|
|
for `192.168.1.1 .. 192.168.1.255`.
|
|
</td></tr>
|
|
<tr><td>`mac`</td><td>
|
|
String containing MAC address to match.
|
|
</td></tr>
|
|
</table>
|
|
@param callback <p>Callback function to invoke for each found neighbour
|
|
entry instead of returning one table of neighbour entries (optional)</p>
|
|
@return 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:
|
|
|
|
<table>
|
|
<tr><th>Field</th><th>Description</th></tr>
|
|
<tr>
|
|
<td>`family`</td>
|
|
<td>Number containing the neighbour entry family, `4` for IPv4
|
|
ARP or `6` for IPv6 NDP</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`dev`</td>
|
|
<td>String containing the associated device of the neighbour entry</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`dest`</td>
|
|
<td>IP address `luci.ip.cidr` instance</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`mac`</td>
|
|
<td>MAC address `luci.ip.cidr` instance</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`router`</td>
|
|
<td>Boolean "true" if the neighbour entry is a router (IPv6, optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`proxy`</td>
|
|
<td>Boolean "true" if this is a proxy entry (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`incomplete`</td>
|
|
<td>Boolean "true" if the entry is in incomplete state (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`reachable`</td>
|
|
<td>Boolean "true" if the entry is in reachable state (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`stale`</td>
|
|
<td>Boolean "true" if the entry is stale (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`delay`</td>
|
|
<td>Boolean "true" if the entry is delayed (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`probe`</td>
|
|
<td>Boolean "true" if the entry is in probe state (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`failed`</td>
|
|
<td>Boolean "true" if the entry is in failed state (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`noarp`</td>
|
|
<td>Boolean "true" if the entry is not caused by NDP or
|
|
ARP (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`permanent`</td>
|
|
<td>Boolean "true" if the entry was statically configured from
|
|
userspace (optional)</td>
|
|
</tr>
|
|
</table>
|
|
@usage <ul>
|
|
<li>Find all ARP neighbours in the LAN:
|
|
`luci.ip.neighbors({ dest = "192.168.0.0/16" }, function(n)
|
|
print(n.dest, n.mac)
|
|
end)`</li>
|
|
<li>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)`</li>
|
|
</ul>
|
|
]]
|
|
|
|
---[[
|
|
Fetch basic device information
|
|
@class function
|
|
@sort 11
|
|
@name link
|
|
@param device String containing the network device to query
|
|
@return If the given interface is found, a table containing the fields
|
|
described below is returned, else an empty table.
|
|
|
|
<table>
|
|
<tr><th>Field</th><th>Description</th></tr>
|
|
<tr>
|
|
<td>`up`</td>
|
|
<td>Boolean indicating whether the device is in IFF_RUNNING state</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`type`</td>
|
|
<td>Numeric value indicating the type of the device, e.g. `1`
|
|
for ethernet.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`name`</td>
|
|
<td>String containing the name of the device</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`master`</td>
|
|
<td>If queried device is a bridge port, string containing the name of
|
|
parent bridge device (optional)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`mtu`</td>
|
|
<td>Number containing the current MTU of the device</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`qlen`</td>
|
|
<td>Number containing the TX queue length of the device</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`mac`</td>
|
|
<td>MAC address `luci.ip.cidr` instance representing the device ethernet
|
|
address</td>
|
|
</tr>
|
|
</table>
|
|
@usage <ul>
|
|
<li>Test whether device br-lan exists:
|
|
`print(luci.ip.link("br-lan").name ~= nil)
|
|
`</li>
|
|
<li>Query MAC address of eth0:
|
|
`print(luci.ip.link("eth0").mac)
|
|
`</li>
|
|
</ul>
|
|
]]
|
|
|
|
|
|
--- IP CIDR Object.
|
|
-- Represents an IPv4 or IPv6 address range.
|
|
-- @cstyle instance
|
|
module "luci.ip.cidr"
|
|
|
|
---[[
|
|
Checks whether the CIDR instance is an IPv4 address range
|
|
|
|
@class function
|
|
@sort 1
|
|
@name cidr.is4
|
|
@see cidr.is6
|
|
@see cidr.ismac
|
|
@return `true` if the CIDR is an IPv4 range, else `false`
|
|
]]
|
|
|
|
---[[
|
|
Checks whether the CIDR instance is within the private RFC1918 address space
|
|
|
|
@class function
|
|
@sort 2
|
|
@name cidr.is4rfc1918
|
|
@return `true` if the entire range of this CIDR lies within one of
|
|
the ranges `10.0.0.0-10.255.255.255`,
|
|
`172.16.0.0-172.31.0.0` or
|
|
`192.168.0.0-192.168.255.255`, else `false`.
|
|
@usage `local addr = luci.ip.new("192.168.45.2/24")
|
|
if addr:is4rfc1918() then
|
|
print("Is a private address")
|
|
end`
|
|
]]
|
|
|
|
---[[
|
|
Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address
|
|
|
|
@class function
|
|
@sort 3
|
|
@name cidr.is4linklocal
|
|
@return `true` if the entire range of this CIDR lies within the range
|
|
the range `169.254.0.0-169.254.255.255`, else `false`.
|
|
@usage `local addr = luci.ip.new("169.254.34.125")
|
|
if addr:is4linklocal() then
|
|
print("Is a zeroconf address")
|
|
end`
|
|
]]
|
|
|
|
---[[
|
|
Checks whether the CIDR instance is an IPv6 address range
|
|
|
|
@class function
|
|
@sort 4
|
|
@name cidr.is6
|
|
@see cidr.is4
|
|
@see cidr.ismac
|
|
@return `true` if the CIDR is an IPv6 range, else `false`
|
|
]]
|
|
|
|
---[[
|
|
Checks whether the CIDR instance is an IPv6 link local address
|
|
|
|
@class function
|
|
@sort 5
|
|
@name cidr.is6linklocal
|
|
@return `true` if the entire range of this CIDR lies within the range
|
|
the `fe80::/10` range, else `false`.
|
|
@usage `local addr = luci.ip.new("fe92:53a:3216:af01:221:63ff:fe75:aa17/64")
|
|
if addr:is6linklocal() then
|
|
print("Is a linklocal address")
|
|
end`
|
|
]]
|
|
|
|
---[[
|
|
Checks whether the CIDR instance is an IPv6 mapped IPv4 address
|
|
|
|
@class function
|
|
@sort 6
|
|
@name cidr.is6mapped4
|
|
@return `true` if the address is an IPv6 mapped IPv4 address in the
|
|
form `::ffff:1.2.3.4`.
|
|
@usage `local addr = luci.ip.new("::ffff:192.168.1.1")
|
|
if addr:is6mapped4() then
|
|
print("Is a mapped IPv4 address")
|
|
end`
|
|
]]
|
|
|
|
---[[
|
|
Checks whether the CIDR instance is an ethernet MAC address range
|
|
|
|
@class function
|
|
@sort 7
|
|
@name cidr.ismac
|
|
@see cidr.is4
|
|
@see cidr.is6
|
|
@return `true` if the CIDR is a MAC address range, else `false`
|
|
]]
|
|
|
|
---[[
|
|
Checks whether the CIDR instance is a locally administered (LAA) MAC address
|
|
|
|
@class function
|
|
@sort 8
|
|
@name cidr.ismaclocal
|
|
@return `true` if the MAC address sets the locally administered bit.
|
|
@usage `local mac = luci.ip.new("02:C0:FF:EE:00:01")
|
|
if mac:ismaclocal() then
|
|
print("Is an LAA MAC address")
|
|
end`
|
|
]]
|
|
|
|
---[[
|
|
Checks whether the CIDR instance is a multicast MAC address
|
|
|
|
@class function
|
|
@sort 9
|
|
@name cidr.ismacmcast
|
|
@return `true` if the MAC address sets the multicast bit.
|
|
@usage `local mac = luci.ip.new("01:00:5E:7F:00:10")
|
|
if addr:ismacmcast() then
|
|
print("Is a multicast MAC address")
|
|
end`
|
|
]]
|
|
|
|
---[[
|
|
Checks whether this CIDR instance is lower than the given argument.
|
|
The comparisation follows these rules:
|
|
<ul><li>An IPv4 address is always lower than an IPv6 address and IPv6 addresses
|
|
are considered lower than MAC addresses</li>
|
|
<li>Prefix sizes are ignored</li></ul>
|
|
|
|
@class function
|
|
@sort 10
|
|
@name cidr.lower
|
|
@param addr A `luci.ip.cidr` instance or a string convertible by
|
|
`luci.ip.new()` to compare against.
|
|
@return `true` if this CIDR is lower than the given address,
|
|
else `false`.
|
|
@usage `local addr = luci.ip.new("192.168.1.1")
|
|
print(addr:lower(addr)) -- false
|
|
print(addr:lower("10.10.10.10/24")) -- false
|
|
print(addr:lower(luci.ip.new("::1"))) -- true
|
|
print(addr:lower(luci.ip.new("192.168.200.1"))) -- true
|
|
print(addr:lower(luci.ip.new("00:14:22:01:23:45"))) -- true`
|
|
@see cidr.higher
|
|
@see cidr.equal
|
|
]]
|
|
|
|
---[[
|
|
Checks whether this CIDR instance is higher than the given argument.
|
|
The comparisation follows these rules:
|
|
<ul><li>An IPv4 address is always lower than an IPv6 address and IPv6 addresses
|
|
are considered lower than MAC addresses</li>
|
|
<li>Prefix sizes are ignored</li></ul>
|
|
|
|
@class function
|
|
@sort 11
|
|
@name cidr.higher
|
|
@param addr A `luci.ip.cidr` instance or a string convertible by
|
|
`luci.ip.new()` to compare against.
|
|
@return `true` if this CIDR is higher than the given address,
|
|
else `false`.
|
|
@usage `local addr = luci.ip.new("192.168.1.1")
|
|
print(addr:higher(addr)) -- false
|
|
print(addr:higher("10.10.10.10/24")) -- true
|
|
print(addr:higher(luci.ip.new("::1"))) -- false
|
|
print(addr:higher(luci.ip.new("192.168.200.1"))) -- false
|
|
print(addr:higher(luci.ip.new("00:14:22:01:23:45"))) -- false`
|
|
@see cidr.lower
|
|
@see cidr.equal
|
|
]]
|
|
|
|
---[[
|
|
Checks whether this CIDR instance is equal to the given argument.
|
|
|
|
@class function
|
|
@sort 12
|
|
@name cidr.equal
|
|
@param addr A `luci.ip.cidr` instance or a string convertible by
|
|
`luci.ip.new()` to compare against.
|
|
@return `true` if this CIDR is equal to the given address,
|
|
else `false`.
|
|
@usage `local addr = luci.ip.new("192.168.1.1")
|
|
print(addr:equal(addr)) -- true
|
|
print(addr:equal("192.168.1.1")) -- true
|
|
print(addr:equal(luci.ip.new("::1"))) -- false
|
|
|
|
local addr6 = luci.ip.new("::1")
|
|
print(addr6:equal("0:0:0:0:0:0:0:1/64")) -- true
|
|
print(addr6:equal(luci.ip.new("fe80::221:63ff:fe75:aa17"))) -- false
|
|
|
|
local mac = luci.ip.new("00:14:22:01:23:45")
|
|
print(mac:equal("0:14:22:1:23:45")) -- true
|
|
print(mac:equal(luci.ip.new("01:23:45:67:89:AB")) -- false`
|
|
@see cidr.lower
|
|
@see cidr.higher
|
|
]]
|
|
|
|
---[[
|
|
Get or set prefix size of CIDR instance.
|
|
If the optional mask parameter is given, the prefix size of this CIDR is altered
|
|
else the current prefix size is returned.
|
|
|
|
@class function
|
|
@sort 13
|
|
@name cidr.prefix
|
|
@param mask Either a number containing the number of bits (`0..32`
|
|
for IPv4, `0..128` for IPv6 or `0..48` for MAC addresses) or a string
|
|
containing a valid netmask (optional)
|
|
@return Bit count of the current prefix size
|
|
@usage `local range = luci.ip.new("192.168.1.1/255.255.255.0")
|
|
print(range:prefix()) -- 24
|
|
|
|
range:prefix(16)
|
|
print(range:prefix()) -- 16
|
|
|
|
range:prefix("255.255.255.255")
|
|
print(range:prefix()) -- 32`
|
|
]]
|
|
|
|
---[[
|
|
Derive network address of CIDR instance.
|
|
|
|
Returns a new CIDR instance representing the network address of this instance
|
|
with all host parts masked out. The used prefix size can be overridden by the
|
|
optional mask parameter.
|
|
|
|
@class function
|
|
@sort 14
|
|
@name cidr.network
|
|
@param mask Either a number containing the number of bits (`0..32`
|
|
for IPv4, `0..128` for IPv6 or `0..48` for MAC addresses) or a string
|
|
containing a valid netmask (optional)
|
|
@return CIDR instance representing the network address
|
|
@usage `local range = luci.ip.new("192.168.62.243/255.255.0.0")
|
|
print(range:network()) -- "192.168.0.0"
|
|
print(range:network(24)) -- "192.168.62.0"
|
|
print(range:network("255.255.255.0")) -- "192.168.62.0"
|
|
|
|
local range6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
|
|
print(range6:network()) -- "fd9b:62b3:9cc5::"`
|
|
]]
|
|
|
|
---[[
|
|
Derive host address of CIDR instance.
|
|
|
|
This function essentially constructs a copy of this CIDR with the prefix size
|
|
set to `32` for IPv4, `128` for IPv6 or `48` for MAC addresses.
|
|
|
|
@class function
|
|
@sort 15
|
|
@name cidr.host
|
|
@return CIDR instance representing the host address
|
|
@usage `local range = luci.ip.new("172.19.37.45/16")
|
|
print(range) -- "172.19.37.45/16"
|
|
print(range:host()) -- "172.19.37.45"`
|
|
]]
|
|
|
|
---[[
|
|
Derive netmask of CIDR instance.
|
|
|
|
Constructs a CIDR instance representing the netmask of this instance. The used
|
|
prefix size can be overridden by the optional mask parameter.
|
|
|
|
@class function
|
|
@sort 16
|
|
@name cidr.mask
|
|
@param mask Either a number containing the number of bits (`0..32`
|
|
for IPv4, `0..128` for IPv6 or `0..48` for MAC addresses) or a string
|
|
containing a valid netmask (optional)
|
|
@return CIDR instance representing the netmask
|
|
@usage `local range = luci.ip.new("172.19.37.45/16")
|
|
print(range:mask()) -- "255.255.0.0"
|
|
print(range:mask(24)) -- "255.255.255.0"
|
|
print(range:mask("255.0.0.0")) -- "255.0.0.0"`
|
|
]]
|
|
|
|
---[[
|
|
Derive broadcast address of CIDR instance.
|
|
|
|
Constructs a CIDR instance representing the broadcast address of this instance.
|
|
The used prefix size can be overridden by the optional mask parameter.
|
|
|
|
This function has no effect on IPv6 or MAC address instances, it will return
|
|
nothing in this case.
|
|
|
|
@class function
|
|
@sort 17
|
|
@name cidr.broadcast
|
|
@param mask Either a number containing the number of bits (`0..32` for IPv4) or
|
|
a string containing a valid netmask (optional)
|
|
@return Return a new CIDR instance representing the broadcast address if this
|
|
instance is an IPv4 range, else return nothing.
|
|
@usage `local range = luci.ip.new("172.19.37.45/16")
|
|
print(range:broadcast()) -- "172.19.255.255"
|
|
print(range:broadcast(24)) -- "172.19.37.255"
|
|
print(range:broadcast("255.0.0.0")) -- "172.255.255.255"`
|
|
]]
|
|
|
|
---[[
|
|
Derive mapped IPv4 address of CIDR instance.
|
|
|
|
Constructs a CIDR instance representing the IPv4 address of the IPv6 mapped
|
|
IPv4 address in this instance.
|
|
|
|
This function has no effect on IPv4 instances, MAC address instances or IPv6
|
|
instances which are not a mapped address, it will return nothing in this case.
|
|
|
|
@class function
|
|
@sort 18
|
|
@name cidr.mapped4
|
|
@return Return a new CIDR instance representing the IPv4 address if this
|
|
instance is an IPv6 mapped IPv4 address, else return nothing.
|
|
@usage `local addr = luci.ip.new("::ffff:172.16.19.1")
|
|
print(addr:mapped4()) -- "172.16.19.1"`
|
|
]]
|
|
|
|
---[[
|
|
Derive MAC address of IPv6 link local CIDR instance.
|
|
|
|
Constructs a CIDR instance representing the MAC address contained in the IPv6
|
|
link local address of this instance.
|
|
|
|
This function has no effect on IPv4 instances, MAC address instances or IPv6
|
|
instances which are not a link local address, it will return nothing in this
|
|
case.
|
|
|
|
@class function
|
|
@sort 19
|
|
@name cidr.tomac
|
|
@return Return a new CIDR instance representing the MAC address if this
|
|
instance is an IPv6 link local address, else return nothing.
|
|
@usage `local addr = luci.ip.new("fe80::6666:b3ff:fe47:e1b9")
|
|
print(addr:tomac()) -- "64:66:B3:47:E1:B9"`
|
|
]]
|
|
|
|
---[[
|
|
Derive IPv6 link local address from MAC address CIDR instance.
|
|
|
|
Constructs a CIDR instance representing the IPv6 link local address of the
|
|
MAC address represented by this instance.
|
|
|
|
This function has no effect on IPv4 instances or IPv6 instances, it will return
|
|
nothing in this case.
|
|
|
|
@class function
|
|
@sort 20
|
|
@name cidr.tolinklocal
|
|
@return Return a new CIDR instance representing the IPv6 link local address.
|
|
@usage `local mac = luci.ip.new("64:66:B3:47:E1:B9")
|
|
print(mac:tolinklocal()) -- "fe80::6666:b3ff:fe47:e1b9"`
|
|
]]
|
|
|
|
---[[
|
|
Test whether CIDR contains given range.
|
|
|
|
@class function
|
|
@sort 21
|
|
@name cidr.contains
|
|
@param addr A `luci.ip.cidr` instance or a string convertible by
|
|
`luci.ip.new()` to test.
|
|
@return `true` if this instance fully contains the given address else
|
|
`false`.
|
|
@usage `local range = luci.ip.new("10.24.0.0/255.255.0.0")
|
|
print(range:contains("10.24.5.1")) -- true
|
|
print(range:contains("::1")) -- false
|
|
print(range:contains("10.0.0.0/8")) -- false
|
|
|
|
local range6 = luci.ip.new("fe80::/10")
|
|
print(range6:contains("fe80::221:63f:fe75:aa17/64")) -- true
|
|
print(range6:contains("fd9b:6b3:c5:0:221:63f:fe75:aa17/64")) -- false
|
|
|
|
local intel_macs = luci.ip.MAC("C0:B6:F9:00:00:00/24")
|
|
print(intel_macs:contains("C0:B6:F9:A3:C:11")) -- true
|
|
print(intel_macs:contains("64:66:B3:47:E1:B9")) -- false`
|
|
]]
|
|
|
|
---[[
|
|
Add given amount to CIDR instance. If the result would overflow the maximum
|
|
address space, the result is set to the highest possible address.
|
|
|
|
@class function
|
|
@sort 22
|
|
@name cidr.add
|
|
@param amount A numeric value between 0 and 0xFFFFFFFF, a
|
|
`luci.ip.cidr` instance or a string convertible by
|
|
`luci.ip.new()`.
|
|
@param inplace If `true`, modify this instance instead of returning
|
|
a new derived CIDR instance.
|
|
@return <ul>
|
|
<li>When adding inplace: Return `true` if the addition succeeded
|
|
or `false` when the addition overflowed.</li>
|
|
<li>When deriving new CIDR: Return new instance representing the value of
|
|
this instance plus the added amount or the highest possible address if
|
|
the addition overflowed the available address space.</li></ul>
|
|
@usage `local addr = luci.ip.new("192.168.1.1/24")
|
|
print(addr:add(250)) -- "192.168.1.251/24"
|
|
print(addr:add("0.0.99.0")) -- "192.168.100.1/24"
|
|
|
|
addr:add(256, true) -- true
|
|
print(addr) -- "192.168.2.1/24
|
|
|
|
addr:add("255.0.0.0", true) -- false (overflow)
|
|
print(addr) -- "255.255.255.255/24
|
|
|
|
local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
|
|
print(addr6:add(256)) -- "fe80::221:63f:fe75:ab17/64"
|
|
print(addr6:add("::ffff:0")) -- "fe80::221:640:fe74:aa17/64"
|
|
|
|
addr6:add(256, true) -- true
|
|
print(addr6) -- "fe80::221:63f:fe75:ab17/64
|
|
|
|
addr6:add("ffff::", true) -- false (overflow)
|
|
print(addr6) -- "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/64"
|
|
|
|
local mac = luci.ip.new("00:14:22:01:23:45")
|
|
print(mac:add(256)) -- "00:14:22:01:24:45"
|
|
print(mac:add("0:0:0:0:FF:0") -- "00:14:22:02:22:45"
|
|
|
|
mac:add(256, true) -- true
|
|
print(mac) -- "00:14:22:01:24:45"
|
|
|
|
mac:add("FF:FF:0:0:0:0", true) -- false (overflow)
|
|
print(mac) -- "FF:FF:FF:FF:FF:FF"`
|
|
]]
|
|
|
|
---[[
|
|
Subtract given amount from CIDR instance. If the result would under, the lowest
|
|
possible address is returned.
|
|
|
|
@class function
|
|
@sort 23
|
|
@name cidr.sub
|
|
@param amount A numeric value between 0 and 0xFFFFFFFF, a
|
|
`luci.ip.cidr` instance or a string convertible by
|
|
`luci.ip.new()`.
|
|
@param inplace If `true`, modify this instance instead of returning
|
|
a new derived CIDR instance.
|
|
@return <ul>
|
|
<li>When subtracting inplace: Return `true` if the subtraction
|
|
succeeded or `false` when the subtraction underflowed.</li>
|
|
<li>When deriving new CIDR: Return new instance representing the value of
|
|
this instance minus the subtracted amount or the lowest address if
|
|
the subtraction underflowed.</li></ul>
|
|
@usage `local addr = luci.ip.new("192.168.1.1/24")
|
|
print(addr:sub(256)) -- "192.168.0.1/24"
|
|
print(addr:sub("0.168.0.0")) -- "192.0.1.1/24"
|
|
|
|
addr:sub(256, true) -- true
|
|
print(addr) -- "192.168.0.1/24
|
|
|
|
addr:sub("255.0.0.0", true) -- false (underflow)
|
|
print(addr) -- "0.0.0.0/24
|
|
|
|
local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
|
|
print(addr6:sub(256)) -- "fe80::221:63f:fe75:a917/64"
|
|
print(addr6:sub("::ffff:0")) -- "fe80::221:63e:fe76:aa17/64"
|
|
|
|
addr:sub(256, true) -- true
|
|
print(addr) -- "fe80::221:63f:fe75:a917/64"
|
|
|
|
addr:sub("ffff::", true) -- false (underflow)
|
|
print(addr) -- "::/64"
|
|
|
|
local mac = luci.ip.new("00:14:22:01:23:45")
|
|
print(mac:sub(256)) -- "00:14:22:01:22:45"
|
|
print(mac:sub("0:0:0:0:FF:0") -- "00:14:22:00:24:45"
|
|
|
|
mac:sub(256, true) -- true
|
|
print(mac) -- "00:14:22:01:22:45"
|
|
|
|
mac:sub("FF:FF:0:0:0:0", true) -- false (overflow)
|
|
print(mac) -- "00:00:00:00:00:00"`
|
|
]]
|
|
|
|
---[[
|
|
Calculate the lowest possible host address within this CIDR instance.
|
|
|
|
@class function
|
|
@sort 24
|
|
@name cidr.minhost
|
|
@return Returns a new CIDR instance representing the lowest host address
|
|
within this range.
|
|
@usage `local addr = luci.ip.new("192.168.123.56/24")
|
|
print(addr:minhost()) -- "192.168.123.1"
|
|
|
|
local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
|
|
print(addr6:minhost()) -- "fd9b:62b3:9cc5::1"
|
|
|
|
local mac = luci.ip.new("00:14:22:01:22:45/32")
|
|
print(mac:minhost()) -- "00:14:22:01:00:01"`
|
|
]]
|
|
|
|
---[[
|
|
Calculate the highest possible host address within this CIDR instance.
|
|
|
|
@class function
|
|
@sort 25
|
|
@name cidr.maxhost
|
|
@return Returns a new CIDR instance representing the highest host address
|
|
within this range.
|
|
@usage `local addr = luci.ip.new("192.168.123.56/24")
|
|
print(addr:maxhost()) -- "192.168.123.254" (.255 is broadcast)
|
|
|
|
local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
|
|
print(addr6:maxhost()) -- "fd9b:62b3:9cc5:0:ffff:ffff:ffff:ffff"
|
|
|
|
local mac = luci.ip.new("00:14:22:01:22:45/32")
|
|
print(mac:maxhost()) -- "00:14:22:01:FF:FF"`
|
|
]]
|
|
|
|
---[[
|
|
Convert CIDR instance into string representation.
|
|
|
|
If the prefix size of instance is less than 32 for IPv4, 128 for IPv6 or 48 for
|
|
MACs, the address is returned in the form "address/prefix" otherwise just
|
|
"address".
|
|
|
|
It is usually not required to call this function directly as CIDR objects
|
|
define it as __tostring function in the associated metatable.
|
|
|
|
@class function
|
|
@sort 26
|
|
@name cidr.string
|
|
@return Returns a string representing the range or address of this CIDR instance
|
|
]]
|