luci-lib-ip: add api documentation
Signed-off-by: Jo-Philipp Wich <jow@openwrt.org>
This commit is contained in:
Jo-Philipp Wich
parent
fb69e15e8d
commit
7ca5222f4b
1 changed files with 831 additions and 0 deletions
831
libs/luci-lib-ip/src/ip.luadoc
Normal file
831
libs/luci-lib-ip/src/ip.luadoc
Normal file
|
|
@ -0,0 +1,831 @@
|
|||
--- 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
|
||||
]]
|
||||
|
||||
---[[
|
||||
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.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`
|
||||
@see IPv6
|
||||
]]
|
||||
|
||||
---[[
|
||||
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.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
|
||||
]]
|
||||
|
||||
---[[
|
||||
Determine the route leading to the given destination.
|
||||
@class function
|
||||
@sort 4
|
||||
@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 5
|
||||
@name routes
|
||||
@param filter <p>Table containing one or more of the possible filter
|
||||
critera 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 6
|
||||
@name neighbors
|
||||
@param filter <p>Table containing one or more of the possible filter
|
||||
critera 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>String containing the associated MAC address</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 7
|
||||
@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>String containing the link local address of the device in
|
||||
dotted hex notation</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
|
||||
@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
|
||||
@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 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</li>
|
||||
<li>Prefix sizes are ignored</li></ul>
|
||||
|
||||
@class function
|
||||
@sort 7
|
||||
@name cidr.lower
|
||||
@param addr A `luci.ip.cidr` instance or a string convertable 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`
|
||||
@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</li>
|
||||
<li>Prefix sizes are ignored</li></ul>
|
||||
|
||||
@class function
|
||||
@sort 8
|
||||
@name cidr.higher
|
||||
@param addr A `luci.ip.cidr` instance or a string convertable 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`
|
||||
@see cidr.lower
|
||||
@see cidr.equal
|
||||
]]
|
||||
|
||||
---[[
|
||||
Checks whether this CIDR instance is equal to the given argument.
|
||||
|
||||
@class function
|
||||
@sort 9
|
||||
@name cidr.equal
|
||||
@param addr A `luci.ip.cidr` instance or a string convertable 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`
|
||||
@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 10
|
||||
@name cidr.prefix
|
||||
@param mask Either a number containing the number of bits (`0..32`
|
||||
for IPv4, `0..128` for IPv6) 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 11
|
||||
@name cidr.network
|
||||
@param mask Either a number containing the number of bits (`0..32`
|
||||
for IPv4, `0..128` for IPv6) 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 and `128` for IPv6.
|
||||
|
||||
@class function
|
||||
@sort 12
|
||||
@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 13
|
||||
@name cidr.mask
|
||||
@param mask Either a number containing the number of bits (`0..32`
|
||||
for IPv4, `0..128` for IPv6) 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 instances, it will return nothing in this
|
||||
case.
|
||||
|
||||
@class function
|
||||
@sort 14
|
||||
@name cidr.broadcast
|
||||
@param mask Either a number containing the number of bits (`0..32`
|
||||
for IPv4, `0..128` for IPv6) 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 or IPv6 instances which are not a
|
||||
mapped address, it will return nothing in this case.
|
||||
|
||||
@class function
|
||||
@sort 15
|
||||
@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"`
|
||||
]]
|
||||
|
||||
---[[
|
||||
Test whether CIDR contains given range.
|
||||
|
||||
@class function
|
||||
@sort 16
|
||||
@name cidr.contains
|
||||
@param addr A `luci.ip.cidr` instance or a string convertable 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`
|
||||
]]
|
||||
|
||||
---[[
|
||||
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 17
|
||||
@name cidr.add
|
||||
@param amount A numeric value between 0 and 0xFFFFFFFF, a
|
||||
`luci.ip.cidr` instance or a string convertable 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 succeded
|
||||
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"
|
||||
|
||||
addr:add(256, true) -- true
|
||||
print(addr) -- "fe80::221:63f:fe75:ab17/64
|
||||
|
||||
addr:add("ffff::", true) -- false (overflow)
|
||||
print(addr) -- "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/64"`
|
||||
]]
|
||||
|
||||
---[[
|
||||
Substract given amount from CIDR instance. If the result would under, the lowest
|
||||
possible address is returned.
|
||||
|
||||
@class function
|
||||
@sort 18
|
||||
@name cidr.sub
|
||||
@param amount A numeric value between 0 and 0xFFFFFFFF, a
|
||||
`luci.ip.cidr` instance or a string convertable by
|
||||
`luci.ip.new()`.
|
||||
@param inplace If `true`, modify this instance instead of returning
|
||||
a new derived CIDR instance.
|
||||
@return <ul>
|
||||
<li>When substracting inplace: Return `true` if the substraction
|
||||
succeded or `false` when the substraction underflowed.</li>
|
||||
<li>When deriving new CIDR: Return new instance representing the value of
|
||||
this instance minus the substracted amount or the lowest address if
|
||||
the substraction 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"`
|
||||
]]
|
||||
|
||||
---[[
|
||||
Calculate the lowest possible host address within this CIDR instance.
|
||||
|
||||
@class function
|
||||
@sort 19
|
||||
@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"`
|
||||
]]
|
||||
|
||||
---[[
|
||||
Calculate the highest possible host address within this CIDR instance.
|
||||
|
||||
@class function
|
||||
@sort 20
|
||||
@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"`
|
||||
]]
|
||||
|
||||
---[[
|
||||
Convert CIDR instance into string representation.
|
||||
|
||||
If the prefix size of instance is less than 32 for IPv4 or 128 for IPv6, 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 21
|
||||
@name cidr.string
|
||||
@return Returns a string representing the range or address of this CIDR instance
|
||||
]]
|
||||
Loading…
Reference in a new issue