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", ip.IP)
prefix, err = ipam.ReleaseIP(ip)
if err != nil {
panic(err)
}
fmt.Printf("IP: %s released.", ip.IP)
}
Performance
BenchmarkNewPrefixMemory-4 1000000 1637 ns/op 728 B/op 27 allocs/op
BenchmarkNewPrefixPostgres-4 200 8611579 ns/op 6170 B/op 155 allocs/op
BenchmarkAcquireIPMemory-4 1000000 1234 ns/op 232 B/op 15 allocs/op
BenchmarkAcquireIPPostgres-4 200 11583345 ns/op 7252 B/op 184 allocs/op
BenchmarkAcquireChildPrefix1-4 300000 3771 ns/op 1528 B/op 58 allocs/op
BenchmarkAcquireChildPrefix2-4 300000 3773 ns/op 1528 B/op 58 allocs/op
BenchmarkAcquireChildPrefix3-4 300000 3997 ns/op 1541 B/op 58 allocs/op
BenchmarkAcquireChildPrefix4-4 300000 4877 ns/op 1581 B/op 60 allocs/op
BenchmarkAcquireChildPrefix5-4 200000 5541 ns/op 1854 B/op 70 allocs/op
BenchmarkAcquireChildPrefix6-4 300000 4123 ns/op 1528 B/op 58 allocs/op
BenchmarkAcquireChildPrefix7-4 300000 4954 ns/op 1528 B/op 58 allocs/op
BenchmarkAcquireChildPrefix8-4 300000 5017 ns/op 1528 B/op 58 allocs/op
BenchmarkAcquireChildPrefix9-4 300000 5309 ns/op 1528 B/op 58 allocs/op
BenchmarkAcquireChildPrefix10-4 200000 5234 ns/op 1532 B/op 58 allocs/op
BenchmarkPrefixOverlapping-4 1000000 1934 ns/op 432 B/op 24 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
- Variables
- func JitterDelay(_ uint, config *retry.Config) time.Duration
- func NewMemory() *memory
- func NewPostgresStorage(host, port, user, password, dbname string, sslmode SSLMode) (*sql, error)
- type IP
- type Ipamer
- type NoIPAvailableError
- type NotFoundError
- type OptimisticLockError
- type Prefix
- type SSLMode
- type Storage
- type Usage
Constants ¶
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 ¶
var ( // ErrNotFound is returned if prefix or cidr was not found ErrNotFound NotFoundError // ErrNoIPAvailable is returned if no IP is available anymore ErrNoIPAvailable NoIPAvailableError )
Functions ¶
func JitterDelay ¶
JitterDelay is a DelayType which varies delay in each iterations
func NewPostgresStorage ¶
NewPostgresStorage creates a new Storage which uses postgres.
Types ¶
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 int) (*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 {
// contains filtered or unexported fields
}
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
Source Files