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 ¶
const ( IPv4 = 0x01 IPv6 = 0x02 IPv4AndIPv6 = (IPv4 | IPv6) //< Default option. )
Options for IPType.
Variables ¶
var (
DefaultTTL uint32 = 3200
)
Functions ¶
This section is empty.
Types ¶
type Browser ¶
type Browser struct {
// contains filtered or unexported fields
}
Browser is reference to an instance of browser
func (*Browser) Entries ¶
func (b *Browser) Entries() []ServiceEntry
Entries returns the current cache
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.
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.
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
// contains filtered or unexported fields
}
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.
func (*ServiceEntry) EventType ¶
func (s *ServiceEntry) EventType() ServiceEventType
EventType returns the type of event that happened to ServiceEntry
type ServiceEventType ¶
type ServiceEventType string
ServiceEventType is type of event happening on a service
const ( // NewOrUpdated service instance NewOrUpdated ServiceEventType = "NewOrUpdated" // Removed notifies when an instance is going away Removed ServiceEventType = "Removed" )
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.
Source Files
Directories