1.\" -*- tab-width: 4 -*- 2.\" 3.\" Copyright (c) 2004-2012 Apple Inc. All Rights Reserved. 4.\" 5.\" Licensed under the Apache License, Version 2.0 (the "License"); 6.\" you may not use this file except in compliance with the License. 7.\" You may obtain a copy of the License at 8.\" 9.\" http://www.apache.org/licenses/LICENSE-2.0 10.\" 11.\" Unless required by applicable law or agreed to in writing, software 12.\" distributed under the License is distributed on an "AS IS" BASIS, 13.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14.\" See the License for the specific language governing permissions and 15.\" limitations under the License. 16.\" 17.Dd April 2004 \" Date 18.Dt dns-sd 1 \" Document Title 19.Os Darwin \" Operating System 20.\" 21.Sh NAME 22.Nm dns-sd 23.Nd Multicast DNS (mDNS) & DNS Service Discovery (DNS-SD) Test Tool \" For whatis 24.\" 25.Sh SYNOPSIS 26.Nm Fl E 27.Pp 28.Nm Fl F 29.Pp 30.Nm Fl R Ar name type domain port Op Ar key=value ... 31.Pp 32.Nm Fl B Ar type domain 33.Pp 34.Nm Fl L Ar name type domain 35.Pp 36.Nm Fl P Ar name type domain port host IP Op Ar key=value ... 37.Pp 38.Nm Fl q Ar name rrtype rrclass 39.Pp 40.Nm Fl Z Ar type domain 41.Pp 42.Nm Fl G Ns \ v4/v6/v4v6 Ar name 43.Pp 44.Nm Fl V 45.\" 46.Sh DESCRIPTION 47The 48.Nm 49command is a network diagnostic tool, much like 50.Xr ping 8 51or 52.Xr traceroute 8 . 53However, unlike those tools, most of its functionality is not implemented in the 54.Nm 55executable itself, but in library code that is available to any application. 56The library API that 57.Nm 58uses is documented in 59.Pa /usr/include/dns_sd.h . 60The 61.Nm 62command replaces the older 63mDNS 64command. 65.Pp 66The 67.Nm 68command is primarily intended for interactive use. 69Because its command-line arguments and output format are subject to change, 70invoking it from a shell script will generally be fragile. Additionally, 71the asynchronous nature of DNS Service Discovery does 72not lend itself easily to script-oriented programming. For example, 73calls like "browse" never complete; the action of performing a "browse" 74sets in motion machinery to notify the client whenever instances of 75that service type appear or disappear from the network. These 76notifications continue to be delivered indefinitely, for minutes, 77hours, or even days, as services come and go, until the client 78explicitly terminates the call. This style of asynchronous interaction 79works best with applications that are either multi-threaded, or use a 80main event-handling loop to receive keystrokes, network data, and other 81asynchronous event notifications as they happen. 82.br 83If you wish to perform DNS Service Discovery operations from a 84scripting language, then the best way to do this is not to execute the 85.Nm 86command and then attempt to decipher the textual output, but instead to 87directly call the DNS-SD APIs using a binding for your chosen language. 88.br 89For example, if you are programming in Ruby, then you can 90directly call DNS-SD APIs using the dnssd package documented at 91.Pa <http://rubyforge.org/projects/dnssd/> . 92.br 93Similar bindings for other languages are also in development. 94.Pp 95.Bl -tag -width E 96.It Nm Fl E 97return a list of domains recommended for registering(advertising) services. 98.Pp 99.It Nm Fl F 100return a list of domains recommended for browsing services. 101.Pp 102Normally, on your home network, the only domain you are likely to see is "local". 103However if your network administrator has created Domain Enumeration records, 104then you may also see other recommended domains for registering and browsing. 105.Pp 106.It Nm Fl R Ar name type domain port Op Ar key=value ... 107register (advertise) a service in the specified 108.Ar domain 109with the given 110.Ar name 111and 112.Ar type 113as listening (on the current machine) on 114.Ar port. 115.Pp 116.Ar name 117can be arbitrary unicode text, containing any legal unicode characters 118(including dots, spaces, slashes, colons, etc. without restriction), 119up to 63 UTF-8 bytes long. 120.Ar type 121must be of the form "_app-proto._tcp" or "_app-proto._udp", where 122"app-proto" is an application protocol name registered at 123.Pa http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml . 124.Pp 125.Ar domain 126is the domain in which to register the service. 127In current implementations, only the local multicast domain "local" is 128supported. In the future, registering will be supported in any arbitrary 129domain that has a working DNS Update server [RFC 2136]. The 130.Ar domain 131"." is a synonym for "pick a sensible default" which today 132means "local". 133.Pp 134.Ar port 135is a number from 0 to 65535, and is the TCP or UDP port number upon 136which the service is listening. 137.Pp 138Additional attributes of the service may optionally be described by 139key/value pairs, which are stored in the advertised service's DNS TXT 140record. Allowable keys and values are listed with the service 141registration at 142.Pa http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml . 143.It Nm Fl B Ar type domain 144browse for instances of service 145.Ar type 146in 147.Ar domain . 148.Pp 149For valid 150.Ar type Ns s 151see 152.Pa http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml . 153as described above. Omitting the 154.Ar domain 155or using "." means "pick a sensible default." 156.It Nm Fl L Ar name type domain 157look up and display the information necessary to contact and use the 158named service: the hostname of the machine where that service is 159available, the port number on which the service is listening, and (if 160present) TXT record attributes describing properties of the service. 161.Pp 162Note that in a typical application, browsing may only happen rarely, while lookup 163(or "resolving") happens every time the service is used. For example, a 164user browses the network to pick a default printer fairly rarely, but once 165a default printer has been picked, that named service is resolved to its 166current IP address and port number every time the user presses Cmd-P to 167print. 168.Pp 169.It Nm Fl P Ar name type domain port host IP Op Ar key=value ... 170create a proxy advertisement for a service running on(offered by) some other machine. 171The two new options are Host, a name for the device and IP, the address of it. 172.Pp 173The service for which you create a proxy advertisement does not necessarily have to be on your local network. 174You can set up a local proxy for a website on the Internet. 175.Pp 176.It Nm Fl q Ar name rrtype rrclass 177look up any DNS name, resource record type, and resource record class, 178not necessarily DNS-SD names and record types. 179If rrtype is not specified, it queries for the IPv4 address of the name, 180if rrclass is not specified, IN class is assumed. If the name is not a fully 181qualified domain name, then search domains may be appended. 182.Pp 183.It Nm Fl Z Ar type domain 184browse for service instances and display output in zone file format. 185.Pp 186.It Nm Fl G Ns \ v4/v6/v4v6 Ar name 187look up the IP address information of the name. 188If v4 is specified, the IPv4 address of the name is looked up, 189if v6 is specified the IPv6 address is looked up. If v4v6 is specified both the IPv4 and IPv6 190address is looked up. If the name is not a fully qualified domain name, 191then search domains may be appended. 192.Pp 193.It Nm Fl V 194return the version of the currently running daemon/system service. 195.El 196.Sh EXAMPLES 197.Pp 198To advertise the existence of LPR printing service on port 515 on this 199machine, such that it will be discovered by the Mac OS X printing software 200and other DNS-SD compatible printing clients, use: 201.Pp 202.Dl Nm Fl R Ns \ \&"My Test\&" _printer._tcp. \&. 515 pdl=application/postscript 203.Pp 204For this registration to be useful, you need to actually have LPR service 205available on port 515. Advertising a service that does not exist is not 206very useful, and will be confusing and annoying to other people on the 207network. 208.Pp 209Similarly, to advertise a web page being served by an HTTP 210server on port 80 on this machine, such that it will show up in the 211Bonjour list in Safari and other DNS-SD compatible Web clients, use: 212.Pp 213.Dl Nm Fl R Ns \ \&"My Test\&" _http._tcp \&. 80 path=/path-to-page.html 214.Pp 215To find the advertised web pages on the local network (the same list that 216Safari shows), use: 217.Pp 218.Dl Nm Fl B Ns \ _http._tcp 219.Pp 220While that command is running, in another window, try the 221.Nm Fl R 222example given above to advertise a web page, and you should see the 223"Add" event reported to the 224.Nm Fl B 225window. Now press Ctrl-C in the 226.Nm Fl R 227window and you should see the "Remove" event reported to the 228.Nm Fl B 229window. 230.Pp 231In the example below, the www.apple.com web page is advertised as a service called "apple", 232running on a target host called apple.local, which resolves to 17.149.160.49. 233.Pp 234.Dl Nm Fl P Ns \ apple _http._tcp \&"\&"\& 80 apple.local 17.149.160.49 235.Pp 236The Bonjour menu in the Safari web browser will now show "apple". 237The same IP address can be reached by entering apple.local in the web browser. 238In either case, the request will be resolved to the IP address and browser will show 239contents associated with www.apple.com. 240.Pp 241If a client wants to be notified of changes in server state, it can 242initiate a query for the service's particular record and leave it running. 243For example, to monitor the status of an iChat user you can use: 244.Pp 245.Dl Nm Fl q Ns \ someone@ex1._presence._tcp.local txt 246.Pp 247Everytime status of that user(someone) changes, you will see a new TXT record result reported. 248.Pp 249You can also query for a unicast name like www.apple.com and monitor its status. 250.Pp 251.Dl Nm Fl q Ns \ www.apple.com 252.Pp 253.Sh FILES 254.Pa /usr/bin/dns-sd \" Pathname 255.\" 256.Sh SEE ALSO 257.Xr mDNSResponder 8 258.\" 259.Sh BUGS 260.Nm 261bugs are tracked in Apple Radar component "mDNSResponder". 262.\" 263.Sh HISTORY 264The 265.Nm 266command first appeared in Mac OS X 10.4 (Tiger). 267