15ffb0c9bSToomas Soome.\" -*- tab-width: 4 -*- 2a5934736SYuri Pankov.\" 35ffb0c9bSToomas Soome.\" Copyright (c) 2004 Apple Computer, Inc. All Rights Reserved. 4a5934736SYuri Pankov.\" 55ffb0c9bSToomas Soome.\" Licensed under the Apache License, Version 2.0 (the "License"); 65ffb0c9bSToomas Soome.\" you may not use this file except in compliance with the License. 75ffb0c9bSToomas Soome.\" You may obtain a copy of the License at 8a5934736SYuri Pankov.\" 95ffb0c9bSToomas Soome.\" http://www.apache.org/licenses/LICENSE-2.0 10a5934736SYuri Pankov.\" 115ffb0c9bSToomas Soome.\" Unless required by applicable law or agreed to in writing, software 125ffb0c9bSToomas Soome.\" distributed under the License is distributed on an "AS IS" BASIS, 135ffb0c9bSToomas Soome.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 145ffb0c9bSToomas Soome.\" See the License for the specific language governing permissions and 155ffb0c9bSToomas Soome.\" limitations under the License. 165ffb0c9bSToomas Soome.\" 175ffb0c9bSToomas Soome.\" Copyright 2016 Toomas Soome <tsoome@me.com> 185ffb0c9bSToomas Soome.\" 195ffb0c9bSToomas Soome.Dd Jan 28, 2016 \" Date 20*bbf21555SRichard Lowe.Dt DNS-SD 8 \" Document Title 215ffb0c9bSToomas Soome.Os illumos \" Operating System 225ffb0c9bSToomas Soome.\" 235ffb0c9bSToomas Soome.Sh NAME 245ffb0c9bSToomas Soome.Nm dns-sd 255ffb0c9bSToomas Soome.Nd Multicast DNS (mDNS) & DNS Service Discovery (DNS-SD) Test Tool \" For whatis 26a5934736SYuri Pankov.\" 275ffb0c9bSToomas Soome.Sh SYNOPSIS 285ffb0c9bSToomas Soome.Nm 295ffb0c9bSToomas Soome.Op Fl E 305ffb0c9bSToomas Soome.Pp 315ffb0c9bSToomas Soome.Nm 325ffb0c9bSToomas Soome.Op Fl F 335ffb0c9bSToomas Soome.Pp 345ffb0c9bSToomas Soome.Nm 355ffb0c9bSToomas Soome.Op Fl R Ar name type domain port Op Ar key=value ... 365ffb0c9bSToomas Soome.Pp 375ffb0c9bSToomas Soome.Nm 385ffb0c9bSToomas Soome.Op Fl B Ar type domain 395ffb0c9bSToomas Soome.Pp 405ffb0c9bSToomas Soome.Nm 415ffb0c9bSToomas Soome.Op Fl L Ar name type domain 425ffb0c9bSToomas Soome.Pp 435ffb0c9bSToomas Soome.Nm 445ffb0c9bSToomas Soome.Op Fl P Ar name type domain port host IP Op Ar key=value ... 455ffb0c9bSToomas Soome.Pp 465ffb0c9bSToomas Soome.Nm 475ffb0c9bSToomas Soome.Op Fl q Ar name rrtype rrclass 485ffb0c9bSToomas Soome.Pp 495ffb0c9bSToomas Soome.Nm 505ffb0c9bSToomas Soome.Op Fl Z Ar type domain 515ffb0c9bSToomas Soome.Pp 525ffb0c9bSToomas Soome.Nm 535ffb0c9bSToomas Soome.Op Fl G Ns \ v4/v6/v4v6 Ar name 545ffb0c9bSToomas Soome.Pp 555ffb0c9bSToomas Soome.Nm 565ffb0c9bSToomas Soome.Op Fl V 575ffb0c9bSToomas Soome.\" 585ffb0c9bSToomas Soome.Sh DESCRIPTION 595ffb0c9bSToomas SoomeThe 605ffb0c9bSToomas Soome.Nm 615ffb0c9bSToomas Soomecommand is a network diagnostic tool, much like 62*bbf21555SRichard Lowe.Xr ping 8 635ffb0c9bSToomas Soomeor 64*bbf21555SRichard Lowe.Xr traceroute 8 . 655ffb0c9bSToomas SoomeHowever, unlike those tools, most of its functionality is not implemented in the 665ffb0c9bSToomas Soome.Nm 675ffb0c9bSToomas Soomeexecutable itself, but in library code that is available to any application. 685ffb0c9bSToomas SoomeThe library API that 695ffb0c9bSToomas Soome.Nm 705ffb0c9bSToomas Soomeuses is documented in 715ffb0c9bSToomas Soome.Pa /usr/include/dns_sd.h . 725ffb0c9bSToomas SoomeThe 735ffb0c9bSToomas Soome.Nm 745ffb0c9bSToomas Soomecommand replaces the older 755ffb0c9bSToomas SoomemDNS 765ffb0c9bSToomas Soomecommand. 775ffb0c9bSToomas Soome.Pp 785ffb0c9bSToomas SoomeThe 795ffb0c9bSToomas Soome.Nm 805ffb0c9bSToomas Soomecommand is primarily intended for interactive use. 815ffb0c9bSToomas SoomeBecause its command-line arguments and output format are subject to change, 8272d3dbb9SYuri Pankovinvoking it from a shell script will generally be fragile. 8372d3dbb9SYuri PankovAdditionally, the asynchronous nature of DNS Service Discovery does 8472d3dbb9SYuri Pankovnot lend itself easily to script-oriented programming. 8572d3dbb9SYuri PankovFor example, calls like "browse" never complete; the action of performing a 8672d3dbb9SYuri Pankov"browse" sets in motion machinery to notify the client whenever instances of 8772d3dbb9SYuri Pankovthat service type appear or disappear from the network. 8872d3dbb9SYuri PankovThese notifications continue to be delivered indefinitely, for minutes, 895ffb0c9bSToomas Soomehours, or even days, as services come and go, until the client 9072d3dbb9SYuri Pankovexplicitly terminates the call. 9172d3dbb9SYuri PankovThis style of asynchronous interaction works best with applications that are 9272d3dbb9SYuri Pankoveither multi-threaded, or use a main event-handling loop to receive keystrokes, 9372d3dbb9SYuri Pankovnetwork data, and other asynchronous event notifications as they happen. 945ffb0c9bSToomas Soome.br 955ffb0c9bSToomas SoomeIf you wish to perform DNS Service Discovery operations from a 965ffb0c9bSToomas Soomescripting language, then the best way to do this is not to execute the 975ffb0c9bSToomas Soome.Nm 985ffb0c9bSToomas Soomecommand and then attempt to decipher the textual output, but instead to 995ffb0c9bSToomas Soomedirectly call the DNS-SD APIs using a binding for your chosen language. 1005ffb0c9bSToomas Soome.br 1015ffb0c9bSToomas SoomeFor example, if you are programming in Ruby, then you can 1025ffb0c9bSToomas Soomedirectly call DNS-SD APIs using the dnssd package documented at 1035ffb0c9bSToomas Soome.Pa <http://rubyforge.org/projects/dnssd/> . 1045ffb0c9bSToomas Soome.br 1055ffb0c9bSToomas SoomeSimilar bindings for other languages are also in development. 1065ffb0c9bSToomas Soome.Bl -tag -width E 1075ffb0c9bSToomas Soome.It Nm Fl E 1085ffb0c9bSToomas Soomereturn a list of domains recommended for registering(advertising) services. 1095ffb0c9bSToomas Soome.It Nm Fl F 1105ffb0c9bSToomas Soomereturn a list of domains recommended for browsing services. 1115ffb0c9bSToomas Soome.Pp 11272d3dbb9SYuri PankovNormally, on your home network, the only domain you are likely to see is 11372d3dbb9SYuri Pankov"local". 1145ffb0c9bSToomas SoomeHowever if your network administrator has created Domain Enumeration records, 1155ffb0c9bSToomas Soomethen you may also see other recommended domains for registering and browsing. 1165ffb0c9bSToomas Soome.It Nm Fl R Ar name type domain port Op Ar key=value ... 1175ffb0c9bSToomas Soomeregister (advertise) a service in the specified 1185ffb0c9bSToomas Soome.Ar domain 1195ffb0c9bSToomas Soomewith the given 1205ffb0c9bSToomas Soome.Ar name 1215ffb0c9bSToomas Soomeand 1225ffb0c9bSToomas Soome.Ar type 1235ffb0c9bSToomas Soomeas listening (on the current machine) on 1245ffb0c9bSToomas Soome.Ar port. 1255ffb0c9bSToomas Soome.Pp 1265ffb0c9bSToomas Soome.Ar name 1275ffb0c9bSToomas Soomecan be arbitrary unicode text, containing any legal unicode characters 1285ffb0c9bSToomas Soome(including dots, spaces, slashes, colons, etc. without restriction), 1295ffb0c9bSToomas Soomeup to 63 UTF-8 bytes long. 1305ffb0c9bSToomas Soome.Ar type 1315ffb0c9bSToomas Soomemust be of the form "_app-proto._tcp" or "_app-proto._udp", where 132c10c16deSRichard Lowe"app-proto" is an application protocol name registered at 1335ffb0c9bSToomas Soome.Pa http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml . 1345ffb0c9bSToomas Soome.Pp 1355ffb0c9bSToomas Soome.Ar domain 1365ffb0c9bSToomas Soomeis the domain in which to register the service. 1375ffb0c9bSToomas SoomeIn current implementations, only the local multicast domain "local" is 13872d3dbb9SYuri Pankovsupported. 13972d3dbb9SYuri PankovIn the future, registering will be supported in any arbitrary domain that has a 14072d3dbb9SYuri Pankovworking DNS Update server [RFC 2136]. 14172d3dbb9SYuri PankovThe 1425ffb0c9bSToomas Soome.Ar domain 1435ffb0c9bSToomas Soome"." is a synonym for "pick a sensible default" which today 1445ffb0c9bSToomas Soomemeans "local". 1455ffb0c9bSToomas Soome.Pp 1465ffb0c9bSToomas Soome.Ar port 1475ffb0c9bSToomas Soomeis a number from 0 to 65535, and is the TCP or UDP port number upon 1485ffb0c9bSToomas Soomewhich the service is listening. 1495ffb0c9bSToomas Soome.Pp 150c10c16deSRichard LoweAdditional attributes of the service may optionally be described by 1515ffb0c9bSToomas Soomekey/value pairs, which are stored in the advertised service's DNS TXT 15272d3dbb9SYuri Pankovrecord. 15372d3dbb9SYuri PankovAllowable keys and values are listed with the service registration at 1545ffb0c9bSToomas Soome.Pa http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml . 1555ffb0c9bSToomas Soome.It Nm Fl B Ar type domain 1565ffb0c9bSToomas Soomebrowse for instances of service 1575ffb0c9bSToomas Soome.Ar type 1585ffb0c9bSToomas Soomein 1595ffb0c9bSToomas Soome.Ar domain . 1605ffb0c9bSToomas Soome.Pp 1615ffb0c9bSToomas SoomeFor valid 1625ffb0c9bSToomas Soome.Ar type Ns s 1635ffb0c9bSToomas Soomesee 1645ffb0c9bSToomas Soome.Pa http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml . 16572d3dbb9SYuri Pankovas described above. 16672d3dbb9SYuri PankovOmitting the 1675ffb0c9bSToomas Soome.Ar domain 1685ffb0c9bSToomas Soomeor using "." means "pick a sensible default." 1695ffb0c9bSToomas Soome.It Nm Fl L Ar name type domain 1705ffb0c9bSToomas Soomelook up and display the information necessary to contact and use the 1715ffb0c9bSToomas Soomenamed service: the hostname of the machine where that service is 1725ffb0c9bSToomas Soomeavailable, the port number on which the service is listening, and (if 1735ffb0c9bSToomas Soomepresent) TXT record attributes describing properties of the service. 1745ffb0c9bSToomas Soome.Pp 17572d3dbb9SYuri PankovNote that in a typical application, browsing may only happen rarely, while 17672d3dbb9SYuri Pankovlookup (or "resolving") happens every time the service is used. 17772d3dbb9SYuri PankovFor example, a user browses the network to pick a default printer fairly rarely, 17872d3dbb9SYuri Pankovbut once a default printer has been picked, that named service is resolved to 17972d3dbb9SYuri Pankovits current IP address and port number every time the user presses Cmd-P to 1805ffb0c9bSToomas Soomeprint. 1815ffb0c9bSToomas Soome.It Nm Fl P Ar name type domain port host IP Op Ar key=value ... 18272d3dbb9SYuri Pankovcreate a proxy advertisement for a service running on(offered by) some other 18372d3dbb9SYuri Pankovmachine. 1845ffb0c9bSToomas SoomeThe two new options are Host, a name for the device and IP, the address of it. 1855ffb0c9bSToomas Soome.Pp 18672d3dbb9SYuri PankovThe service for which you create a proxy advertisement does not necessarily have 18772d3dbb9SYuri Pankovto be on your local network. 1885ffb0c9bSToomas SoomeYou can set up a local proxy for a website on the Internet. 1895ffb0c9bSToomas Soome.It Nm Fl q Ar name rrtype rrclass 1905ffb0c9bSToomas Soomelook up any DNS name, resource record type, and resource record class, 1915ffb0c9bSToomas Soomenot necessarily DNS-SD names and record types. 1925ffb0c9bSToomas SoomeIf rrtype is not specified, it queries for the IPv4 address of the name, 19372d3dbb9SYuri Pankovif rrclass is not specified, IN class is assumed. 19472d3dbb9SYuri PankovIf the name is not a fully qualified domain name, then search domains may be 19572d3dbb9SYuri Pankovappended. 1965ffb0c9bSToomas Soome.It Nm Fl Z Ar type domain 1975ffb0c9bSToomas Soomebrowse for service instances and display output in zone file format. 1985ffb0c9bSToomas Soome.It Nm Fl G Ns \ v4/v6/v4v6 Ar name 1995ffb0c9bSToomas Soomelook up the IP address information of the name. 2005ffb0c9bSToomas SoomeIf v4 is specified, the IPv4 address of the name is looked up, 20172d3dbb9SYuri Pankovif v6 is specified the IPv6 address is looked up. 20272d3dbb9SYuri PankovIf v4v6 is specified both the IPv4 and IPv6 address is looked up. 20372d3dbb9SYuri PankovIf the name is not a fully qualified domain name, then search domains may be 20472d3dbb9SYuri Pankovappended. 2055ffb0c9bSToomas Soome.It Nm Fl V 2065ffb0c9bSToomas Soomereturn the version of the currently running daemon/system service. 2075ffb0c9bSToomas Soome.El 2085ffb0c9bSToomas Soome.Sh FILES 2095ffb0c9bSToomas Soome.Pa /usr/bin/dns-sd \" Pathname 2105ffb0c9bSToomas Soome.\" 2115ffb0c9bSToomas Soome.Sh EXAMPLES 2125ffb0c9bSToomas SoomeTo advertise the existence of LPR printing service on port 515 on this 2135ffb0c9bSToomas Soomemachine, such that it will be discovered by the Mac OS X printing software 2145ffb0c9bSToomas Soomeand other DNS-SD compatible printing clients, use: 2155ffb0c9bSToomas Soome.Pp 2165ffb0c9bSToomas Soome.Dl Nm Fl R Ns \ \&"My Test\&" _printer._tcp. \&. 515 pdl=application/postscript 2175ffb0c9bSToomas Soome.Pp 2185ffb0c9bSToomas SoomeFor this registration to be useful, you need to actually have LPR service 21972d3dbb9SYuri Pankovavailable on port 515. 22072d3dbb9SYuri PankovAdvertising a service that does not exist is not very useful, and will be 22172d3dbb9SYuri Pankovconfusing and annoying to other people on the network. 2225ffb0c9bSToomas Soome.Pp 2235ffb0c9bSToomas SoomeSimilarly, to advertise a web page being served by an HTTP 2245ffb0c9bSToomas Soomeserver on port 80 on this machine, such that it will show up in the 2255ffb0c9bSToomas SoomeBonjour list in Safari and other DNS-SD compatible Web clients, use: 2265ffb0c9bSToomas Soome.Pp 2275ffb0c9bSToomas Soome.Dl Nm Fl R Ns \ \&"My Test\&" _http._tcp \&. 80 path=/path-to-page.html 2285ffb0c9bSToomas Soome.Pp 2295ffb0c9bSToomas SoomeTo find the advertised web pages on the local network (the same list that 2305ffb0c9bSToomas SoomeSafari shows), use: 2315ffb0c9bSToomas Soome.Pp 2325ffb0c9bSToomas Soome.Dl Nm Fl B Ns \ _http._tcp 2335ffb0c9bSToomas Soome.Pp 2345ffb0c9bSToomas SoomeWhile that command is running, in another window, try the 2355ffb0c9bSToomas Soome.Nm Fl R 2365ffb0c9bSToomas Soomeexample given above to advertise a web page, and you should see the 2375ffb0c9bSToomas Soome"Add" event reported to the 2385ffb0c9bSToomas Soome.Nm Fl B 23972d3dbb9SYuri Pankovwindow. 24072d3dbb9SYuri PankovNow press Ctrl-C in the 2415ffb0c9bSToomas Soome.Nm Fl R 2425ffb0c9bSToomas Soomewindow and you should see the "Remove" event reported to the 2435ffb0c9bSToomas Soome.Nm Fl B 2445ffb0c9bSToomas Soomewindow. 2455ffb0c9bSToomas Soome.Pp 24672d3dbb9SYuri PankovIn the example below, the www.apple.com web page is advertised as a service 24772d3dbb9SYuri Pankovcalled "apple", 2485ffb0c9bSToomas Soomerunning on a target host called apple.local, which resolves to 17.149.160.49. 2495ffb0c9bSToomas Soome.Pp 2505ffb0c9bSToomas Soome.Dl Nm Fl P Ns \ apple _http._tcp \&"\&"\& 80 apple.local 17.149.160.49 2515ffb0c9bSToomas Soome.Pp 2525ffb0c9bSToomas SoomeThe Bonjour menu in the Safari web browser will now show "apple". 2535ffb0c9bSToomas SoomeThe same IP address can be reached by entering apple.local in the web browser. 25472d3dbb9SYuri PankovIn either case, the request will be resolved to the IP address and browser will 25572d3dbb9SYuri Pankovshow contents associated with www.apple.com. 2565ffb0c9bSToomas Soome.Pp 2575ffb0c9bSToomas SoomeIf a client wants to be notified of changes in server state, it can 2585ffb0c9bSToomas Soomeinitiate a query for the service's particular record and leave it running. 2595ffb0c9bSToomas SoomeFor example, to monitor the status of an iChat user you can use: 2605ffb0c9bSToomas Soome.Pp 2615ffb0c9bSToomas Soome.Dl Nm Fl q Ns \ someone@ex1._presence._tcp.local txt 2625ffb0c9bSToomas Soome.Pp 26372d3dbb9SYuri PankovEverytime status of that user(someone) changes, you will see a new TXT record 26472d3dbb9SYuri Pankovresult reported. 2655ffb0c9bSToomas Soome.Pp 2665ffb0c9bSToomas SoomeYou can also query for a unicast name like www.apple.com and monitor its status. 2675ffb0c9bSToomas Soome.Pp 2685ffb0c9bSToomas Soome.Dl Nm Fl q Ns \ www.apple.com 2695ffb0c9bSToomas Soome.Sh INTERFACE STABILITY 2705ffb0c9bSToomas Soome.Sy Volatile . 2715ffb0c9bSToomas Soome.Sh SEE ALSO 272*bbf21555SRichard Lowe.Xr resolv.conf 5 , 273*bbf21555SRichard Lowe.Xr mdnsd 8 , 274*bbf21555SRichard Lowe.Xr ping 8 , 275*bbf21555SRichard Lowe.Xr traceroute 8 276