README
¶
go-ipam
go-ipam is a module to handle IP address management. It can operate on networks, prefixes and IPs.
IP
Most obvious this library is all about IP management. The main purpose is to acquire and release an IP, or a bunch of IP's from prefixes.
Prefix
A prefix is a network with IP and mask, typically in the form of 192.168.0.0/24. To be able to manage IPs you have to create a prefix first.
Example usage:
package main
import (
"fmt"
goipam "github.com/metal-stack/go-ipam"
)
func main() {
// create a ipamer with in memory storage
ipam := goipam.New()
prefix, err := ipam.NewPrefix("192.168.0.0/24")
if err != nil {
panic(err)
}
ip, err := ipam.AcquireIP(prefix.Cidr)
if err != nil {
panic(err)
}
fmt.Printf("got IP: %s\n", ip.IP)
prefix, err = ipam.ReleaseIP(ip)
if err != nil {
panic(err)
}
fmt.Printf("IP: %s released.\n", ip.IP)
// Now a IPv6 Super Prefix with Child Prefixes
prefix, err = ipam.NewPrefix("2001:aabb::/48")
if err != nil {
panic(err)
}
cp1, err := ipam.AcquireChildPrefix(prefix.Cidr, 64)
if err != nil {
panic(err)
}
fmt.Printf("got Prefix: %s\n", cp1)
cp2, err := ipam.AcquireChildPrefix(prefix.Cidr, 72)
if err != nil {
panic(err)
}
fmt.Printf("got Prefix: %s\n", cp2)
ip21, err := ipam.AcquireIP(cp2.Cidr)
if err != nil {
panic(err)
}
fmt.Printf("got IP: %s\n", ip21.IP)
}
Performance
BenchmarkNewPrefix/Memory-4 422596 2712 ns/op 1536 B/op 20 allocs/op
BenchmarkNewPrefix/Postgres-4 127 8257821 ns/op 5587 B/op 126 allocs/op
BenchmarkNewPrefix/Cockroach-4 18 78498926 ns/op 5869 B/op 128 allocs/op
BenchmarkAcquireIP/Memory-4 299738 3941 ns/op 2360 B/op 42 allocs/op
BenchmarkAcquireIP/Postgres-4 88 13501419 ns/op 10740 B/op 257 allocs/op
BenchmarkAcquireIP/Cockroach-4 14 79709070 ns/op 11253 B/op 265 allocs/op
BenchmarkAcquireChildPrefix/8/14-4 153535 7995 ns/op 4496 B/op 69 allocs/op
BenchmarkAcquireChildPrefix/8/16-4 151178 8000 ns/op 4496 B/op 69 allocs/op
BenchmarkAcquireChildPrefix/8/20-4 152636 7760 ns/op 4496 B/op 69 allocs/op
BenchmarkAcquireChildPrefix/8/22-4 154134 7793 ns/op 4496 B/op 69 allocs/op
BenchmarkAcquireChildPrefix/8/24-4 153325 7759 ns/op 4496 B/op 69 allocs/op
BenchmarkAcquireChildPrefix/16/18-4 147488 8186 ns/op 4496 B/op 69 allocs/op
BenchmarkAcquireChildPrefix/16/20-4 154622 7802 ns/op 4496 B/op 69 allocs/op
BenchmarkAcquireChildPrefix/16/22-4 154148 8034 ns/op 4496 B/op 69 allocs/op
BenchmarkAcquireChildPrefix/16/24-4 138088 8748 ns/op 4496 B/op 69 allocs/op
BenchmarkAcquireChildPrefix/16/26-4 125978 8104 ns/op 4496 B/op 69 allocs/op
BenchmarkPrefixOverlapping-4 3400266 342 ns/op 0 B/op 0 allocs/op
Documentation
¶
Overview ¶
Package ipam is a ip address management library for ip's and prefixes (networks).
It uses either memory or postgresql database to store the ip's and prefixes. You can also bring you own Storage implementation as you need.
Example usage:
import (
"fmt"
goipam "github.com/metal-stack/go-ipam"
)
func main() {
// create a ipamer with in memory storage
ipam := goipam.New()
prefix, err := ipam.NewPrefix("192.168.0.0/24")
if err != nil {
panic(err)
}
ip, err := ipam.AcquireIP(prefix)
if err != nil {
panic(err)
}
fmt.Printf("got IP: %s", ip.IP)
err = ipam.ReleaseIP(ip)
if err != nil {
panic(err)
}
fmt.Printf("IP: %s released.", ip.IP)
}
Index ¶
Constants ¶
View Source
const ( // SSLModeAllow I don't care about security // but I will pay the overhead of encryption if the server insists on it SSLModeAllow = SSLMode("allow") // SSLModeDisable I don't care about security // and I don't want to pay the overhead of encryption. SSLModeDisable = SSLMode("disable") // SSLModePrefer I don't care about encryption // but I wish to pay the overhead of encryption if the server supports it. SSLModePrefer = SSLMode("prefer") // SSLModeRequire I want my data to be encrypted and I accept the overhead. // I trust that the network will make sure I always connect to the server I want. SSLModeRequire = SSLMode("require") // SSLModeVerifyCA I want my data encrypted and I accept the overhead. // I want to be sure that I connect to a server that I trust. SSLModeVerifyCA = SSLMode("verify-ca") // SSLModeVerifyFull I want my data encrypted and I accept the overhead. // I want to be sure that I connect to a server I trust, and that it's the one I specify. SSLModeVerifyFull = SSLMode("verify-full") )
Variables ¶
View Source
var ( // ErrNotFound is returned if prefix or cidr was not found ErrNotFound NotFoundError // ErrNoIPAvailable is returned if no IP is available anymore ErrNoIPAvailable NoIPAvailableError // ErrAlreadyAllocated is returned if the requested address is not available ErrAlreadyAllocated AlreadyAllocatedError // ErrOptimisticLockError is returned if insert or update conflicts with the existing data ErrOptimisticLockError OptimisticLockError )
Functions ¶
This section is empty.
Types ¶
type AlreadyAllocatedError ¶
type AlreadyAllocatedError struct {
}
AlreadyAllocatedError is raised if the given address is already in use
func (AlreadyAllocatedError) Error ¶
func (o AlreadyAllocatedError) Error() string
type Ipamer ¶
type Ipamer interface {
// NewPrefix create a new Prefix from a string notation.
NewPrefix(cidr string) (*Prefix, error)
// DeletePrefix delete a Prefix from a string notation.
// If the Prefix is not found an NotFoundError is returned.
DeletePrefix(cidr string) (*Prefix, error)
// AcquireChildPrefix will return a Prefix with a smaller length from the given Prefix.
AcquireChildPrefix(parentCidr string, length uint8) (*Prefix, error)
// AcquireSpecificChildPrefix will return a Prefix with a smaller length from the given Prefix.
AcquireSpecificChildPrefix(parentCidr, childCidr string) (*Prefix, error)
// ReleaseChildPrefix will mark this child Prefix as available again.
ReleaseChildPrefix(child *Prefix) error
// PrefixFrom will return a known Prefix.
PrefixFrom(cidr string) *Prefix
// AcquireSpecificIP will acquire given IP and mark this IP as used, if already in use, return nil.
// If specificIP is empty, the next free IP is returned.
// If there is no free IP an NoIPAvailableError is returned.
AcquireSpecificIP(prefixCidr, specificIP string) (*IP, error)
// AcquireIP will return the next unused IP from this Prefix.
AcquireIP(prefixCidr string) (*IP, error)
// ReleaseIP will release the given IP for later usage and returns the updated Prefix.
// If the IP is not found an NotFoundError is returned.
ReleaseIP(ip *IP) (*Prefix, error)
// ReleaseIPFromPrefix will release the given IP for later usage.
// If the Prefix or the IP is not found an NotFoundError is returned.
ReleaseIPFromPrefix(prefixCidr, ip string) error
// PrefixesOverlapping will check if one ore more prefix of newPrefixes is overlapping
// with one of existingPrefixes
PrefixesOverlapping(existingPrefixes []string, newPrefixes []string) error
}
Ipamer can be used to do IPAM stuff.
func New ¶
func New() Ipamer
New returns a Ipamer with in memory storage for networks, prefixes and ips.
func NewWithStorage ¶
NewWithStorage allows you to create a Ipamer instance with your Storage implementation. The Storage interface must be implemented.
type NoIPAvailableError ¶
type NoIPAvailableError struct {
}
NoIPAvailableError indicates that the acquire-operation could not be executed because the specified prefix has no free IP anymore.
func (NoIPAvailableError) Error ¶
func (o NoIPAvailableError) Error() string
type NotFoundError ¶
type NotFoundError struct {
}
NotFoundError is raised if the given Prefix or Cidr was not found
func (NotFoundError) Error ¶
func (o NotFoundError) Error() string
type OptimisticLockError ¶
type OptimisticLockError struct {
}
OptimisticLockError indicates that the operation could not be executed because the dataset to update has changed in the meantime. clients can decide to read the current dataset and retry the operation.
func (OptimisticLockError) Error ¶
func (o OptimisticLockError) Error() string
type Prefix ¶
type Prefix struct {
Cidr string // The Cidr of this prefix
ParentCidr string // if this prefix is a child this is a pointer back
// contains filtered or unexported fields
}
Prefix is a expression of a ip with length and forms a classless network.
type SSLMode ¶
type SSLMode string
SSLMode specifies how to configure ssl encryption to the database
type Storage ¶
type Storage interface {
CreatePrefix(prefix Prefix) (Prefix, error)
ReadPrefix(prefix string) (Prefix, error)
ReadAllPrefixes() ([]Prefix, error)
ReadAllPrefixCidrs() ([]string, error)
UpdatePrefix(prefix Prefix) (Prefix, error)
DeletePrefix(prefix Prefix) (Prefix, error)
}
Storage is a interface to store ipam objects.
type Usage ¶
type Usage struct {
// AvailableIPs the number of available IPs if this is not a parent prefix
// No more than 2^31 available IPs are reported
AvailableIPs uint64
// AcquiredIPs the number of acquire IPs if this is not a parent prefix
AcquiredIPs uint64
// AvailableSmallestPrefixes is the count of available Prefixes with 2 countable Bits
// No more than 2^31 available Prefixes are reported
AvailableSmallestPrefixes uint64
// AvailablePrefixes is a list of prefixes which are available
AvailablePrefixes []string
// AcquiredPrefixes the number of acquired prefixes if this is a parent prefix
AcquiredPrefixes uint64
}
Usage of ips and child Prefixes of a Prefix
Source Files
Click to show internal directories.
Click to hide internal directories.