From 7ca5222f4bd7a91ce58cc595f6082623045ebb22 Mon Sep 17 00:00:00 2001 From: Jo-Philipp Wich Date: Wed, 28 Jan 2015 22:31:14 +0100 Subject: [PATCH] luci-lib-ip: add api documentation Signed-off-by: Jo-Philipp Wich --- libs/luci-lib-ip/src/ip.luadoc | 831 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 831 insertions(+) create mode 100644 libs/luci-lib-ip/src/ip.luadoc diff --git a/libs/luci-lib-ip/src/ip.luadoc b/libs/luci-lib-ip/src/ip.luadoc new file mode 100644 index 000000000..00738832c --- /dev/null +++ b/libs/luci-lib-ip/src/ip.luadoc @@ -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

Table containing the fields described below.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
`type` +

Route type with one of the following numeric values:

+ + + + + + + + + + + + + + + + + + + + + +
`1``RTN_UNICAST` - Gateway or direct route
`2``RTN_LOCAL` - Accept locally
`3``RTN_BROADCAST` - + Accept locally as broadcast send as broadcast
`4``RTN_ANYCAST` - + Accept locally as broadcast but send as unicast
`5``RTN_MULTICAST` - Multicast route
+
`family`Number containing the route family, `4` for IPv4 or + `6` for IPv6
`dest`Destination `luci.ip.cidr` instance
`gw`Gateway `luci.ip.cidr` instance (optional)
`from`Source address `luci.ip.cidr` instance (optional)
`src`Preferred source `luci.ip.cidr` instance (optional)
`dev`String containing the name of the outgoing interface
`iif`String containing the name of the incoming interface (optional)
`table`Number of the associated routing table (`0..65535`)
`proto`Number of the associated routing protocol
`scope`Number describing the scope of the route, most commonly + `0` for global or `253` for on-link
`metric`Number describing the route metric (optional)
`expires`Number of seconds the prefix is valid (IPv6 only, optional)
`error`Route destination error code (optional)
+@usage +@see routes +]] + +---[[ +Fetch all routes, optionally matching the given criteria. +@class function +@sort 5 +@name routes +@param filter

Table containing one or more of the possible filter +critera described below (optional)

+ + + + + + + + + + + + + + +
FieldDescription
`family` + Number describing the address family to return - `4` selects + IPv4 routes, `6` IPv6 ones. Any other value selects both. +
`iif` + String containing the incoming route interface to match. +
`oif` + String containing the outgoing route interface to match. +
`type` + Numeric type to match, e.g. `1` for unicast. +
`scope` + Numeric scope to match, e.g. `253` for onlink. +
`proto` + Numeric protocol to match, e.g. `2` for boot. +
`table` + Numeric routing table to match (`0..65535`). +
`gw` + 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`. +
`dest` + String containing the destination to match. Prefix matching is performed. +
`from` + String containing the source address to match. Prefix matching is performed. +
`src` + String containing the preferred source address to match. + Prefix matching is performed. +
`dest_exact` + String containing the destination to match. Exact matching is performed, + e.g. `dest = "0.0.0.0/0"` would match any IPv4 route + while `dest_exact = "0.0.0.0/0"` will only match the + default route. +
`from_exact` + String containing the source address to match. Exact matching is performed. +
+@param callback

Callback function to invoke for each found route +instead of returning one table of route objects (optional)

+@return If no callback function is provided, a table of routes +as specified by `luci.ip.route()` +is returned. If a callback function is given, it is invoked for each route +and nothing is returned. +@see route +@usage +]] + +---[[ +Fetches entries from the IPv4 ARP and IPv6 neighbour kernel table +@class function +@sort 6 +@name neighbors +@param filter

Table containing one or more of the possible filter +critera described below (optional)

+ + + + + +
FieldDescription
`family` + Number describing the address family to return - `4` selects + IPv4 ARP, `6` select IPv6 neighbour entries. Any other value + selects both. +
`dev` + String containing the associated interface to match. +
`dest` + 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`. +
`mac` + String containing MAC address to match. +
+@param callback

Callback function to invoke for each found neighbour +entry instead of returning one table of neighbour entries (optional)

+@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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
`family`Number containing the neighbour entry family, `4` for IPv4 + ARP or `6` for IPv6 NDP
`dev`String containing the associated device of the neighbour entry
`dest`IP address `luci.ip.cidr` instance
`mac`String containing the associated MAC address
`router`Boolean "true" if the neighbour entry is a router (IPv6, optional)
`proxy`Boolean "true" if this is a proxy entry (optional)
`incomplete`Boolean "true" if the entry is in incomplete state (optional)
`reachable`Boolean "true" if the entry is in reachable state (optional)
`stale`Boolean "true" if the entry is stale (optional)
`delay`Boolean "true" if the entry is delayed (optional)
`probe`Boolean "true" if the entry is in probe state (optional)
`failed`Boolean "true" if the entry is in failed state (optional)
`noarp`Boolean "true" if the entry is not caused by NDP or + ARP (optional)
`permanent`Boolean "true" if the entry was statically configured from + userspace (optional)
+@usage +]] + +---[[ +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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
`up`Boolean indicating whether the device is in IFF_RUNNING state
`type`Numeric value indicating the type of the device, e.g. `1` + for ethernet.
`name`String containing the name of the device
`master`If queried device is a bridge port, string containing the name of + parent bridge device (optional)
`mtu`Number containing the current MTU of the device
`qlen`Number containing the TX queue length of the device
`mac`String containing the link local address of the device in + dotted hex notation
+@usage +]] + + +--- 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: + + +@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: + + +@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 +@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 +@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 +]] -- 2.11.0