node_modules/ipaddr.js/README.md

   1 # ipaddr.js — an IPv6 and IPv4 address manipulation library [![Build Status](https://travis-ci.org/whitequark/ipaddr.js.svg)](https://travis-ci.org/whitequark/ipaddr.js)
   2
   3 ipaddr.js is a small (1.9K minified and gzipped) library for manipulating
   4 IP addresses in JavaScript environments. It runs on both CommonJS runtimes
   5 (e.g. [nodejs]) and in a web browser.
   6
   7 ipaddr.js allows you to verify and parse string representation of an IP
   8 address, match it against a CIDR range or range list, determine if it falls
   9 into some reserved ranges (examples include loopback and private ranges),
  10 and convert between IPv4 and IPv4-mapped IPv6 addresses.
  11
  12 [nodejs]: http://nodejs.org
  13
  14 ## Installation
  15
  16 `npm install ipaddr.js`
  17
  18 or
  19
  20 `bower install ipaddr.js`
  21
  22 ## API
  23
  24 ipaddr.js defines one object in the global scope: `ipaddr`. In CommonJS,
  25 it is exported from the module:
  26
  27 ```js
  28 var ipaddr = require('ipaddr.js');
  29 ```
  30
  31 The API consists of several global methods and two classes: ipaddr.IPv6 and ipaddr.IPv4.
  32
  33 ### Global methods
  34
  35 There are three global methods defined: `ipaddr.isValid`, `ipaddr.parse` and
  36 `ipaddr.process`. All of them receive a string as a single parameter.
  37
  38 The `ipaddr.isValid` method returns `true` if the address is a valid IPv4 or
  39 IPv6 address, and `false` otherwise. It does not throw any exceptions.
  40
  41 The `ipaddr.parse` method returns an object representing the IP address,
  42 or throws an `Error` if the passed string is not a valid representation of an
  43 IP address.
  44
  45 The `ipaddr.process` method works just like the `ipaddr.parse` one, but it
  46 automatically converts IPv4-mapped IPv6 addresses to their IPv4 counterparts
  47 before returning. It is useful when you have a Node.js instance listening
  48 on an IPv6 socket, and the `net.ivp6.bindv6only` sysctl parameter (or its
  49 equivalent on non-Linux OS) is set to 0. In this case, you can accept IPv4
  50 connections on your IPv6-only socket, but the remote address will be mangled.
  51 Use `ipaddr.process` method to automatically demangle it.
  52
  53 ### Object representation
  54
  55 Parsing methods return an object which descends from `ipaddr.IPv6` or
  56 `ipaddr.IPv4`. These objects share some properties, but most of them differ.
  57
  58 #### Shared properties
  59
  60 One can determine the type of address by calling `addr.kind()`. It will return
  61 either `"ipv6"` or `"ipv4"`.
  62
  63 An address can be converted back to its string representation with `addr.toString()`.
  64 Note that this method:
  65  * does not return the original string used to create the object (in fact, there is
  66    no way of getting that string)
  67  * returns a compact representation (when it is applicable)
  68
  69 A `match(range, bits)` method can be used to check if the address falls into a
  70 certain CIDR range.
  71 Note that an address can be (obviously) matched only against an address of the same type.
  72
  73 For example:
  74
  75 ```js
  76 var addr = ipaddr.parse("2001:db8:1234::1");
  77 var range = ipaddr.parse("2001:db8::");
  78
  79 addr.match(range, 32); // => true
  80 ```
  81
  82 Alternatively, `match` can also be called as `match([range, bits])`. In this way,
  83 it can be used together with the `parseCIDR(string)` method, which parses an IP
  84 address together with a CIDR range.
  85
  86 For example:
  87
  88 ```js
  89 var addr = ipaddr.parse("2001:db8:1234::1");
  90
  91 addr.match(ipaddr.parseCIDR("2001:db8::/32")); // => true
  92 ```
  93
  94 A `range()` method returns one of predefined names for several special ranges defined
  95 by IP protocols. The exact names (and their respective CIDR ranges) can be looked up
  96 in the source: [IPv6 ranges] and [IPv4 ranges]. Some common ones include `"unicast"`
  97 (the default one) and `"reserved"`.
  98
  99 You can match against your own range list by using
 100 `ipaddr.subnetMatch(address, rangeList, defaultName)` method. It can work with a mix of IPv6 or IPv4 addresses, and accepts a name-to-subnet map as the range list. For example:
 101
 102 ```js
 103 var rangeList = {
 104   documentationOnly: [ ipaddr.parse('2001:db8::'), 32 ],
 105   tunnelProviders: [
 106     [ ipaddr.parse('2001:470::'), 32 ], // he.net
 107     [ ipaddr.parse('2001:5c0::'), 32 ]  // freenet6
 108   ]
 109 };
 110 ipaddr.subnetMatch(ipaddr.parse('2001:470:8:66::1'), rangeList, 'unknown'); // => "tunnelProviders"
 111 ```
 112
 113 The addresses can be converted to their byte representation with `toByteArray()`.
 114 (Actually, JavaScript mostly does not know about byte buffers. They are emulated with
 115 arrays of numbers, each in range of 0..255.)
 116
 117 ```js
 118 var bytes = ipaddr.parse('2a00:1450:8007::68').toByteArray(); // ipv6.google.com
 119 bytes // => [42, 0x00, 0x14, 0x50, 0x80, 0x07, 0x00, <zeroes...>, 0x00, 0x68 ]
 120 ```
 121
 122 The `ipaddr.IPv4` and `ipaddr.IPv6` objects have some methods defined, too. All of them
 123 have the same interface for both protocols, and are similar to global methods.
 124
 125 `ipaddr.IPvX.isValid(string)` can be used to check if the string is a valid address
 126 for particular protocol, and `ipaddr.IPvX.parse(string)` is the error-throwing parser.
 127
 128 `ipaddr.IPvX.isValid(string)` uses the same format for parsing as the POSIX `inet_ntoa` function, which accepts unusual formats like `0xc0.168.1.1` or `0x10000000`. The function `ipaddr.IPv4.isValidFourPartDecimal(string)` validates the IPv4 address and also ensures that it is written in four-part decimal format.
 129
 130 [IPv6 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L186
 131 [IPv4 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L71
 132
 133 #### IPv6 properties
 134
 135 Sometimes you will want to convert IPv6 not to a compact string representation (with
 136 the `::` substitution); the `toNormalizedString()` method will return an address where
 137 all zeroes are explicit.
 138
 139 For example:
 140
 141 ```js
 142 var addr = ipaddr.parse("2001:0db8::0001");
 143 addr.toString(); // => "2001:db8::1"
 144 addr.toNormalizedString(); // => "2001:db8:0:0:0:0:0:1"
 145 ```
 146
 147 The `isIPv4MappedAddress()` method will return `true` if this address is an IPv4-mapped
 148 one, and `toIPv4Address()` will return an IPv4 object address.
 149
 150 To access the underlying binary representation of the address, use `addr.parts`.
 151
 152 ```js
 153 var addr = ipaddr.parse("2001:db8:10::1234:DEAD");
 154 addr.parts // => [0x2001, 0xdb8, 0x10, 0, 0, 0, 0x1234, 0xdead]
 155 ```
 156
 157 A IPv6 zone index can be accessed via `addr.zoneId`:
 158
 159 ```js
 160 var addr = ipaddr.parse("2001:db8::%eth0");
 161 addr.zoneId // => 'eth0'
 162 ```
 163
 164 #### IPv4 properties
 165
 166 `toIPv4MappedAddress()` will return a corresponding IPv4-mapped IPv6 address.
 167
 168 To access the underlying representation of the address, use `addr.octets`.
 169
 170 ```js
 171 var addr = ipaddr.parse("192.168.1.1");
 172 addr.octets // => [192, 168, 1, 1]
 173 ```
 174
 175 `prefixLengthFromSubnetMask()` will return a CIDR prefix length for a valid IPv4 netmask or
 176 null if the netmask is not valid.
 177
 178 ```js
 179 ipaddr.IPv4.parse('255.255.255.240').prefixLengthFromSubnetMask() == 28
 180 ipaddr.IPv4.parse('255.192.164.0').prefixLengthFromSubnetMask()  == null
 181 ```
 182
 183 `subnetMaskFromPrefixLength()` will return an IPv4 netmask for a valid CIDR prefix length.
 184
 185 ```js
 186 ipaddr.IPv4.subnetMaskFromPrefixLength(24) == "255.255.255.0"
 187 ipaddr.IPv4.subnetMaskFromPrefixLength(29) == "255.255.255.248"
 188 ```
 189
 190 `broadcastAddressFromCIDR()` will return the broadcast address for a given IPv4 interface and netmask in CIDR notation.
 191 ```js
 192 ipaddr.IPv4.broadcastAddressFromCIDR("172.0.0.1/24") == "172.0.0.255"
 193 ```
 194 `networkAddressFromCIDR()` will return the network address for a given IPv4 interface and netmask in CIDR notation.
 195 ```js
 196 ipaddr.IPv4.networkAddressFromCIDR("172.0.0.1/24") == "172.0.0.0"
 197 ```
 198
 199 #### Conversion
 200
 201 IPv4 and IPv6 can be converted bidirectionally to and from network byte order (MSB) byte arrays.
 202
 203 The `fromByteArray()` method will take an array and create an appropriate IPv4 or IPv6 object
 204 if the input satisfies the requirements. For IPv4 it has to be an array of four 8-bit values,
 205 while for IPv6 it has to be an array of sixteen 8-bit values.
 206
 207 For example:
 208 ```js
 209 var addr = ipaddr.fromByteArray([0x7f, 0, 0, 1]);
 210 addr.toString(); // => "127.0.0.1"
 211 ```
 212
 213 or
 214
 215 ```js
 216 var addr = ipaddr.fromByteArray([0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1])
 217 addr.toString(); // => "2001:db8::1"
 218 ```
 219
 220 Both objects also offer a `toByteArray()` method, which returns an array in network byte order (MSB).
 221
 222 For example:
 223 ```js
 224 var addr = ipaddr.parse("127.0.0.1");
 225 addr.toByteArray(); // => [0x7f, 0, 0, 1]
 226 ```
 227
 228 or
 229
 230 ```js
 231 var addr = ipaddr.parse("2001:db8::1");
 232 addr.toByteArray(); // => [0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
 233 ```