From 4f412a76c262acf099678fe97c058f295c749608 Mon Sep 17 00:00:00 2001 From: Jo-Philipp Wich Date: Mon, 12 Mar 2018 08:18:11 +0100 Subject: luci-lib-ip: add MAC address calculation support Signed-off-by: Jo-Philipp Wich --- documentation/api/modules/luci.ip.cidr.html | 330 ++++++++++++++++++++++++---- documentation/api/modules/luci.ip.html | 288 +++++++++++++++++++++++- 2 files changed, 573 insertions(+), 45 deletions(-) (limited to 'documentation/api/modules') diff --git a/documentation/api/modules/luci.ip.cidr.html b/documentation/api/modules/luci.ip.cidr.html index ce8c567952..5a2b06ec67 100644 --- a/documentation/api/modules/luci.ip.cidr.html +++ b/documentation/api/modules/luci.ip.cidr.html @@ -256,6 +256,30 @@ Checks whether the CIDR instance is an IPv6 link local address Checks whether the CIDR instance is an IPv6 mapped IPv4 address + + + + + cidr:ismac () + + +Checks whether the CIDR instance is an ethernet MAC address range + + + + + cidr:ismaclocal () + + +Checks whether the CIDR instance is a locally administered (LAA) MAC address + + + + + cidr:ismacmcast () + + +Checks whether the CIDR instance is a multicast MAC address @@ -322,6 +346,20 @@ Derive broadcast address of CIDR instance. Derive mapped IPv4 address of CIDR instance. + + cidr:tomac () + + +Derive MAC address of IPv6 link local CIDR instance. + + + + cidr:tolinklocal () + + +Derive IPv6 link local address from MAC address CIDR instance. + + cidr:contains (addr) @@ -405,6 +443,10 @@ Checks whether the CIDR instance is an IPv4 address range cidr:is6 +
  • + cidr:ismac + + @@ -499,6 +541,10 @@ Checks whether the CIDR instance is an IPv6 address range cidr:is4 +
  • + cidr:ismac + + @@ -566,13 +612,108 @@ end +
    cidr:ismac ()
    +
    + + +Checks whether the CIDR instance is an ethernet MAC address range + + + + + + + + +

    Return value:

    +true if the CIDR is a MAC address range, else false + + + +

    See also:

    + + +
    + + + + +
    cidr:ismaclocal ()
    +
    + + +Checks whether the CIDR instance is a locally administered (LAA) MAC address + + + + + + +

    Usage:

    +
    local mac = luci.ip.new("02:C0:FF:EE:00:01") 
+if mac:ismaclocal() then 
+  print("Is an LAA MAC address") 
+end
    + + + +

    Return value:

    +true if the MAC address sets the locally administered bit. + + + +
    + + + + +
    cidr:ismacmcast ()
    +
    + + +Checks whether the CIDR instance is a multicast MAC address + + + + + + +

    Usage:

    +
    local mac = luci.ip.new("01:00:5E:7F:00:10") 
+if addr:ismacmcast() then 
+  print("Is a multicast MAC address") 
+end
    + + + +

    Return value:

    +true if the MAC address sets the multicast bit. + + + +
    + + + +
    cidr:lower (addr)
    Checks whether this CIDR instance is lower than the given argument. The comparisation follows these rules: -
    • An IPv4 address is always lower than an IPv6 address
      • +
      • An IPv4 address is always lower than an IPv6 address and IPv6 addresses +are considered lower than MAC addresses
      • Prefix sizes are ignored
      @@ -595,7 +736,8 @@ The comparisation follows these rules: 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("192.168.200.1"))) -- true +print(addr:lower(luci.ip.new("00:14:22:01:23:45"))) -- true @@ -629,7 +771,8 @@ print(addr:lower(luci.ip.new("192.168.200.1"))) -- true Checks whether this CIDR instance is higher than the given argument. The comparisation follows these rules: -
      • An IPv4 address is always lower than an IPv6 address
        • +
        • An IPv4 address is always lower than an IPv6 address and IPv6 addresses +are considered lower than MAC addresses
        • Prefix sizes are ignored
        @@ -652,7 +795,8 @@ The comparisation follows these rules: 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("192.168.200.1"))) -- false +print(addr:higher(luci.ip.new("00:14:22:01:23:45"))) -- false @@ -709,7 +853,11 @@ 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 +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 @@ -752,8 +900,8 @@ else the current prefix size is returned.
      • 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) + for IPv4, 0..128 for IPv6 or 0..48 for MAC addresses) or a string + containing a valid netmask (optional)
      @@ -800,8 +948,8 @@ optional mask parameter.
    • 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) + for IPv4, 0..128 for IPv6 or 0..48 for MAC addresses) or a string + containing a valid netmask (optional)
    @@ -837,7 +985,7 @@ CIDR instance representing the network address 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. +set to 32 for IPv4, 128 for IPv6 or 48 for MAC addresses. @@ -877,8 +1025,8 @@ prefix size can be overridden by the optional mask parameter.
  • 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) + for IPv4, 0..128 for IPv6 or 0..48 for MAC addresses) or a string + containing a valid netmask (optional)
    • @@ -913,8 +1061,8 @@ 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. +This function has no effect on IPv6 or MAC address instances, it will return +nothing in this case. @@ -922,9 +1070,8 @@ case.
    • - 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) + mask: Either a number containing the number of bits (0..32 for IPv4) or + a string containing a valid netmask (optional)
    @@ -960,8 +1107,8 @@ 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. +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. @@ -985,6 +1132,74 @@ Return a new CIDR instance representing the IPv4 address if this +
    cidr:tomac ()
    +
    + + +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. + + + + + + +

    Usage:

    +
    local addr = luci.ip.new("fe80::6666:b3ff:fe47:e1b9") 
+print(addr:tomac()) -- "64:66:B3:47:E1:B9"
    + + + +

    Return value:

    +Return a new CIDR instance representing the MAC address if this + instance is an IPv6 link local address, else return nothing. + + + +
    + + + + +
    cidr:tolinklocal ()
    +
    + + +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. + + + + + + +

    Usage:

    +
    local mac = luci.ip.new("64:66:B3:47:E1:B9") 
+print(mac:tolinklocal()) -- "fe80::6666:b3ff:fe47:e1b9"
    + + + +

    Return value:

    +Return a new CIDR instance representing the IPv6 link local address. + + + +
    + + + +
    cidr:contains (addr)
    @@ -1014,7 +1229,11 @@ 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 +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 @@ -1059,30 +1278,40 @@ address space, the result is set to the highest possible address.

    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" 
+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(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 
+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" 
+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" 
  
-addr:add(256, true)          -- true 
-print(addr)                  -- "fe80::221:63f:fe75:ab17/64 
+mac:add(256, true)             -- true 
+print(mac)                     -- "00:14:22:01:24:45" 
  
-addr:add("ffff::", true)     -- false (overflow) 
-print(addr)                  -- "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/64"
    +mac:add("FF:FF:0:0:0:0", true) -- false (overflow) +print(mac) -- "FF:FF:FF:FF:FF:FF"

    Return value:

      -
    • When adding inplace: Return true if the addition succeeded +
    • When adding inplace: Return true if the addition succeded or false when the addition overflowed.
    • When deriving new CIDR: Return new instance representing the value of this instance plus the added amount or the highest possible address if @@ -1099,7 +1328,7 @@ print(addr) -- "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/64" -Subtract given amount from CIDR instance. If the result would under, the lowest +Subtract given amount from CIDR instance. If the result would under, the lowest possible address is returned. @@ -1142,16 +1371,26 @@ addr:sub(256, true) -- true print(addr) -- "fe80::221:63f:fe75:a917/64" addr:sub("ffff::", true) -- false (underflow) -print(addr) -- "::/64" +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"

      Return value:

        -
      • When subtracting inplace: Return true if the subtraction - succeeded or false when the subtraction underflowed.
        • +
      • When subtracting inplace: Return true if the subtraction + succeeded or false when the subtraction underflowed.
      • When deriving new CIDR: Return new instance representing the value of - this instance minus the subtracted amount or the lowest address if + this instance minus the subtracted amount or the lowest address if the subtraction underflowed.
      @@ -1177,7 +1416,10 @@ Calculate the lowest possible host address within this CIDR instance. 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" +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" @@ -1208,7 +1450,10 @@ Calculate the highest possible host address within this CIDR instance. 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" +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" @@ -1229,8 +1474,9 @@ Returns a new CIDR instance representing the highest host address 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". +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. diff --git a/documentation/api/modules/luci.ip.html b/documentation/api/modules/luci.ip.html index 549a55307e..1f89626faa 100644 --- a/documentation/api/modules/luci.ip.html +++ b/documentation/api/modules/luci.ip.html @@ -231,6 +231,34 @@ Construct a new IPv4 luci.ip.cidr instance. 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) @@ -334,6 +362,10 @@ address/mask range. IPv6 +
    • + MAC + +
    @@ -389,6 +421,10 @@ A luci.ip.cidr object representing the given IPv4 range. IPv6 +
  • + MAC + + @@ -444,6 +480,252 @@ A luci.ip.cidr object representing the given IPv6 range. IPv4 +
  • + MAC + + + + + + + + + +
    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 0 and 48 bit. +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 mask
    + + + +

    Return value:

    +A luci.ip.cidr object 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()                          -- nothing
    + + + +

    Return 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()                                -- nothing
    + + + +

    Return 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()                                  -- nothing
    + + + +

    Return value:

    +A string representing the given MAC address. + + + +

    See also:

    +
    @@ -787,7 +1069,7 @@ A neighbour entry is a table containing the following fields: mac - String containing the associated MAC address + MAC address luci.ip.cidr instance router @@ -905,8 +1187,8 @@ described below is returned, else an empty table. mac - String containing the link local address of the device in - dotted hex notation + MAC address luci.ip.cidr instance representing the device ethernet + address -- cgit v1.2.3