| blob | 93ca9ae043b00a46b2940784b2aa592620964810 |
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
54 The
55 .Nm
56 command is a network diagnostic tool, much like
57 .Xr ping 8
58 or
59 .Xr traceroute 8 .
60 However, unlike those tools, most of its functionality is not implemented in the
61 .Nm
62 executable itself, but in library code that is available to any application.
63 The library API that
64 .Nm
65 uses is documented in
66 .Pa /usr/include/dns_sd.h .
67 .Pp
68 The
69 .Nm
70 command is primarily intended for interactive use.
71 Because its command-line arguments and output format are subject to change,
72 invoking it from a shell script will generally be fragile. Additionally,
73 the asynchronous nature of DNS Service Discovery does
74 not lend itself easily to script-oriented programming. For example,
75 calls like "browse" never complete; the action of performing a "browse"
76 sets in motion machinery to notify the client whenever instances of
77 that service type appear or disappear from the network. These
78 notifications continue to be delivered indefinitely, for minutes,
79 hours, or even days, as services come and go, until the client
80 explicitly terminates the call. This style of asynchronous interaction
81 works best with applications that are either multi-threaded, or use a
82 main event-handling loop to receive keystrokes, network data, and other
83 asynchronous event notifications as they happen.
84 .br
85 If you wish to perform DNS Service Discovery operations from a
86 scripting language, then the best way to do this is not to execute the
87 .Nm
88 command and then attempt to decipher the textual output, but instead to
89 directly call the DNS-SD APIs using a binding for your chosen language.
90 .br
91 For example, if you are programming in Ruby, then you can
92 directly call DNS-SD APIs using the dnssd package documented at
93 .Pa <http://rubyforge.org/projects/dnssd/> .
94 .br
95 Similar 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 ...
99 register (advertise) a service in the specified
100 .Ar domain
101 with the given
102 .Ar name
103 and
104 .Ar type
105 as listening (on the current machine) on
106 .Ar port.
107 .Pp
108 .Ar name
109 can be arbitrary unicode text, containing any legal unicode characters
110 (including dots, spaces, slashes, colons, etc. without restriction),
111 up to 63 UTF-8 bytes long.
112 .Ar type
113 must 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
118 is the domain in which to register the service.
119 In current implementations, only the local multicast domain "local" is
120 supported. In the future, registering will be supported in any arbitrary
121 domain that has a working DNS Update server [RFC 2136]. The
122 .Ar domain
123 "." is a synonym for "pick a sensible default" which today
124 means "local".
125 .Pp
126 .Ar port
127 is a number from 0 to 65535, and is the TCP or UDP port number upon
128 which the service is listening.
129 .Pp
130 Additional attributes of the service may optionally be described by
131 key/value pairs, which are stored in the advertised service's DNS TXT
132 record. Allowable keys and values are listed with the service
133 registration at
134 .Pa http://www.dns-sd.org/ServiceTypes.html .
135 .It Nm Fl B Ar type domain
136 browse for instances of service
137 .Ar type
138 in
139 .Ar domain .
140 .Pp
141 For valid
142 .Ar type Ns s
143 see
144 .Pa http://www.dns-sd.org/ServiceTypes.html
145 as described above. Omitting the
146 .Ar domain
147 or using "." means "pick a sensible default."
148 .It Nm Fl L Ar name type domain
149 look up and display the information necessary to contact and use the
150 named service: the hostname of the machine where that service is
151 available, the port number on which the service is listening, and (if
152 present) TXT record attributes describing properties of the service.
153 .Pp
154 Note that in a typical application, browsing happens rarely, while lookup
155 (or "resolving") happens every time the service is used. For example, a
156 user browses the network to pick a default printer fairly rarely, but once
157 a default printer has been picked, that named service is resolved to its
158 current IP address and port number every time the user presses Cmd-P to
159 print.
160 .El
161 .Sh EXAMPLES
162 .Pp
163 To advertise the existence of LPR printing service on port 515 on this
164 machine, such that it will be discovered by the Mac OS X printing software
165 and 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
169 For this registration to be useful, you need to actually have LPR service
170 available on port 515. Advertising a service that does not exist is not
171 very useful, and will be confusing and annoying to other people on the
172 network.
173 .Pp
174 Similarly, to advertise a web page being served by an HTTP
175 server on port 80 on this machine, such that it will show up in the
176 Bonjour 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
180 To find the advertised web pages on the local network (the same list that
181 Safari shows), use:
182 .Pp
183 .Dl Nm Fl B Ns \ _http._tcp
184 .Pp
185 While that command is running, in another window, try the
186 .Nm Fl R
187 example given above to advertise a web page, and you should see the
188 "Add" event reported to the
189 .Nm Fl B
190 window. Now press Ctrl-C in the
191 .Nm Fl R
192 window and you should see the "Remove" event reported to the
193 .Nm Fl B
194 window.
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
203 The
204 .Nm
205 command first appeared in
206 .Nx 6.0 ,
207 having originated in Mac OS X 10.4 (Tiger).