zeroconf

README

ZeroConf: Service Discovery with mDNS

ZeroConf is a pure Golang library that employs Multicast DNS-SD for

• browsing and resolving services in your network
• registering own services

in the local network.

It basically implements aspects of the standards RFC 6762 (mDNS) and RFC 6763 (DNS-SD). Though it does not support all requirements yet, the aim is to provide a complient solution in the long-term with the community.

By now, it should be compatible to Avahi (tested) and Apple's Bonjour (untested). Target environments: private LAN/Wifi, small or isolated networks.

Install

Nothing is as easy as that:

$ go get -u github.com/grandcat/zeroconf

This package requires Go 1.7 (context in std lib) or later.

Browse for services in your local network

// Discover all services on the network (e.g. _workstation._tcp)
resolver, err := zeroconf.NewResolver(nil)
if err != nil {
    log.Fatalln("Failed to initialize resolver:", err.Error())
}

entries := make(chan *zeroconf.ServiceEntry)
go func(results <-chan *zeroconf.ServiceEntry) {
    for entry := range results {
        log.Println(entry)
    }
    log.Println("No more entries.")
}(entries)

ctx, cancel := context.WithTimeout(context.Background(), time.Second*15)
defer cancel()
err = resolver.Browse(ctx, "_workstation._tcp", "local.", entries)
if err != nil {
    log.Fatalln("Failed to browse:", err.Error())
}

<-ctx.Done()

See https://github.com/grandcat/zeroconf/blob/master/examples/resolv/client.go.

Lookup a specific service instance

// Example filled soon.

Register a service

server, err := zeroconf.Register("GoZeroconf", "_workstation._tcp", "local.", 42424, []string{"txtv=0", "lo=1", "la=2"}, nil)
if err != nil {
    panic(err)
}
defer server.Shutdown()

// Clean exit.
sig := make(chan os.Signal, 1)
signal.Notify(sig, os.Interrupt, syscall.SIGTERM)
select {
case <-sig:
    // Exit by user
case <-time.After(time.Second * 120):
    // Exit by timeout
}

log.Println("Shutting down.")

See https://github.com/grandcat/zeroconf/blob/master/examples/register/server.go.

Features and ToDo's

This list gives a quick impression about the state of this library. See what needs to be done and submit a pull request :)

• Browse / Lookup / Register services
• Multiple IPv6 / IPv4 addresses support
• Send multiple probes (exp. back-off) if no service answers (*)
• Timestamp entries for TTL checks
• Compare new multicasts with already received services

Notes:

(*) The denoted functionalities might not be 100% standard conform, but should not be a deal breaker. Some test scenarios demonstrated that the overall robustness and performance increases when applying the suggested improvements.

Credits

Great thanks to hashicorp and to oleksandr and all contributing authors for the code this projects bases upon. Large parts of the code are still the same.

However, there are several reasons why I decided to create a fork of the original project: The previous project seems to be unmaintained. There are several useful pull requests waiting. I merged most of them in this project. Still, the implementation has some bugs and lacks some other features that make it quite unreliable in real LAN environments when running continously. Last but not least, the aim for this project is to build a solution that targets standard conformance in the long term with the support of the community. Though, resiliency should remain a top goal.

Documentation

Overview

Package zeroconf is a pure Golang library that employs Multicast DNS-SD for browsing and resolving services in your network and registering own services in the local network.

It basically implements aspects of the standards RFC 6762 (mDNS) and RFC 6763 (DNS-SD). Though it does not support all requirements yet, the aim is to provide a complient solution in the long-term with the community.

By now, it should be compatible to [Avahi](http://avahi.org/) (tested) and Apple's Bonjour (untested). Should work in the most office, home and private environments.

Index

• Constants
• func OverrideLogging(errout logOutLn, infoout logOutLn, debugout logOutLn)
• type ClientOption
  • func SelectIPTraffic(t IPType) ClientOption
  • func SelectIfaces(ifaces []net.Interface) ClientOption
• type IPType
• type LookupParams
  • func NewLookupParams(instance, service, domain string, entries chan<- *ServiceEntry) *LookupParams
• type Resolver
  • func NewResolver(options ...ClientOption) (*Resolver, error)
  • func (r *Resolver) Browse(ctx context.Context, service, domain string, entries chan<- *ServiceEntry) error
  • func (r *Resolver) Lookup(ctx context.Context, instance, service, domain string, ...) error
• type Server
  • func Register(instance, service, domain string, port int, text []string, ...) (*Server, error)
  • func RegisterProxy(instance, service, domain string, port int, host string, ips []string, ...) (*Server, error)
  • func RegisterServiceEntry(entry *ServiceEntry, ips []string, ifaces []string, notIfaces []string) (*Server, error)
  • func RegisterServiceEntryEachInterfaceIP(entry *ServiceEntry, ifaces []string, notIfaces []string) (servers []*Server, err error)
  • func (s *Server) SetText(text []string)
  • func (s *Server) Shutdown()
  • func (s *Server) TTL(ttl uint32)
• type ServiceEntry
  • func NewServiceEntry(instance, service, domain string) *ServiceEntry
• type ServiceRecord
  • func NewServiceRecord(instance, service, domain string) *ServiceRecord
  • func (s *ServiceRecord) ServiceInstanceName() string
  • func (s *ServiceRecord) ServiceName() string
  • func (s *ServiceRecord) ServiceTypeName() string

Constants

const (
	IPv4        = 0x01
	IPv6        = 0x02
	IPv4AndIPv6 = (IPv4 | IPv6) //< Default option.
)

Options for IPType.

Functions

func OverrideLogging

func OverrideLogging(errout logOutLn, infoout logOutLn, debugout logOutLn)

OverrideLogging gives us a way to override where we are spewing errors.

Types

type ClientOption

type ClientOption func(*clientOpts)

ClientOption fills the option struct to configure intefaces, etc.

func SelectIPTraffic

func SelectIPTraffic(t IPType) ClientOption

SelectIPTraffic selects the type of IP packets (IPv4, IPv6, or both) this instance listens for. This does not guarantee that only mDNS entries of this sepcific type passes. E.g. typical mDNS packets distributed via IPv4, may contain both DNS A and AAAA entries.

func SelectIfaces

func SelectIfaces(ifaces []net.Interface) ClientOption

SelectIfaces selects the interfaces to query for mDNS records

type IPType

type IPType uint8

IPType specifies the IP traffic the client listens for. This does not guarantee that only mDNS entries of this sepcific type passes. E.g. typical mDNS packets distributed via IPv4, often contain both DNS A and AAAA entries.

type LookupParams

type LookupParams struct {
	ServiceRecord
	Entries chan<- *ServiceEntry // Entries Channel
	// contains filtered or unexported fields
}

LookupParams contains configurable properties to create a service discovery request

func NewLookupParams

func NewLookupParams(instance, service, domain string, entries chan<- *ServiceEntry) *LookupParams

NewLookupParams constructs a LookupParams.

type Resolver

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

Resolver acts as entry point for service lookups and to browse the DNS-SD.

func NewResolver

func NewResolver(options ...ClientOption) (*Resolver, error)

NewResolver creates a new resolver and joins the UDP multicast groups to listen for mDNS messages.

func (*Resolver) Browse

func (r *Resolver) Browse(ctx context.Context, service, domain string, entries chan<- *ServiceEntry) error

Browse for all services of a given type in a given domain.

func (*Resolver) Lookup

func (r *Resolver) Lookup(ctx context.Context, instance, service, domain string, entries chan<- *ServiceEntry) error

Lookup a specific service by its name and type in a given domain.

type Server

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

Server structure encapsulates both IPv4/IPv6 UDP connections

func Register

func Register(instance, service, domain string, port int, text []string, ifaces []net.Interface) (*Server, error)

Register a service by given arguments. This call will take the system's hostname and lookup IP by that hostname.

func RegisterProxy

func RegisterProxy(instance, service, domain string, port int, host string, ips []string, text []string, ifaces []net.Interface) (*Server, error)

RegisterProxy registers a service proxy. This call will skip the hostname/IP lookup and will use the provided values.

func RegisterServiceEntry

func RegisterServiceEntry(entry *ServiceEntry, ips []string, ifaces []string, notIfaces []string) (*Server, error)

RegisterServiceEntry let's you register a service by handing in a raw ServiceEntry struct for better flexibility, along with string array of ips to publish and intefaces to run the server on. notIfaces lets you black list specific interface to not publish to

func RegisterServiceEntryEachInterfaceIP

func RegisterServiceEntryEachInterfaceIP(entry *ServiceEntry, ifaces []string, notIfaces []string) (servers []*Server, err error)

RegisterServiceEntryEachInterfaceIP publishes the service entry to each interface separately, using each interfaces assigned IP address. If ifaces is empty, it will go through all network interfaces except loopback.

func (*Server) SetText

func (s *Server) SetText(text []string)

SetText updates and announces the TXT records

func (*Server) Shutdown

func (s *Server) Shutdown()

Shutdown closes all udp connections and unregisters the service

func (*Server) TTL

func (s *Server) TTL(ttl uint32)

TTL sets the TTL for DNS replies

type ServiceEntry

type ServiceEntry struct {
	ServiceRecord
	HostName string   `json:"hostname"` // Host machine DNS name
	Port     int      `json:"port"`     // Service Port
	Text     []string `json:"text"`     // Service info served as a TXT record
	TTL      uint32   `json:"ttl"`      // TTL of the service record
	AddrIPv4 []net.IP `json:"-"`        // Host machine IPv4 address
	AddrIPv6 []net.IP `json:"-"`        // Host machine IPv6 address
}

ServiceEntry represents a browse/lookup result for client API. It is also used to configure service registration (server API), which is used to answer multicast queries.

func NewServiceEntry

func NewServiceEntry(instance, service, domain string) *ServiceEntry

NewServiceEntry constructs a ServiceEntry.

type ServiceRecord

type ServiceRecord struct {
	Instance string `json:"name"`   // Instance name (e.g. "My web page")
	Service  string `json:"type"`   // Service name (e.g. _http._tcp.)
	Domain   string `json:"domain"` // If blank, assumes "local"
	// contains filtered or unexported fields
}

ServiceRecord contains the basic description of a service, which contains instance name, service type & domain

func NewServiceRecord

func NewServiceRecord(instance, service, domain string) *ServiceRecord

NewServiceRecord constructs a ServiceRecord.

func (*ServiceRecord) ServiceInstanceName

func (s *ServiceRecord) ServiceInstanceName() string

ServiceInstanceName returns a complete service instance name (e.g. MyDemo\ Service._foobar._tcp.local.), which is composed from service instance name, service name and a domain.

func (*ServiceRecord) ServiceName

func (s *ServiceRecord) ServiceName() string

ServiceName returns a complete service name (e.g. _foobar._tcp.local.), which is composed of a service name (also referred as service type) and a domain.

func (*ServiceRecord) ServiceTypeName

func (s *ServiceRecord) ServiceTypeName() string

ServiceTypeName returns the complete identifier for a DNS-SD query.