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 compliant 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/libp2p/zeroconf

Browse for services in your local network

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()
// Discover all services on the network (e.g. _workstation._tcp)
err = zeroconf.Browse(ctx, "_workstation._tcp", "local.", entries)
if err != nil {
    log.Fatalln("Failed to browse:", err.Error())
}

<-ctx.Done()

A subtype may added to service name to narrow the set of results. E.g. to browse _workstation._tcp with subtype _windows, use_workstation._tcp,_windows.

See https://github.com/libp2p/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.")

Multiple subtypes may be added to service name, separated by commas. E.g _workstation._tcp,_windows has subtype _windows.

See https://github.com/libp2p/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 features might not be perfectly standards compliant, but shouldn't cause any problems. Some tests showed improvements in overall robustness and performance with the features enabled.

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 Browse(ctx context.Context, service, domain string, entries chan<- *ServiceEntry, ...) error
• func Lookup(ctx context.Context, instance, service, domain string, ...) error
• type ClientOption
  • func SelectIPTraffic(t IPType) ClientOption
  • func SelectIfaces(ifaces []net.Interface) ClientOption
• type IPType
• 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 (s *Server) SetText(text []string)
  • func (s *Server) Shutdown()
  • func (s *Server) TTL(ttl uint32)
• type ServiceEntry
  • func NewServiceEntry(instance, service string, domain string) *ServiceEntry
• type ServiceRecord
  • func NewServiceRecord(instance, service string, 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 Browse

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

Browse for all services of a given type in a given domain. Received entries are sent on the entries channel. It blocks until the context is canceled (or an error occurs).

func Lookup

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

Lookup a specific service by its name and type in a given domain. Received entries are sent on the entries channel. It blocks until the context is canceled (or an error occurs).

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 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 (*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
	Expiry   time.Time `json:"expiry"`   // Expiry of the service entry, will be converted to a TTL value
	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 string, 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.)
	Subtypes []string `json:"subtypes"` // Service subtypes
	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 string, 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.