Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/c-robinson/iplib

A library for working with IP addresses and networks in Go
https://github.com/c-robinson/iplib

cidr go golang-library golang-tools ip ipaddress ipaddresses ipv4 ipv4-address ipv6 ipv6-address ipv6-subnetting library subnet subnet-calculator subnetting

Last synced: 3 months ago
JSON representation

A library for working with IP addresses and networks in Go

Awesome Lists containing this project

README 

        
# IPLib

[![Documentation](https://godoc.org/github.com/c-robinson/iplib?status.svg)](https://pkg.go.dev/github.com/c-robinson/iplib/v2)

[![Go Report Card](https://goreportcard.com/badge/github.com/c-robinson/iplib)](https://goreportcard.com/report/github.com/c-robinson/iplib)

[![Tests](https://img.shields.io/github/actions/workflow/status/c-robinson/iplib/test.yml?branch=main&longCache=true&label=Test&logo=github%20actions&logoColor=fff)](https://github.com/c-robinson/iplib/actions?query=workflow%3ATest)



**ATTENTION** version 2.0.0 is a breaking change from previous versions for

handling IPv6 addresses (functions for IPv4 are unchanged). Calls that result

in arithmatic operations against IPv6 now use [uint128.Uint128](https://lukechampine.com/uint128)

instead of `*big.Int`. Until now this library restricted itself to using the

standard library, but `math/big` is sloooooooooow and the performance gains

from switching were too large to ignore:



| Benchmark | *big.Int | uint128.Uint128 |

| --- | --- |-----------------|

| Benchmark_DeltaIP6 | 79.27 ns/op | 2.809 ns/op     |

| BenchmarkDecrementIP6By | 50.54 ns/op | 13.88 ns/op     |

| BenchmarkIncrementIP6By | 50.48 ns/op | 13.92 ns/op     |

| BenchmarkNet_Count6 | 122.2 ns/op | 11.26 ns/op     |



It would be fantastic to remove this external dependency in some future v3

that switched to a native `uint128` but for that to happen [this proposal](https://github.com/golang/go/issues/9455)

(or something similar) would need to be adopted.



**Okay you can stop paying attention now** 



I really enjoy Python's [ipaddress](https://docs.python.org/3/library/ipaddress.html)

library and Ruby's [ipaddr](https://ruby-doc.org/stdlib-2.5.1/libdoc/ipaddr/rdoc/IPAddr.html),

I think you can write a lot of neat software if some of the little problems

around manipulating IP addresses and netblocks are taken care of for you, so I

set out to write something like them for my language of choice, Go. This is

what I've come up with.



[IPLib](http://godoc.org/github.com/c-robinson/iplib) is a hopefully useful,

aspirationally full-featured library built around and on top of the address

primitives found in the [net](https://golang.org/pkg/net/) package, it seeks

to make them more accessible and easier to manipulate. 



It includes:



##### net.IP tools



Some simple tools for performing common tasks against IP objects:



- compare two addresses

- make a copy of a net.IP address

- get the delta between two addresses

- sort

- decrement or increment addresses

- print addresses as binary or hexadecimal strings, or print their addr.ARPA

  DNS name

- print v6 in fully expanded form

- convert between net.IP and integer values

- get the version of a v4 address or force a IPv4-mapped IPv6address to be a 

  v4 address



##### iplib.Net



An enhancement of `net.IPNet`, `iplib.Net` is an interface with two, version-

specific implementations providing features such as:



- retrieve the first and last usable address

- retrieve the wildcard mask

- enumerate all or part of a netblock to `[]net.IP`

- decrement or increment addresses within the boundaries of the netblock

- return the supernet of a netblock

- allocate subnets within the netblock

- return next- or previous-adjacent netblocks



##### Net4 and Net6 implementations of Net



The two address versions behave differently in both large and subtle ways,

and the version-specific implementations seek to account for this. For example

the Net4 implementation omits the network and broadcast addresses from

consideration during enumeration; while the Net6 implementation introduces the

concept of a HostMask, which blocks usable addresses off from the right in the

same way that a netmask constrains them from the left



Additional version-specific considerations described in the [Net4](#using-iplibnet4)

and [Net6](#using-iplibnet6) sections below.



## Sub-modules



- [iana](https://github.com/c-robinson/iplib/tree/main/iana) - a module for referencing 

  IP netblocks against the [Internet Assigned Numbers Authority's](https://www.iana.org/)

  Special IP Address Registry

- [iid](https://github.com/c-robinson/iplib/tree/main/iid) - a module for

  generating and validating IPv6 Interface Identifiers, including [RFC4291](https://tools.ietf.org/html/rfc4291)

  modified EUI64 and [RFC7217](https://tools.ietf.org/html/rfc7217)

  Semantically Opaque addresses



## Installing



```sh

go get -u github.com/c-robinson/iplib/v2

```



## Using iplib



There are a series of functions for working with v4 or v6 `net.IP` objects:



```go

package main



import (

	"fmt"

	"net"

	"sort"

	

	"github.com/c-robinson/iplib/v2"

)



func main() {

	ipa := net.ParseIP("192.168.1.1")

	ipb := iplib.IncrementIPBy(ipa, 15)      // ipb is 192.168.1.16

	ipc := iplib.NextIP(ipa)                 // ipc is 192.168.1.2



	fmt.Println(iplib.CompareIPs(ipa, ipb))  // -1

    

	fmt.Println(iplib.DeltaIP(ipa, ipb))     // 15

    

	fmt.Println(iplib.IPToHexString(ipc))    // "c0a80102"



	iplist := []net.IP{ ipb, ipc, ipa }

	sort.Sort(iplib.ByIP(iplist))            // []net.IP{ipa, ipc, ipb}



	fmt.Println(iplib.IP4ToUint32(ipa))      // 3232235777

	fmt.Println(iplib.IPToBinaryString(ipa)) // 11000000.10101000.00000001.00000001

	fmt.Println(iplib.IP4ToARPA(ipa))        // 1.1.168.192.in-addr.arpa

}

```



Addresses that require or return a count default to using `uint32`, which is

sufficient for working with the entire IPv4 space. As a rule these functions

are just lowest-common wrappers around IPv4- or IPv6-specific functions. The

IPv6-specific variants use `uint128.Uint128` so they can access the entire v6

space.



## The iplib.Net interface



`Net` describes an `iplib.Net` object, the exposed functions are those that 

are required for comparison, sorting, generic initialization and for ancillary 

functions such as those found in this package's submodules.



## Using iplib.Net4



`Net4` represents an IPv4 network. Since the first and last addresses of a v4

network are typically not allocated for use these will be omitted by

`Enumerate()`, `NextIP()` and `PreviousIP()`; they wont show up in `Count()`;

and `FirstAddress()` and `LastAddress()` show the 2nd and 2nd-to-the-last

addresses respectively. The v4-specific method `NetworkAddress()` returns the

first address, while `BroadcastAddress()` returns the last. There is an

exception made for `Net4` networks defined with a 31-bit netmask, since these

are assumed to be for [RFC3021](https://datatracker.ietf.org/doc/html/rfc3021)

point-to-point links.



Additionally `Net4` contains a `Wildcard()` method which will return the

network's [wildcard address](https://en.wikipedia.org/wiki/Wildcard_mask).



```go

n := iplib.NewNet4(net.ParseIP("192.168.0.0"), 16)

fmt.Println(n.Count())            // 65534 (note: not 65536)

fmt.Println(n.Enumerate(2, 1024)) // [192.168.4.1 192.168.4.2]

fmt.Println(n.IP())               // 192.168.0.0

fmt.Println(n.FirstAddress())     // 192.168.0.1

fmt.Println(n.LastAddress())      // 192.168.255.254

fmt.Println(n.BroadcastAddress()) // 192.168.255.255

fmt.Println(n.Wildcard())         // 0000ffff

fmt.Println(n.Subnet(0))          // [192.168.0.0/17 192.168.128.0/17] 

fmt.Println(n.Supernet(0))        // 192.168.0.0/15 

```



## Using iplib.Net6



`Net6` represents an IPv6 network. In some ways v6 is simpler than v4, as

it does away with the special behavior of addresses at the front and back of

the netblock. For IPv6 the primary problem is the sheer size of the thing:

there are 2^128th addresses in IPv6, which translates to 340 undecillion!



```go

n := iplib.NewNet6(net.ParseIP("2001:db8::"), 56, 0)

fmt.Println(n.Count())                  // 4722366482869645213696

fmt.Println(n.Enumerate(2, 1024))       // [2001:db8::400 2001:db8::401]

fmt.Println(n.FirstAddress())           // 2001:db8::

fmt.Println(n.NextIP(n.FirstAddress())) // 2001:db8::1 

fmt.Println(n.LastAddress())            // 2001:db8:0:ff:ffff:ffff:ffff:ffff

fmt.Println(n.Subnet(0, 0))             // [2001:db8::/57 2001:db8:0:80::/57] 

fmt.Println(n.Supernet(0, 0))           // 2001:db8::/55 

```



### HostMasks with Net6



To manage the address space, `Net6` introduces `HostMask`. This optional

constraint can be used to block addresses on the right-side of a netblock

somewhat like Netmasks do on the left. `Hostmask` must be specified at

initialization time and, if set, will affect the behavior of `Count()`, 

`Enumerate()`, `LastAddress()`, `NextIP()` and `PreviousIP()`. `Subnet()` and

`Supernet()` generate objects that inherit the hostmask of their parent, while

a hostmask must be specified for `NextNet()` and `PreviousNet()`.



```go

// this is the same as the previous example, except with a hostmask set

n := NewNet6(net.ParseIP("2001:db8::"), 56, 60)

fmt.Println(n.Count())                  // 4096

fmt.Println(n.Enumerate(2, 1024))       // [2001:db8:0:40:: 2001:db8:0:40:100::]

fmt.Println(n.FirstAddress())           // 2001:db8::

fmt.Println(n.NextIP(n.FirstAddress())) // 2001:db8:0:0:100:: 

fmt.Println(n.LastAddress())            // 2001:db8:0:ff:f00::

fmt.Println(n.Mask().String())          // ffffffffffffff000000000000000000

fmt.Println(n.Hostmask.String())        // 0000000000000000f0ffffffffffffff

fmt.Println(n.Subnet(0, 60))            // [2001:db8::/57 2001:db8:0:80::/57] 

fmt.Println(n.Supernet(0, 60))          // 2001:db8::/55 

```



## Test driving

[IPfool](github.com/c-robinson/ipfool) is a simple command-line tool that I

wrote to test many of the features within this library and might be useful in

evaluating it.