1.\" -*- tab-width: 4 -*- 2.\" 3.\" Copyright (c) 2004 Apple Computer, 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.\" Log: dns-sd.1,v $ 18.\" Revision 1.6 2006/08/14 23:24:56 cheshire 19.\" Re-licensed mDNSResponder daemon source code under Apache License, Version 2.0 20.\" 21.\" Revision 1.5 2005/07/04 23:12:35 cheshire 22.\" <rdar://problem/4103628> The dns-sd command first appeared in Mac OS X 10.4 (Tiger) 23.\" 24.\" Revision 1.4 2005/02/16 02:29:32 cheshire 25.\" Update terminology 26.\" 27.\" Revision 1.3 2005/02/10 22:35:28 cheshire 28.\" <rdar://problem/3727944> Update name 29.\" 30.\" Revision 1.2 2004/09/24 18:33:05 cheshire 31.\" <rdar://problem/3561780> Update man pages to clarify that mDNS and dns-sd are not intended for script use 32.\" 33.\" Revision 1.1 2004/09/22 22:46:25 cheshire 34.\" Man page for dns-sd command-line tool 35.\" 36.\" 37.\" 38.Dd April 2004 \" Date 39.Dt dns-sd 1 \" Document Title 40.Os NetBSD \" Operating System 41.\" 42.Sh NAME 43.Nm dns-sd 44.Nd Multicast DNS (mDNS) & DNS Service Discovery (DNS-SD) Test Tool \" For whatis 45.\" 46.Sh SYNOPSIS 47.Nm Fl R Ar name type domain port Op Ar key=value ... 48.Pp 49.Nm Fl B Ar type domain 50.Pp 51.Nm Fl L Ar name type domain 52.\" 53.Sh DESCRIPTION 54The 55.Nm 56command is a network diagnostic tool, much like 57.Xr ping 8 58or 59.Xr traceroute 8 . 60However, unlike those tools, most of its functionality is not implemented in the 61.Nm 62executable itself, but in library code that is available to any application. 63The library API that 64.Nm 65uses is documented in 66.Pa /usr/include/dns_sd.h . 67.Pp 68The 69.Nm 70command is primarily intended for interactive use. 71Because its command-line arguments and output format are subject to change, 72invoking it from a shell script will generally be fragile. Additionally, 73the asynchronous nature of DNS Service Discovery does 74not lend itself easily to script-oriented programming. For example, 75calls like "browse" never complete; the action of performing a "browse" 76sets in motion machinery to notify the client whenever instances of 77that service type appear or disappear from the network. These 78notifications continue to be delivered indefinitely, for minutes, 79hours, or even days, as services come and go, until the client 80explicitly terminates the call. This style of asynchronous interaction 81works best with applications that are either multi-threaded, or use a 82main event-handling loop to receive keystrokes, network data, and other 83asynchronous event notifications as they happen. 84.br 85If you wish to perform DNS Service Discovery operations from a 86scripting language, then the best way to do this is not to execute the 87.Nm 88command and then attempt to decipher the textual output, but instead to 89directly call the DNS-SD APIs using a binding for your chosen language. 90.br 91For example, if you are programming in Ruby, then you can 92directly call DNS-SD APIs using the dnssd package documented at 93.Pa <http://rubyforge.org/projects/dnssd/> . 94.br 95Similar bindings for other languages are also in development. 96.Pp 97.Bl -tag -width R 98.It Nm Fl R Ar name type domain port Op Ar key=value ... 99register (advertise) a service in the specified 100.Ar domain 101with the given 102.Ar name 103and 104.Ar type 105as listening (on the current machine) on 106.Ar port. 107.Pp 108.Ar name 109can be arbitrary unicode text, containing any legal unicode characters 110(including dots, spaces, slashes, colons, etc. without restriction), 111up to 63 UTF-8 bytes long. 112.Ar type 113must be of the form "_app-proto._tcp" or "_app-proto._udp", where 114"app-proto" is an application protocol name registered at 115.Pa http://www.dns-sd.org/ServiceTypes.html . 116.Pp 117.Ar domain 118is the domain in which to register the service. 119In current implementations, only the local multicast domain "local" is 120supported. In the future, registering will be supported in any arbitrary 121domain that has a working DNS Update server [RFC 2136]. The 122.Ar domain 123"." is a synonym for "pick a sensible default" which today 124means "local". 125.Pp 126.Ar port 127is a number from 0 to 65535, and is the TCP or UDP port number upon 128which the service is listening. 129.Pp 130Additional attributes of the service may optionally be described by 131key/value pairs, which are stored in the advertised service's DNS TXT 132record. Allowable keys and values are listed with the service 133registration at 134.Pa http://www.dns-sd.org/ServiceTypes.html . 135.It Nm Fl B Ar type domain 136browse for instances of service 137.Ar type 138in 139.Ar domain . 140.Pp 141For valid 142.Ar type Ns s 143see 144.Pa http://www.dns-sd.org/ServiceTypes.html 145as described above. Omitting the 146.Ar domain 147or using "." means "pick a sensible default." 148.It Nm Fl L Ar name type domain 149look up and display the information necessary to contact and use the 150named service: the hostname of the machine where that service is 151available, the port number on which the service is listening, and (if 152present) TXT record attributes describing properties of the service. 153.Pp 154Note that in a typical application, browsing happens rarely, while lookup 155(or "resolving") happens every time the service is used. For example, a 156user browses the network to pick a default printer fairly rarely, but once 157a default printer has been picked, that named service is resolved to its 158current IP address and port number every time the user presses Cmd-P to 159print. 160.El 161.Sh EXAMPLES 162.Pp 163To advertise the existence of LPR printing service on port 515 on this 164machine, such that it will be discovered by the Mac OS X printing software 165and other DNS-SD compatible printing clients, use: 166.Pp 167.Dl Nm Fl R Ns \ \&"My Test\&" _printer._tcp. \&. 515 pdl=application/postscript 168.Pp 169For this registration to be useful, you need to actually have LPR service 170available on port 515. Advertising a service that does not exist is not 171very useful, and will be confusing and annoying to other people on the 172network. 173.Pp 174Similarly, to advertise a web page being served by an HTTP 175server on port 80 on this machine, such that it will show up in the 176Bonjour list in Safari and other DNS-SD compatible Web clients, use: 177.Pp 178.Dl Nm Fl R Ns \ \&"My Test\&" _http._tcp \&. 80 path=/path-to-page.html 179.Pp 180To find the advertised web pages on the local network (the same list that 181Safari shows), use: 182.Pp 183.Dl Nm Fl B Ns \ _http._tcp 184.Pp 185While that command is running, in another window, try the 186.Nm Fl R 187example given above to advertise a web page, and you should see the 188"Add" event reported to the 189.Nm Fl B 190window. Now press Ctrl-C in the 191.Nm Fl R 192window and you should see the "Remove" event reported to the 193.Nm Fl B 194window. 195.Pp 196.Sh FILES 197.Pa /usr/bin/dns-sd \" Pathname 198.\" 199.Sh SEE ALSO 200.Xr mdnsd 8 201.\" 202.Sh HISTORY 203The 204.Nm 205command first appeared in 206.Nx 6.0 , 207having originated in Mac OS X 10.4 (Tiger). 208