odyn

README

odyn

odyn is a dynamic ip address updater for the new age.

It supports a number of public IP address provider web services and can handle AWS Route53 DNS zones.

help

For help with using the command line tool, please download the binary from the releases and run odyn --help.

You can build from source by using the provided Dockerfile:

$ docker build -t odyn .
$ docker run --rm -it odyn --help

For documentation on how to use this package, please see the docs.

contributing

Pull requests that extend the supported services or introduce other improvements are welcome. Feel free to open an issue and discuss if you're unsure.

Documentation

Overview

Package odyn provides functionality to discover one's public IP address using a variety of services (providers).

Public IP address Providers

The services currently available to use through this package are ipify.org, ipinfo.io and opendns.com

The easiest approach is to simply:

ip, err := IpifyProvider.Get()

You can also use the HTTPProvider and DNSProvider to expand the functionality to further online services:

For example, to retrieve it over HTTP:

p, err := NewHTTPProvider("http://myip.example.com")
ip, err := p.Get()

The HTTPProvider and DNSProvider can be used to retrieve the public IP address from many different services since they're highly customisable. You can combine also them using ProviderSets:

ps, err := NewProviderSet(ProviderSetParallel, myHTTPProvider, myDNSProvider)
ip, err := ps.Get()

See the documentation on NewProviderSet for more information.

DNS Client

To request for an A record from a set of nameservers:

c := NewDNSClient()
ip, err := c.ResolveA("test.example.com", []string{"8.8.8.8"})

DNS Zone Providers

DNS providers are tasked with updating A records:

p, err := NewRoute53Zone()
err := p.UpdateA("test.example.com", "example.com.", net.ParseIP("1.2.3.4"))

Index

• Constants
• Variables
• type DNSClient
  • func NewDNSClient() *DNSClient
  • func (c *DNSClient) ResolveA(name string, nameservers []string) ([]net.IP, error)
• type DNSProvider
  • func NewDNSProvider(record string, nameservers []string) (*DNSProvider, error)
  • func (p DNSProvider) Get() (net.IP, error)
• type DNSZone
• type HTTPProvider
  • func NewHTTPProvider(u string) (*HTTPProvider, error)
  • func NewHTTPProviderWithOptions(options *HTTPProviderOptions) (*HTTPProvider, error)
  • func (p *HTTPProvider) Get() (net.IP, error)
• type HTTPProviderOptions
• type HTTPProviderRequester
• type HTTPProviderResponseParser
• type IPProvider
• type ProviderSet
  • func NewProviderSet(kind ProviderSetKind, providers ...IPProvider) (*ProviderSet, error)
  • func (p *ProviderSet) Get() (net.IP, error)
• type ProviderSetKind
• type Route53Zone
  • func NewRoute53Zone() (*Route53Zone, error)
  • func NewRoute53ZoneWithOptions(options *Route53ZoneOptions) (*Route53Zone, error)
  • func (p *Route53Zone) Nameservers(zoneName string) ([]string, error)
  • func (p *Route53Zone) UpdateA(recordName string, zoneName string, ip net.IP) error
• type Route53ZoneOptions

Constants

const (
	// ProviderSetSerial sets the ProviderSet mode to serial.
	ProviderSetSerial = ProviderSetKind(1)

	// ProviderSetParallel sets the ProviderSet mode to parallel.
	ProviderSetParallel = ProviderSetKind(2)
)

Variables

var (
	// IpifyProvider uses ipify.org to discover the public IP address.
	IpifyProvider, _ = NewHTTPProvider("https://api.ipify.org")

	// IPInfoProvider uses ipinfo.io to discover the public IP address.
	IPInfoProvider, _ = NewHTTPProviderWithOptions(&HTTPProviderOptions{
		URL:   "https://ipinfo.io",
		Parse: ipInfoParser,
		Headers: map[string]string{
			"Accept": "application/json",
		},
	})

	// OpenDNSProvider uses OpenDNS's nameservers to discover the public IP
	// address.
	OpenDNSProvider, _ = NewDNSProvider("myip.opendns.com.", []string{
		"208.67.222.222:53",
		"208.67.220.220:53",
		"208.67.222.220:53",
		"208.67.220.222:53",
	})
)

var (
	// ErrDNSProviderNoResults is returned when no results could be obtained
	// from the DNS nameservers.
	ErrDNSProviderNoResults = errors.New("dns provider returned no results")

	// ErrDNSProviderMultipleResults is returned when multiple different IP
	// addresses where obtained from the set of nameservers. In this case, the
	// provider will, however, return the first IP address instead of nil.
	ErrDNSProviderMultipleResults = errors.New("dns provider returned multiple different results")
)

var (
	// ErrHTTPProviderInvalidResponseCode is returned when the HTTP service
	// responds with a non 200 HTTP code.
	ErrHTTPProviderInvalidResponseCode = errors.New("provider responded with a non-200 status code")

	// ErrHTTPProviderCouldNotParseIP is returned when the provider is unable
	// to parse the IP address from the response body.
	ErrHTTPProviderCouldNotParseIP = errors.New("provider could not parse IP address from the response")

	// ErrHTTPProviderURLIsRequired is returned when trying to create an
	// HTTPProvider with a nil URL address.
	ErrHTTPProviderURLIsRequired = errors.New("the URL option is required")
)

var (
	// ErrProviderSetInvalidKind is returned when trying to create a new
	// ProviderSetor or querying using one with invalid kind set.
	ErrProviderSetInvalidKind = errors.New("invalid ProviderSet kind")

	// ErrProviderSetAllProvidersFailed is returned when all the providers in
	// the ProviderSet returned an error.
	ErrProviderSetAllProvidersFailed = errors.New("all the providers returned an error")

	// ErrProviderSetMultipleResults is returned when providers in a parallel
	// mode ProviderSet return different (conflicting) results.
	ErrProviderSetMultipleResults = errors.New("the providers returned multiple different results")
)

var (
	// ErrRoute53NoHostedZoneFound is returned when the Route53 DNS Zone provider
	// fails to find the Route53 Hosted Zone.
	ErrRoute53NoHostedZoneFound = errors.New("could not find a Route53 hosted zone")

	// ErrRoute53WatchTimedOut is returned when the update method times
	// out waiting to confirm that the change has been applied.
	ErrRoute53WatchTimedOut = errors.New("timed out")
)

var (
	// ErrDNSEmptyAnswer is returned when the DNS client receives an empty
	// response from the nameservers.
	ErrDNSEmptyAnswer = errors.New("DNS nameserver returned an empty answer")
)

Types

type DNSClient

type DNSClient struct {
	*dns.Client
}

DNSClient provides easy to use DNS resolving methods.

func NewDNSClient

func NewDNSClient() *DNSClient

NewDNSClient instantiates a new DNS client.

func (*DNSClient) ResolveA

func (c *DNSClient) ResolveA(name string, nameservers []string) ([]net.IP, error)

ResolveA will ask the provided nameservers for an A record of the provided DNS name and return the list of IP addresses in the answer, if any.

type DNSProvider

type DNSProvider struct {
	// contains filtered or unexported fields
}

DNSProvider sends queries to a DNS nameserver to discover the public IP address.

func NewDNSProvider

func NewDNSProvider(record string, nameservers []string) (*DNSProvider, error)

NewDNSProvider returns an instantiated DNSProvider.

func (DNSProvider) Get

func (p DNSProvider) Get() (net.IP, error)

Get performs a DNS query and returns the IP address in the answer.

type DNSZone

type DNSZone interface {
	UpdateA(recordName string, zoneName string, ip net.IP) error
	Nameservers(zoneName string) ([]string, error)
}

DNSZone is an interface for DNS Zone providers to implement.

type HTTPProvider

type HTTPProvider struct {
	// contains filtered or unexported fields
}

HTTPProvider is used to retrieve the IP address from any HTTP service.

func NewHTTPProvider

func NewHTTPProvider(u string) (*HTTPProvider, error)

NewHTTPProvider returns a basic HTTPProvider that can parse plaintext responses from a URL.

func NewHTTPProviderWithOptions

func NewHTTPProviderWithOptions(options *HTTPProviderOptions) (*HTTPProvider, error)

NewHTTPProviderWithOptions allows you to specify the HTTPProviderOptions and completely customise the behaviour.

func (*HTTPProvider) Get

func (p *HTTPProvider) Get() (net.IP, error)

Get will discover the public IP address using the HTTP service defined in the options of the HTTPProvider.

type HTTPProviderOptions

type HTTPProviderOptions struct {
	// Function to send the HTTP request to the service and return the response
	// body.
	Request HTTPProviderRequester

	// Function to parse the response body and return an IP address.
	Parse HTTPProviderResponseParser

	// HTTP Client used to send the GET request.
	Client *http.Client

	// HTTP Headers to set on the request
	Headers map[string]string

	// URL endpoint of the service.
	URL string
}

HTTPProviderOptions are used to alter the behaviour of the JSON IP Provider.

type HTTPProviderRequester

type HTTPProviderRequester func(options *HTTPProviderOptions) ([]byte, error)

HTTPProviderRequester is tasked with sending an HTTP request to the service ander returning the body of the response if the request was successful.

type HTTPProviderResponseParser

type HTTPProviderResponseParser func(body []byte) (net.IP, error)

HTTPProviderResponseParser is tasked with parsing the HTTP response body and returning an IP address.

type IPProvider

type IPProvider interface {
	Get() (net.IP, error)
}

IPProvider is an interface for IP providers to implement.

type ProviderSet

type ProviderSet struct {
	// contains filtered or unexported fields
}

ProviderSet combines multiple Providers to provide an easier way of handling results from multiple sources.

func NewProviderSet

func NewProviderSet(kind ProviderSetKind, providers ...IPProvider) (*ProviderSet, error)

NewProviderSet creates a new ProviderSet using the specified Providers. The kind argument dictates the method that the ProviderSet will use to extract the IP address:

ProviderSetSerial will use the providers in sequence and return the first successful result, ignoring the rest of the Providers.

ProviderSetParallel will query all the providers at once and ensure that they return the same result or return an error.

func (*ProviderSet) Get

func (p *ProviderSet) Get() (net.IP, error)

Get will use the providers to get the IP address.

type ProviderSetKind

type ProviderSetKind int64

ProviderSetKind represents the operational mode of a ProviderSet.

type Route53Zone

type Route53Zone struct {
	// contains filtered or unexported fields
}

Route53Zone is a DNS Zone provider based on the Amazon Web Services Route53 DNS service.

func NewRoute53Zone

func NewRoute53Zone() (*Route53Zone, error)

NewRoute53Zone returns a new instantiated Route53 DNS zone provider with default options.

func NewRoute53ZoneWithOptions

func NewRoute53ZoneWithOptions(options *Route53ZoneOptions) (*Route53Zone, error)

NewRoute53ZoneWithOptions returns a new instantiated Route53 DNS zone provider using the specified options.

func (*Route53Zone) Nameservers

func (p *Route53Zone) Nameservers(zoneName string) ([]string, error)

Nameservers returns the list of authoritative namservers for a DNS zone.

func (*Route53Zone) UpdateA

func (p *Route53Zone) UpdateA(recordName string, zoneName string, ip net.IP) error

UpdateA will set the Route53 A Record in the specified zone to point to the provided IP address.

type Route53ZoneOptions

type Route53ZoneOptions struct {
	TTL            int64
	SessionOptions session.Options
	API            route53iface.Route53API
	WatchInterval  time.Duration
	WatchTimeout   time.Duration
}

Route53ZoneOptions are used to alter the behaviour of the Route53 DNS zone provider.