ipaddress 0.2.3 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/{crunchy.d.ts → dist/src/crunchy.d.ts} +1 -0
  2. package/dist/src/crunchy.d.ts.map +1 -0
  3. package/dist/src/crunchy.js +484 -0
  4. package/dist/src/index.d.ts +13 -0
  5. package/dist/src/index.d.ts.map +1 -0
  6. package/dist/src/index.js +21 -0
  7. package/{ip_bits.d.ts → dist/src/ip_bits.d.ts} +6 -5
  8. package/dist/src/ip_bits.d.ts.map +1 -0
  9. package/dist/src/ip_bits.js +133 -0
  10. package/{ip_version.d.ts → dist/src/ip_version.d.ts} +2 -1
  11. package/dist/src/ip_version.d.ts.map +1 -0
  12. package/dist/src/ip_version.js +6 -0
  13. package/{ipaddress.d.ts → dist/src/ipaddress.d.ts} +18 -16
  14. package/dist/src/ipaddress.d.ts.map +1 -0
  15. package/dist/src/ipaddress.js +1228 -0
  16. package/dist/src/ipv4.d.ts +15 -0
  17. package/dist/src/ipv4.d.ts.map +1 -0
  18. package/dist/src/ipv4.js +176 -0
  19. package/dist/src/ipv6.d.ts +13 -0
  20. package/dist/src/ipv6.d.ts.map +1 -0
  21. package/dist/src/ipv6.js +190 -0
  22. package/dist/src/ipv6_loopback.d.ts +6 -0
  23. package/dist/src/ipv6_loopback.d.ts.map +1 -0
  24. package/dist/src/ipv6_loopback.js +51 -0
  25. package/dist/src/ipv6_mapped.d.ts +6 -0
  26. package/dist/src/ipv6_mapped.d.ts.map +1 -0
  27. package/dist/src/ipv6_mapped.js +159 -0
  28. package/dist/src/ipv6_unspec.d.ts +6 -0
  29. package/dist/src/ipv6_unspec.d.ts.map +1 -0
  30. package/dist/src/ipv6_unspec.js +57 -0
  31. package/{prefix.d.ts → dist/src/prefix.d.ts} +10 -7
  32. package/dist/src/prefix.d.ts.map +1 -0
  33. package/dist/src/prefix.js +142 -0
  34. package/dist/src/prefix128.d.ts +7 -0
  35. package/dist/src/prefix128.d.ts.map +1 -0
  36. package/dist/src/prefix128.js +35 -0
  37. package/dist/src/prefix32.d.ts +7 -0
  38. package/dist/src/prefix32.d.ts.map +1 -0
  39. package/dist/src/prefix32.js +25 -0
  40. package/dist/src/rle.d.ts +19 -0
  41. package/dist/src/rle.d.ts.map +1 -0
  42. package/dist/src/rle.js +73 -0
  43. package/dist/test/test_crunchy.d.ts +2 -0
  44. package/dist/test/test_crunchy.d.ts.map +1 -0
  45. package/dist/test/test_crunchy.js +451 -0
  46. package/dist/test/test_ipaddress.d.ts +2 -0
  47. package/dist/test/test_ipaddress.d.ts.map +1 -0
  48. package/dist/test/test_ipaddress.js +182 -0
  49. package/dist/test/test_ipv4.d.ts +2 -0
  50. package/dist/test/test_ipv4.d.ts.map +1 -0
  51. package/dist/test/test_ipv4.js +561 -0
  52. package/dist/test/test_ipv6.d.ts +2 -0
  53. package/dist/test/test_ipv6.d.ts.map +1 -0
  54. package/dist/test/test_ipv6.js +313 -0
  55. package/dist/test/test_ipv6_loopback.d.ts +2 -0
  56. package/dist/test/test_ipv6_loopback.d.ts.map +1 -0
  57. package/dist/test/test_ipv6_loopback.js +40 -0
  58. package/dist/test/test_ipv6_mapped.d.ts +2 -0
  59. package/dist/test/test_ipv6_mapped.d.ts.map +1 -0
  60. package/dist/test/test_ipv6_mapped.js +89 -0
  61. package/dist/test/test_ipv6_unspec.d.ts +2 -0
  62. package/dist/test/test_ipv6_unspec.d.ts.map +1 -0
  63. package/dist/test/test_ipv6_unspec.js +39 -0
  64. package/dist/test/test_prefix128.d.ts +2 -0
  65. package/dist/test/test_prefix128.d.ts.map +1 -0
  66. package/dist/test/test_prefix128.js +35 -0
  67. package/dist/test/test_prefix32.d.ts +2 -0
  68. package/dist/test/test_prefix32.d.ts.map +1 -0
  69. package/dist/test/test_prefix32.js +126 -0
  70. package/dist/test/test_rle.d.ts +2 -0
  71. package/dist/test/test_rle.d.ts.map +1 -0
  72. package/dist/test/test_rle.js +141 -0
  73. package/dist/vitest.config.d.ts +3 -0
  74. package/dist/vitest.config.d.ts.map +1 -0
  75. package/dist/vitest.config.js +11 -0
  76. package/package.json +40 -37
  77. package/src/crunchy.ts +546 -0
  78. package/src/index.ts +23 -0
  79. package/src/ip_bits.ts +148 -0
  80. package/src/ip_version.ts +6 -0
  81. package/src/ipaddress.ts +1331 -0
  82. package/src/ipv4.ts +190 -0
  83. package/src/ipv6.ts +202 -0
  84. package/src/ipv6_loopback.ts +55 -0
  85. package/src/ipv6_mapped.ts +163 -0
  86. package/src/ipv6_unspec.ts +59 -0
  87. package/src/prefix.ts +170 -0
  88. package/src/prefix128.ts +38 -0
  89. package/src/prefix32.ts +28 -0
  90. package/src/rle.ts +85 -0
  91. package/test/test_crunchy.ts +614 -0
  92. package/test/test_ipaddress.ts +208 -0
  93. package/test/test_ipv4.ts +596 -0
  94. package/test/test_ipv6.ts +325 -0
  95. package/test/test_ipv6_loopback.ts +52 -0
  96. package/test/test_ipv6_mapped.ts +101 -0
  97. package/test/test_ipv6_unspec.ts +51 -0
  98. package/test/test_prefix128.ts +39 -0
  99. package/test/test_prefix32.ts +130 -0
  100. package/test/test_rle.ts +144 -0
  101. package/LICENSE +0 -20
  102. package/README.md +0 -956
  103. package/index.d.ts +0 -12
  104. package/ipaddress.js +0 -2854
  105. package/ipaddress.js.map +0 -1
  106. package/ipv4.d.ts +0 -14
  107. package/ipv6.d.ts +0 -12
  108. package/ipv6_loopback.d.ts +0 -5
  109. package/ipv6_mapped.d.ts +0 -5
  110. package/ipv6_unspec.d.ts +0 -5
  111. package/prefix128.d.ts +0 -6
  112. package/prefix32.d.ts +0 -6
  113. package/rle.d.ts +0 -14
package/README.md DELETED
@@ -1,956 +0,0 @@
1
-
2
- [![Build Status](https://travis-ci.org/mabels/ipaddress.svg?branch=master)](https://travis-ci.org/mabels/ipaddress)
3
- [![npm](https://img.shields.io/npm/v/ipaddress.svg)](https://www.npmjs.com/package/ipaddress)
4
-
5
- = IPAddress
6
-
7
- IPAddress is a library designed to make the use of IPv4 and IPv6
8
- addresses simple, powerful and enjoyable. It provides a complete set of
9
- methods to handle IP addresses for any need, from simple scripting to
10
- full network design.
11
-
12
- IPAddress should have the same api for:
13
- - ruby (the root implementation, it's not updated after the port to rust)
14
- - rust
15
- - javascript/typescript
16
- The documentation is in ruby and hopefully in rust. There should
17
- be examples writen in ruby in.
18
-
19
- The Function naming could be odd non CamelCase in the javascript out
20
- of the fact that it is grown from ruby/rust which both does not like
21
- CamelCase.
22
-
23
- == Installation
24
-
25
- Install the library using rubygems
26
-
27
- $ gem install construqt-ipaddress
28
-
29
- You can then use it in your programs:
30
-
31
- require 'rubygems' # optional
32
- require 'construqt-ipaddress'
33
-
34
- Another way would be to clone the git repository
35
-
36
- $ git clone git://github.com/mabels/ipaddress.git
37
-
38
- And then install the library
39
-
40
- $ cd ipaddress
41
- ipaddress$ rake install
42
-
43
- Install the library with rust
44
- $ cargo install ipaddress
45
-
46
- or add to your Cargo.toml
47
- ipaddress = "0.1.1"
48
-
49
- For javascript:
50
-
51
- $ npm install ipaddress
52
-
53
- it is a commonjs file ipaddress.js in the root of the package
54
- if your in typescript there is the src directory with the
55
- typescipt sources.
56
-
57
-
58
- == Documentation
59
-
60
- The code is fully documented with RDoc. You can generate the
61
- documentation with Rake:
62
-
63
- ipaddress$ rake rdoc
64
-
65
- The latest documentation can be found online at
66
- [http://rubydoc.info/gems/costruqt-ipaddress]
67
-
68
- or
69
-
70
- [https://docs.rs/ipaddress/0.1.1/ipaddress/struct.IPAddress.html]
71
-
72
- or
73
-
74
- i have to explore to publish the documentation to the npm
75
-
76
- == IPv4
77
-
78
- Class IPAddress::IPv4 is used to handle IPv4 type addresses. IPAddress
79
- is similar to other IP Addresses libraries, like Ruby's own
80
- IPAddr. However it works slightly different, as we will see.
81
-
82
- === Create a new IPv4 address
83
-
84
- The usual way to express an IP Address is using its dotted decimal
85
- form, such as 172.16.10.1, and a prefix, such as 24, separated by a
86
- slash.
87
-
88
- 172.16.10.1/24
89
-
90
- To create a new IPv4 object, you can use IPv4 own class
91
-
92
- ip = IPAddress::IPv4.new "172.16.10.1/24"
93
-
94
- or, in a easier way, using the IPAddress parse method
95
-
96
- ip = IPAddress.parse "172.16.10.1/24"
97
-
98
- which accepts and parses any kind of IP (IPv4, IPV6 and
99
- IPv4 IPv6 Mapped addresses).
100
-
101
- If you like syntactic sugar, you can use the wrapper method
102
- IPAddress(), which is built around IPAddress::parse:
103
-
104
- ip = IPAddress "172.16.10.1/24"
105
-
106
- You can specify an IPv4 address in any of two ways:
107
-
108
- IPAddress "172.16.10.1/24"
109
- IPAddress "172.16.10.1/255.255.255.0"
110
-
111
- In this example, prefix /24 and netmask 255.255.255.0 are the same and
112
- you have the flexibility to use either one of them.
113
-
114
- If you don't explicitly specify the prefix (or the subnet mask),
115
- IPAddress thinks you're dealing with host addresses and not with
116
- networks. Therefore, the default prefix will be /32, or
117
- 255.255.255.255. For example:
118
-
119
- # let's declare an host address
120
- host = IPAddress::IPv4.new "10.1.1.1"
121
-
122
- puts host.to_string
123
- #=> "10.1.1.1/32"
124
-
125
- The new created object has prefix /32, which is the same
126
- as we created the following:
127
-
128
- host = IPAddress::IPv4.new "10.1.1.1/32"
129
-
130
- === Handling the IPv4 address
131
-
132
- Once created, you can obtain the attributes for an IPv4 object:
133
-
134
- ip = IPAddress("172.16.10.1/24")
135
-
136
- ip.address
137
- #=> "172.16.10.1"
138
- ip.prefix
139
- #=> 24
140
-
141
- In case you need to retrieve the netmask in IPv4 format, you can use
142
- the IPv4#netmask method:
143
-
144
- ip.netmask
145
- #=> "255.255.255.0"
146
-
147
- A special attribute, IPv4#octets, is available to get the four
148
- decimal octets from the IP address:
149
-
150
- ip.octets
151
- #=> [172,16,10,1]
152
-
153
- Shortcut method IPv4#[], provides access to a given octet whithin the
154
- range:
155
-
156
- ip[1]
157
- #=> 16
158
-
159
- If you need to print out the IPv4 address in a canonical form, you can
160
- use IPv4#to_string
161
-
162
- ip.to_string
163
- #=> "172.16.10.l/24"
164
-
165
- === Changing netmask
166
-
167
- You can set a new prefix (netmask) after creating an IPv4
168
- object. For example:
169
-
170
- ip.prefix = 25
171
-
172
- ip.to_string
173
- #=> "172.16.10.l/25"
174
-
175
- If you need to use a netmask in IPv4 format, you can achive so by
176
- using the IPv4#netmask= method
177
-
178
- ip.netmask = "255.255.255.252"
179
-
180
- ip.to_string
181
- #=> "172.16.10.1/30"
182
-
183
- === Working with networks, broadcasts and addresses
184
-
185
- Some very important topics in dealing with IP addresses are the
186
- concepts of +network+ and +broadcast+, as well as the addresses
187
- included in a range.
188
-
189
- When you specify an IPv4 address such as "172.16.10.1/24", you are
190
- actually handling two different information:
191
-
192
- * The IP address itself, "172.16.10.1"
193
- * The subnet mask which indicates the network
194
-
195
- The network number is the IP which has all zeroes in the host
196
- portion. In our example, because the prefix is 24, we identify our
197
- network number to have the last 8 (32-24) bits all zeroes. Thus, IP
198
- address "172.16.10.1/24" belongs to network "172.16.10.0/24".
199
-
200
- This is very important because, for instance, IP "172.16.10.1/16" is
201
- very different to the previous one, belonging to the very different
202
- network "172.16.0.0/16".
203
-
204
- ==== Networks
205
-
206
- With IPAddress it's very easy to calculate the network for an IP
207
- address:
208
-
209
- ip = IPAddress "172.16.10.1/24"
210
-
211
- net = ip.network
212
- #=> #<IPAddress::IPv4:0xb7a5ab24 @octets=[172, 16, 10, 0],
213
- @prefix=24,
214
- @address="172.16.10.0">
215
- net.to_string
216
- #=> "172.16.10.0/24"
217
-
218
- Method IPv4#network creates a new IPv4 object from the network
219
- number, calculated after the original object. We want to outline here
220
- that the network address is a perfect legitimate IPv4 address, which
221
- just happen to have all zeroes in the host portion.
222
-
223
- You can use method IPv4#network? to check whether an IP address is a
224
- network or not:
225
-
226
- ip1 = IPAddress "172.16.10.1/24"
227
- ip2 = IPAddress "172.16.10.4/30"
228
-
229
- ip1.network?
230
- #=> false
231
- ip2.network?
232
- #=> true
233
-
234
- ==== Broadcast
235
-
236
- The broadcast address is the contrary than the network number: where
237
- the network number has all zeroes in the host portion, the broadcast
238
- address has all one's. For example, ip "172.16.10.1/24" has broadcast
239
- "172.16.10.255/24", where ip "172.16.10.1/16" has broadcast
240
- "172.16.255.255/16".
241
-
242
- Method IPv4#broadcast has the same behavior as is #network
243
- counterpart: it creates a new IPv4 object to handle the broadcast
244
- address:
245
-
246
- ip = IPAddress "172.16.10.1/24"
247
-
248
- bcast = ip.broadcast
249
- #=> #<IPAddress::IPv4:0xb7a406fc @octets=[172, 16, 10, 255],
250
- @prefix=24,
251
- @address="172.16.10.255">
252
- bcast.to_string
253
- #=> "172.16.10.255/24"
254
-
255
- ==== Addresses, ranges and iterators
256
-
257
- So we see that the netmask essentially specifies a range for IP
258
- addresses that are included in a network: all the addresses between
259
- the network number and the broadcast. IPAddress has many methods to
260
- iterate between those addresses. Let's start with IPv4#each, which
261
- iterates over all addresses in a range
262
-
263
- ip = IPAddress "172.16.10.1/24"
264
-
265
- ip.each do |addr|
266
- puts addr
267
- end
268
-
269
- It is important to note that it doesn't matter if the original IP is a
270
- host IP or a network number (or a broadcast address): the #each method
271
- only considers the range that the original IP specifies.
272
-
273
- If you only want to iterate over hosts IP, use the IPv4#each_host
274
- method:
275
-
276
- ip = IPAddress "172.16.10.1/24"
277
-
278
- ip.each_host do |host|
279
- puts host
280
- end
281
-
282
- Methods IPv4#first and IPv4#last return a new object containing
283
- respectively the first and the last host address in the range
284
-
285
- ip = IPAddress "172.16.10.100/24"
286
-
287
- ip.first.to_string
288
- #=> "172.16.10.1/24"
289
-
290
- ip.last.to_string
291
- #=> "172.16.10.254/24"
292
-
293
- === IP special formats
294
-
295
- The IPAddress library provides a complete set of methods to access an
296
- IPv4 address in special formats, such as binary, 32 bits unsigned int,
297
- data and hexadecimal.
298
-
299
- Let's take the following IPv4 as an example:
300
-
301
- ip = IPAddress "172.16.10.1/24"
302
-
303
- ip.address
304
- #=> "172.16.10.1"
305
-
306
- The first thing to highlight here is that all these conversion methods
307
- only take into consideration the address portion of an IPv4 object and
308
- not the prefix (netmask).
309
-
310
- So, to express the address in binary format, use the IPv4#bits method:
311
-
312
- ip.bits
313
- #=> "10101100000100000000101000000001"
314
-
315
- To calculate the 32 bits unsigned int format of the ip address, use
316
- the IPv4#to_u32 method
317
-
318
- ip.to_u32
319
- #=> 2886732289
320
-
321
- This method is the equivalent of the Unix call pton(), expressing an
322
- IP address in the so called +network byte order+ notation. However, if
323
- you want to transmit your IP over a network socket, you might need to
324
- transform it in data format using the IPv4#data method:
325
-
326
- ip.data
327
- #=> "\254\020\n\001"
328
-
329
- Finally, you can transform an IPv4 address into a format which is
330
- suitable to use in IPv4-IPv6 mapped addresses:
331
-
332
- ip.to_ipv6
333
- #=> "ac10:0a01"
334
-
335
- === Classful networks
336
-
337
- IPAddress allows you to create and manipulate objects using the old
338
- and deprecated (but apparently still popular) classful networks concept.
339
-
340
- Classful networks and addresses don't have a prefix: their subnet mask
341
- is univocally identified by their address, and therefore diveded in classes.
342
- As per RFC 791, these classes are:
343
-
344
- * Class A, from 0.0.0.0 to 127.255.255.255
345
- * Class B, from 128.0.0.0 to 191.255.255.255
346
- * Class C, from 192.0.0.0 to 255.255.255.255
347
-
348
- Since classful networks here are only considered to calculate the default
349
- prefix number, classes D and E are not considered.
350
-
351
- To create a classful IP and prefix from an IP address, use the
352
- IPv4::parse_classful method:
353
-
354
- # classful ip
355
- ip = IPAddress::IPv4::parse_classful "10.1.1.1"
356
-
357
- ip.prefix
358
- #=> 8
359
-
360
- The method automatically created a new IPv4 object and assigned it
361
- the correct prefix.
362
-
363
- You can easily check which CLASSFUL network an IPv4 object belongs:
364
-
365
- ip = IPAddress("10.0.0.1/24")
366
- ip.a?
367
- #=> true
368
-
369
- ip = IPAddress("172.16.10.1/24")
370
- ip.b?
371
- #=> true
372
-
373
- ip = IPAddress("192.168.1.1/30")
374
- ip.c?
375
- #=> true
376
-
377
- Remember that these methods are only checking the address portion of an IP, and are
378
- independent from its prefix, as classful networks have no concept of prefix.
379
-
380
- For more information on CLASSFUL networks visit the
381
- {Wikipedia page}[http://en.wikipedia.org/wiki/Classful_network]
382
-
383
- === Network design with IPAddress
384
-
385
- IPAddress includes a lot of useful methods to manipulate IPv4 and IPv6
386
- networks and do some basic network design.
387
-
388
- ==== Subnetting
389
-
390
- The process of subnetting is the division of a network into smaller
391
- (in terms of hosts capacity) networks, called subnets, so that they
392
- all share a common root, which is the starting network.
393
-
394
- For example, if you have network "172.16.10.0/24", we can subnet it
395
- into 4 smaller subnets. The new prefix will be /26, because 4 is 2^2
396
- and therefore we add 2 bits to the network prefix (24+2=26).
397
-
398
- Subnetting is easy with IPAddress. You actually have two options:
399
-
400
- * IPv4#subnet: specify a new prefix
401
- * IPv4#split: tell IPAddress how many subnets you want to create.
402
-
403
- Let's examine IPv4#subnet first. Say you have network "172.16.10.0/24"
404
- and you want to subnet it into /26 networks. With IPAddress it's very
405
- easy:
406
-
407
- network = IPAddress "172.16.10.0/24"
408
-
409
- subnets = network.subnet(26)
410
-
411
- subnets.map{|i| i.to_string}
412
- #=> ["172.16.10.0/26",
413
- "172.16.10.64/26",
414
- "172.16.10.128/26",
415
- "172.16.10.192/26"]
416
-
417
- As you can see, an Array has been created, containing 4 new IPv4 objects
418
- representing the new subnets.
419
-
420
- Another way to create subnets is to tell IPAddress how many subnets you'd
421
- like to have, and letting the library calculate the new prefix for you.
422
-
423
- Let's see how it works, using IPv4#split method. Say you want 4 new subnets:
424
-
425
- network = IPAddress("172.16.10.0/24")
426
-
427
- subnets = network.split(4)
428
-
429
- subnets.map{|i| i.to_string}
430
- #=> ["172.16.10.0/26",
431
- "172.16.10.64/26",
432
- "172.16.10.128/26",
433
- "172.16.10.192/26"]
434
-
435
- Hey, that's the same result as before! This actually makes sense, as the
436
- two operations are complementary. When you use IPv4#subnet with the new
437
- prefix, IPAddress will always create a number of subnets that is a power
438
- of two. This is equivalent to use IPv4#split with a power of 2.
439
-
440
- Where IPv4#split really shines is with the so called "uneven subnetting".
441
- You are not limited to split a network into a power-of-two numbers of
442
- subnets: IPAddress lets you create any number of subnets, and it will
443
- try to organize the new created network in the best possible way, making
444
- an efficent allocation of the space.
445
-
446
- An example here is worth a thousand words. Let's use the same network
447
- as the previous examples:
448
-
449
- network = IPAddress("172.16.10.0/24")
450
-
451
- How do we split this network into 3 subnets? Very easy:
452
-
453
- subnets = network.split(3)
454
-
455
- subnets.map{|i| i.to_string}
456
- #=> ["172.16.10.0/26",
457
- "172.16.10.64/26",
458
- "172.16.10.128/25"]
459
-
460
- As you can see, IPAddress tried to perform a good allocation by filling up
461
- all the address space from the original network. There is no point in splitting
462
- a network into 3 subnets like "172.16.10.0/26", "172.16.10.64/26" and
463
- "172.16.10.128/26", as you would end up having "172.16.10.192/26" wasted (plus,
464
- I suppose I wouldn't need a Ruby library to perform un-efficient IP
465
- allocation, as I do that myself very well ;) ).
466
-
467
- We can go even further and split into 11 subnets:
468
-
469
- network.split(11)
470
- #=> ["172.16.10.0/28", "172.16.10.16/28", "172.16.10.32/28",
471
- "172.16.10.48/28", "172.16.10.64/28", "172.16.10.80/28",
472
- "172.16.10.96/28", "172.16.10.112/28", "172.16.10.128/27",
473
- "172.16.10.160/27", "172.16.10.192/26"]
474
-
475
- As you can see, most of the networks are /28, with a few /27 and one
476
- /26 to fill up the remaining space.
477
-
478
- ==== Summarization
479
-
480
- Summarization (or aggregation) is the process when two or more
481
- networks are taken together to check if a supernet, including
482
- all and only these networks, exists. If it exists then this supernet
483
- is called the summarized (or aggregated) network.
484
- It is very important to understand that summarization can only
485
- occur if there are no holes in the aggregated network, or, in
486
- other words, if the given networks fill completely the address space
487
- of the supernet. So the two rules are:
488
-
489
- 1) The aggregate network must contain +all+ the IP addresses of the
490
- original networks;
491
-
492
- 2) The aggregate network must contain +only+ the IP addresses of the
493
- original networks;
494
-
495
- A few examples will help clarify the above. Let's consider for
496
- instance the following two networks:
497
-
498
- ip1 = IPAddress("172.16.10.0/24")
499
- ip2 = IPAddress("172.16.11.0/24")
500
-
501
- These two networks can be expressed using only one IP address
502
- network if we change the prefix. Let Ruby do the work:
503
-
504
- IPAddress::IPv4::summarize(ip1,ip2).map(&:to_string)
505
- #=> "172.16.10.0/23"
506
-
507
- We note how the network "172.16.10.0/23" includes all the
508
- addresses specified in the above networks, and (more important) includes
509
- ONLY those addresses.
510
-
511
- If we summarized +ip1+ and +ip2+ with the following network:
512
-
513
- "172.16.0.0/16"
514
-
515
- we would have satisfied rule #1 above, but not rule #2. So
516
-
517
- "172.16.0.0/16"
518
-
519
- is not an aggregate network for +ip1+ and +ip2+.
520
-
521
- If it's not possible to compute a single aggregated network for
522
- all the original networks, the method returns an array with all the
523
- aggregate networks found. For example, the following four networks can be
524
- aggregated in a single /22:
525
-
526
- ip1 = IPAddress("10.0.0.1/24")
527
- ip2 = IPAddress("10.0.1.1/24")
528
- ip3 = IPAddress("10.0.2.1/24")
529
- ip4 = IPAddress("10.0.3.1/24")
530
-
531
- IPAddress::IPv4::summarize(ip1,ip2,ip3,ip4).map{|i| i.to_string}
532
- #=> ["10.0.0.0/22"]
533
-
534
- But the following networks can't be summarized in a single
535
- network:
536
-
537
- ip1 = IPAddress("10.0.1.1/24")
538
- ip2 = IPAddress("10.0.2.1/24")
539
- ip3 = IPAddress("10.0.3.1/24")
540
- ip4 = IPAddress("10.0.4.1/24")
541
-
542
- IPAddress::IPv4::summarize(ip1,ip2,ip3,ip4).map{|i| i.to_string}
543
- #=> ["10.0.1.0/24","10.0.2.0/23","10.0.4.0/24"]
544
-
545
- In this case, the two summarizables networks have been aggregated into
546
- a single /23, while the other two networks have been left untouched.
547
-
548
- ==== Supernetting
549
-
550
- Supernetting is a different operation than aggregation, as it only
551
- works on a single network and returns a new single IPv4 object,
552
- representing the supernet.
553
-
554
- Supernetting is similar to subnetting, except that you getting as a
555
- result a network with a smaller prefix (bigger host space). For
556
- example, given the network
557
-
558
- ip = IPAddress("172.16.10.0/24")
559
-
560
- you can supernet it with a new /23 prefix
561
-
562
- ip.supernet(23).to_string
563
- #=> "172.16.10.0/23"
564
-
565
- However if you supernet it with a /22 prefix, the network address will
566
- change:
567
-
568
- ip.supernet(22).to_string
569
- #=> "172.16.8.0/22"
570
-
571
- This is because "172.16.10.0/22" is not a network anymore, but an host
572
- address.
573
-
574
- == IPv6
575
-
576
- IPAddress is not only fantastic for IPv4 addresses, it's also great to
577
- handle IPv6 addresses family! Let's discover together how to use it in
578
- our projects.
579
-
580
- === IPv6 addresses
581
-
582
- IPv6 addresses are 128 bits long, in contrast with IPv4 addresses
583
- which are only 32 bits long. An IPv6 address is generally written as
584
- eight groups of four hexadecimal digits, each group representing 16
585
- bits or two octet. For example, the following is a valid IPv6
586
- address:
587
-
588
- 2001:0db8:0000:0000:0008:0800:200c:417a
589
-
590
- Letters in an IPv6 address are usually written downcase, as per
591
- RFC. You can create a new IPv6 object using uppercase letters, but
592
- they will be converted.
593
-
594
- ==== Compression
595
-
596
- Since IPv6 addresses are very long to write, there are some
597
- simplifications and compressions that you can use to shorten them.
598
-
599
- * Leading zeroes: all the leading zeroes within a group can be
600
- omitted: "0008" would become "8"
601
-
602
- * A string of consecutive zeroes can be replaced by the string
603
- "::". This can be only applied once.
604
-
605
- Using compression, the IPv6 address written above can be shorten into
606
- the following, equivalent, address
607
-
608
- 2001:db8::8:800:200c:417a
609
-
610
- This short version is often used in human representation.
611
-
612
- ==== Network Mask
613
-
614
- As we used to do with IPv4 addresses, an IPv6 address can be written
615
- using the prefix notation to specify the subnet mask:
616
-
617
- 2001:db8::8:800:200c:417a/64
618
-
619
- The /64 part means that the first 64 bits of the address are
620
- representing the network portion, and the last 64 bits are the host
621
- portion.
622
-
623
- === Using IPAddress with IPv6 addresses
624
-
625
- All the IPv6 representations we've just seen are perfectly fine when
626
- you want to create a new IPv6 address:
627
-
628
- ip6 = IPAddress "2001:0db8:0000:0000:0008:0800:200C:417A"
629
-
630
- ip6 = IPAddress "2001:db8:0:0:8:800:200C:417A"
631
-
632
- ip6 = IPAddress "2001:db8:8:800:200C:417A"
633
-
634
- All three are giving out the same IPv6 object. The default subnet mask
635
- for an IPv6 is 128, as IPv6 addresses don't have classes like IPv4
636
- addresses. If you want a different mask, you can go ahead and explicit
637
- it:
638
-
639
- ip6 = IPAddress "2001:db8::8:800:200c:417a/64"
640
-
641
- Access the address portion and the prefix by using the respective
642
- methods:
643
-
644
- ip6 = IPAddress "2001:db8::8:800:200c:417a/64"
645
-
646
- ip6.address
647
- #=> "2001:0db8:0000:0000:0008:0800:200c:417a"
648
-
649
- ip6.prefix
650
- #=> 64
651
-
652
- A compressed version of the IPv6 address can be obtained with the
653
- IPv6#compressed method:
654
-
655
- ip6 = IPAddress "2001:0db8:0000:0000:0008:200c:417a:00ab/64"
656
-
657
- ip6.compressed
658
- #=> "2001:db8::8:800:200c:417a"
659
-
660
- === Handling the IPv6 address
661
-
662
- Accessing the groups that form an IPv6 address is very easy with the
663
- IPv6#groups method:
664
-
665
- ip6 = IPAddress "2001:db8::8:800:200c:417a/64"
666
-
667
- ip6.groups
668
- #=> [8193, 3512, 0, 0, 8, 2048, 8204, 16762]
669
-
670
- As with IPv4 addresses, each individual group can be accessed using
671
- the IPv6#[] shortcut method:
672
-
673
- ip6[0]
674
- #=> 8193
675
- ip6[1]
676
- #=> 3512
677
- ip6[2]
678
- #=> 0
679
- ip6[3]
680
- #=> 0
681
-
682
- Note that each 16 bits group is expressed in its decimal form. You can
683
- also obtain the groups into hexadecimal format using the IPv6#hexs
684
- method:
685
-
686
- ip6.hexs
687
- #=> => ["2001", "0db8", "0000", "0000", "0008", "0800", "200c", "417a"]
688
-
689
- A few other methods are available to transform an IPv6 address into
690
- decimal representation, with IPv6.to_i
691
-
692
- ip6.to_i
693
- #=> 42540766411282592856906245548098208122
694
-
695
- or to hexadecimal representation
696
-
697
- ip6.to_hex
698
- #=> "20010db80000000000080800200c417a"
699
-
700
- To print out an IPv6 address in human readable form, use the IPv6#to_s, IPv6#to_string
701
- and IPv6#to_string_uncompressed methods
702
-
703
- ip6 = IPAddress "2001:db8::8:800:200c:417a/64"
704
-
705
- ip6.to_string
706
- #=> "2001:db8::8:800:200c:417a/96"
707
-
708
- ip6.to_string_uncompressed
709
- #=> "2001:0db8:0000:0000:0008:0800:200c:417a/96"
710
-
711
- As you can see, IPv6.to_string prints out the compressed form, while
712
- IPv6.to_string_uncompressed uses the expanded version.
713
-
714
- ==== Compressing and uncompressing
715
-
716
- If you have a string representing an IPv6 address, you can easily
717
- compress it and uncompress it using the two class methods IPv6::expand
718
- and IPv6::compress.
719
-
720
- For example, let's say you have the following uncompressed IPv6
721
- address:
722
-
723
- ip6str = "2001:0DB8:0000:CD30:0000:0000:0000:0000"
724
-
725
- Here is the compressed version:
726
-
727
- IPAddress::IPv6.compress ip6str
728
- #=> "2001:db8:0:cd30::"
729
-
730
- The other way works as well:
731
-
732
- ip6str = "2001:db8:0:cd30::"
733
-
734
- IPAddress::IPv6.expand ip6str
735
- #=> "2001:0DB8:0000:CD30:0000:0000:0000:0000"
736
-
737
- These methods can be used when you don't want to create a new object
738
- just for expanding or compressing an address (although a new object is
739
- actually created internally).
740
-
741
- === New IPv6 address from other formats
742
-
743
- You can create a new IPv6 address from different formats than just a
744
- string representing the colon-hex groups.
745
-
746
- For instance, if you have a data stream, you can use IPv6::parse_data,
747
- like in the following example:
748
-
749
- data = " \001\r\270\000\000\000\000\000\b\b\000 \fAz"
750
-
751
- ip6 = IPAddress::IPv6::parse_data data
752
- ip6.prefix = 64
753
-
754
- ip6.to_string
755
- #=> "2001:db8::8:800:200c:417a/64"
756
-
757
- A new IPv6 address can also be created from an unsigned 128 bits
758
- integer:
759
-
760
- u128 = 42540766411282592856906245548098208122
761
-
762
- ip6 = IPAddress::IPv6::parse_u128 u128
763
- ip6.prefix = 64
764
-
765
- ip6.to_string
766
- #=>"2001:db8::8:800:200c:417a/64"
767
-
768
- Finally, a new IPv6 address can be created from an hex string:
769
-
770
- hex = "20010db80000000000080800200c417a"
771
-
772
- ip6 = IPAddress::IPv6::parse_hex hex
773
- ip6.prefix = 64
774
-
775
- ip6.to_string
776
- #=> "2001:db8::8:800:200c:417a/64"
777
-
778
- === Special IPv6 addresses
779
-
780
- Some IPv6 have a special meaning and are expressed in a special form,
781
- quite different than an usual IPv6 address. IPAddress has built-in
782
- support for unspecified, loopback and mapped IPv6 addresses.
783
-
784
- ==== Unspecified address
785
-
786
- The address with all zero bits is called the +unspecified+ address
787
- (corresponding to 0.0.0.0 in IPv4). It should be something like this:
788
-
789
- 0000:0000:0000:0000:0000:0000:0000:0000
790
-
791
- but, with the use of compression, it is usually written as just two
792
- colons:
793
-
794
- ::
795
-
796
- or, specifying the netmask:
797
-
798
- ::/128
799
-
800
- With IPAddress, create a new unspecified IPv6 address using its own
801
- subclass:
802
-
803
- ip = IPAddress::IPv6::Unspecified.new
804
-
805
- ip.to_string
806
- #=> "::/128"
807
-
808
- You can easily check if an IPv6 object is an unspecified address by
809
- using the IPv6#unspecified? method
810
-
811
- ip.unspecified?
812
- #=> true
813
-
814
- An unspecified IPv6 address can also be created with the wrapper
815
- method, like we've seen before
816
-
817
- ip = IPAddress "::"
818
-
819
- ip.unspecified?
820
- #=> true
821
-
822
- This address must never be assigned to an interface and is to be used
823
- only in software before the application has learned its host's source
824
- address appropriate for a pending connection. Routers must not forward
825
- packets with the unspecified address.
826
-
827
- ==== Loopback address
828
-
829
- The loopback address is a unicast localhost address. If an
830
- application in a host sends packets to this address, the IPv6 stack
831
- will loop these packets back on the same virtual interface.
832
-
833
- Loopback addresses are expressed in the following form:
834
-
835
- ::1
836
-
837
- or, with their appropriate prefix,
838
-
839
- ::1/128
840
-
841
- As for the unspecified addresses, IPv6 loopbacks can be created with
842
- IPAddress calling their own class:
843
-
844
- ip = IPAddress::IPv6::Loopback.new
845
-
846
- ip.to_string
847
- #=> "::1/128"
848
-
849
- or by using the wrapper:
850
-
851
- ip = IPAddress "::1"
852
-
853
- ip.to_string
854
- #=> "::1/128"
855
-
856
- Checking if an address is loopback is easy with the IPv6#loopback?
857
- method:
858
-
859
- ip.loopback?
860
- #=> true
861
-
862
- The IPv6 loopback address corresponds to 127.0.0.1 in IPv4.
863
-
864
- ==== Mapped address
865
-
866
- It is usually identified as a IPv4 mapped IPv6 address, a particular
867
- IPv6 address which aids the transition from IPv4 to IPv6. The
868
- structure of the address is
869
-
870
- ::ffff:w.y.x.z
871
-
872
- where w.x.y.z is a normal IPv4 address. For example, the following is
873
- a mapped IPv6 address:
874
-
875
- ::ffff:192.168.100.1
876
-
877
- IPAddress is very powerful in handling mapped IPv6 addresses, as the
878
- IPv4 portion is stored internally as a normal IPv4 object. Let's have
879
- a look at some examples. To create a new mapped address, just use the
880
- class builder itself
881
-
882
- ip6 = IPAddress::IPv6::Mapped.new "::ffff:172.16.10.1/128"
883
-
884
- or just use the wrapper method
885
-
886
- ip6 = IPAddress "::ffff:172.16.10.1/128"
887
-
888
- Let's check it's really a mapped address:
889
-
890
- ip6.mapped?
891
- #=> true
892
-
893
- ip6.to_string
894
- #=> "::ffff:172.16.10.1/128"
895
-
896
- Now with the +ipv4+ attribute, we can easily access the IPv4 portion
897
- of the mapped IPv6 address:
898
-
899
- ip6.ipv4.address
900
- #=> "172.16.10.1"
901
-
902
- Internally, the IPv4 address is stored as two 16 bits
903
- groups. Therefore all the usual methods for an IPv6 address are
904
- working perfectly fine:
905
-
906
- ip6.to_hex
907
- #=> "00000000000000000000ffffac100a01"
908
-
909
- ip6.address
910
- #=> "0000:0000:0000:0000:0000:ffff:ac10:0a01"
911
-
912
- A mapped IPv6 can also be created just by specify the address in the
913
- following format:
914
-
915
- ip6 = IPAddress "::172.16.10.1"
916
-
917
- That is, two colons and the IPv4 address. However, as by RFC, the ffff
918
- group will be automatically added at the beginning
919
-
920
- ip6.to_string
921
- => "::ffff:172.16.10.1/128"
922
-
923
- making it a mapped IPv6 compatible address.
924
-
925
- == Why not using IPAddr?
926
-
927
- IPAddr is the IP addresses library that comes with Ruby standard
928
- lib. We found this library, although very well written, not very
929
- suitable for all our needs, and not very flexible.
930
-
931
- Some quick examples of things you can't do with IPAddr:
932
-
933
- * store both the address and the prefix information
934
- * quickly find the broadcast address of a network
935
- * iterate over hosts
936
- * perform subnetting or network aggregation
937
-
938
- Many methods and procedures are so old that they have been
939
- declared deprecated by the IETF, and some others have bugs in their
940
- implementation.
941
-
942
- Moreover, IPAddress is more robust and is already around 50% faster than IPAddr,
943
- in addition to provide an organic API with logical separation and OO structure.
944
-
945
- We hope that IPAddress will address all these issues and meet all your
946
- needs in network programming.
947
-
948
-
949
- == Copyright
950
-
951
- Copyright (c) 2009-2011 Marco Ceresa. See LICENSE for details.
952
- Copyright (c) 2015-2016 Meno Abels. See LICENSE for details.
953
-
954
-
955
-
956
-