| blob | aeabdcc84030deedae11872c50fada2cb86b546a |
1 '\" te
2 .\" Copyright (c) 2003-2004 Apple Computer, Inc. All Rights Reserved.
3 .\" Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing,
4 .\" software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
5 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
6 .TH DNS-SD 1M "Aug 21, 2007"
7 .SH NAME
8 dns-sd \- Multicast DNS (mDNS) & DNS Service Discovery (DNS-SD) Test Tool
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBdns-sd\fR \fB-R\fR \fIname\fR \fItype\fR \fIdomain\fR \fIport\fR [\fIkey\fR=\fIvalue\fR ...]
13 .fi
15 .LP
16 .nf
17 \fBdns-sd\fR \fB-B\fR \fItype\fR \fIdomain\fR
18 .fi
20 .LP
21 .nf
22 \fBdns-sd\fR \fB-L\fR \fIname\fR \fItype\fR \fIdomain\fR
23 .fi
25 .LP
26 .nf
27 \fBdns-sd\fR \fB-Q\fR \fIFQDN\fR \fIrrtype\fR \fIrrclass\fR
28 .fi
30 .LP
31 .nf
32 \fBdns-sd\fR \fB-C\fR \fIFQDN\fR \fIrrtype\fR \fIrrclass\fR
33 .fi
35 .LP
36 .nf
37 \fBdns-sd\fR \fB-P\fR \fIname\fR \fItype\fR \fIdomain\fR \fIport\fR \fIhost\fR \fIIP\fR [\fIkey\fR=\fIvalue\fR ...]
38 .fi
40 .LP
41 .nf
42 \fBdns-sd\fR \fB-E\fR | \fB-F\fR | \fB-A\fR | \fB-U\fR | \fB-N\fR | \fB-T\fR | \fB-M\fR | \fB-I\fR
43 .fi
45 .SH DESCRIPTION
46 .sp
47 .LP
48 The \fBdns-sd\fR command is a network diagnostic tool, much like \fBping\fR(1M)
49 or \fBtraceroute\fR(1M). However, unlike those tools, most of its functionality
50 is not implemented in the \fBdns-sd\fR executable itself, but in library code
51 that is available to any application. The library \fBAPI\fR that \fBdns-sd\fR
52 uses is documented in \fB/usr/include/dns_sd.h\fR.
53 .sp
54 .LP
55 The \fBdns-sd\fR command is primarily intended for interactive use. Because its
56 command-line arguments and output format are subject to change, invoking it
57 from a shell script can be unpredictable. Additionally, the asynchronous nature
58 of \fBDNS\fR Service Discovery does not easily lend itself to script-oriented
59 programming. This style of asynchronous interaction works best with
60 applications that are either multi-threaded, or use a main event-handling loop
61 to receive keystrokes, network data, and other asynchronous event notifications
62 as they happen.
63 .SH OPTIONS
64 .sp
65 .LP
66 The following options are supported:
67 .sp
68 .ne 2
69 .na
70 \fB\fB-R\fR \fIname\fR \fItype\fR \fIdomain\fR \fIport\fR
71 [\fIkey\fR=\fIvalue\fR ...]\fR
72 .ad
73 .sp .6
74 .RS 4n
75 Register (advertise) a service in the specified domain with the given
76 \fIname\fR and \fItype\fR as listening (on the current machine) on the
77 specified \fIport\fR.
78 .sp
79 \fIname\fR can be any arbitrary unicode text, containing any legal unicode
80 characters (including dots, spaces, slashes, colons, and so on without any
81 restrictions), up to 63 \fBUTF-8\fR bytes long.
82 .sp
83 \fItype\fR must be of the form "_app-proto._tcp" or "_app-proto._udp", where
84 "app-proto" is an application protocol name registered at
85 http://www.dns-sd.org/ServiceTypes.html.
86 .sp
87 \fIdomain\fR is the domain in which to register the service. In current
88 implementations, only the local multicast domain "local" is supported. In the
89 future, registering will be supported in any arbitrary domain that has a
90 working \fBDNS\fR Update server [\fBRFC\fR 2136]. The domain "." is a synonym
91 for "pick a sensible default", which currently means "local".
92 .sp
93 \fIport\fR is a number from 0 to 65535, and is the \fBTCP\fR or \fBUDP\fR port
94 number upon which the service is listening. Registering a service on port 0
95 allows an application to explicitly advertise the non-availability of a
96 service.
97 .sp
98 Additional attributes of the service may optionally be described by
99 \fIkey/value\fR pairs, which are stored in the advertised service's \fBDNS\fR
100 \fBTXT\fR record. Allowable keys and values are listed with the service
101 registration at http://www.dns-sd.org/ServiceTypes.html
102 .RE
104 .sp
105 .ne 2
106 .na
107 \fB\fB-B\fR \fItype\fR \fIdomain\fR\fR
108 .ad
109 .sp .6
110 .RS 4n
111 Browse for instances of service \fItype\fR in \fIdomain\fR.
112 .sp
113 For valid types, see http://www.dns-sd.org/ServiceTypes.html. Omitting the
114 domain name or using "." means "pick a sensible default."
115 .RE
117 .sp
118 .ne 2
119 .na
120 \fB\fB-L\fR \fIname\fR \fItype\fR \fIdomain\fR\fR
121 .ad
122 .sp .6
123 .RS 4n
124 Look up and display the information necessary to contact and use the named
125 service. This information includes the hostname of the machine where that
126 service is available, the port number on which the service is listening, and
127 (if present) \fBTXT\fR record attributes describing properties of the service.
128 .sp
129 In a typical application, browsing happens rarely, while lookup (or
130 "resolving") happens every time the service is used. For example, a user does
131 not browse the network to pick a default printer that often, but once a default
132 printer has been picked, that named service is resolved to its current IP
133 address and port number every time the user presses Cmd-P to print.
134 .RE
136 .sp
137 .ne 2
138 .na
139 \fB\fB-Q\fR \fIFQDN\fR \fIrrtype\fR \fIrrclass\fR\fR
140 .ad
141 .sp .6
142 .RS 4n
143 Generic query for any resource record type and class.
144 .RE
146 .sp
147 .ne 2
148 .na
149 \fB\fB-C\fR \fIFQDN\fR \fIrrtype\fR \fIrrclass\fR\fR
150 .ad
151 .sp .6
152 .RS 4n
153 Generic query for any resource record type and class. This option also
154 reconfirms each result from the query. Reconfirming the record instructs
155 \fBmdnsd\fR(1M) to verify the validity of the record. If the record is not
156 valid \fBmdnsd\fR(1M) flushes the record from the daemon's cache and also from
157 other \fBmdnsd\fR(1M) caches on the network.
158 .RE
160 .sp
161 .ne 2
162 .na
163 \fB\fB-P\fR \fIname\fR \fItype\fR \fIdomain\fR \fIport\fR \fIhost\fR \fIIP\fR
164 [\fIkey\fR=\fIvalue\fR ...]\fR
165 .ad
166 .sp .6
167 .RS 4n
168 Register (advertise) a service in the specified domain with the given
169 \fIname\fR and \fItype\fR listening on the specified port and accessible on
170 another host. This option should be used to advertise by proxy a service
171 accessible on another host. The host name and \fBIPv4\fR address to access the
172 service must be specified.
173 .RE
175 .sp
176 .ne 2
177 .na
178 \fB\fB-E\fR\fR
179 .ad
180 .sp .6
181 .RS 4n
182 Discover recommended registration domains. This option returns the recommended
183 domains to register a service. The recommended registration domains are
184 returned by querying the name servers in \fBresolv.conf\fR(4).
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fB-F\fR\fR
191 .ad
192 .sp .6
193 .RS 4n
194 Discover recommended browsing domains. This option returns the recommended
195 domains for browsing services. The recommended browsing domains are returned by
196 querying the name servers in \fBresolv.conf\fR(4).
197 .RE
199 .sp
200 .ne 2
201 .na
202 \fB\fB-A\fR\fR
203 .ad
204 .sp .6
205 .RS 4n
206 Test registering service with Multicast \fBDNS\fR and test the add, update and
207 delete operations of \fBDNS\fR records with Multicast \fBDNS\fR.
208 .RE
210 .sp
211 .ne 2
212 .na
213 \fB\fB-U\fR\fR
214 .ad
215 .sp .6
216 .RS 4n
217 Test registering service with Multicast \fBDNS\fR and test updating of
218 \fBDNS\fR \fBTXT\fR records for a service registered with Multicast \fBDNS\fR.
219 .RE
221 .sp
222 .ne 2
223 .na
224 \fB\fB-N\fR\fR
225 .ad
226 .sp .6
227 .RS 4n
228 Test adding a large \fBNULL\fR record for a service registered with Multicast
229 \fBDNS\fR.
230 .RE
232 .sp
233 .ne 2
234 .na
235 \fB\fB-T\fR\fR
236 .ad
237 .sp .6
238 .RS 4n
239 Test adding a large \fBTXT\fR record for a service registered with Multicast
240 \fBDNS\fR.
241 .RE
243 .sp
244 .ne 2
245 .na
246 \fB\fB-M\fR\fR
247 .ad
248 .sp .6
249 .RS 4n
250 Test creating a registration with multiple \fBTXT\fR records.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fB-I\fR\fR
257 .ad
258 .sp .6
259 .RS 4n
260 Test registering and then immediately updating a \fBTXT\fR record.
261 .RE
263 .SH EXAMPLES
264 .LP
265 \fBExample 1 \fRAdvertising a printing service
266 .sp
267 .LP
268 The following command advertises the existence of \fBLPR\fR printing service on
269 port 515 on this machine, so that it will be available to \fBDNS-SD\fR
270 compatible printing clients:
272 .sp
273 .in +2
274 .nf
275 dns-sd -R "My Test" _printer._tcp. . 515 pdl=application/postscript
276 .fi
277 .in -2
278 .sp
280 .sp
281 .LP
282 For this registration to be useful, the LPR service should be available on port
283 515. Advertising a service that does not exist is not very useful.
284 .LP
285 \fBExample 2 \fRAdvertising a web page
286 .sp
287 .LP
288 The following command advertises a web page being served by an \fBHTTP\fR
289 server on port 80 on this machine, so that it will appear on the Bonjour list
290 in Safari and other DNS-SD compatible Web clients:
292 .sp
293 .in +2
294 .nf
295 dns-sd -R "My Test" _http._tcp . 80 path=/path-to-page.html
296 .fi
297 .in -2
298 .sp
300 .LP
301 \fBExample 3 \fRFinding the advertised web pages on the local network
302 .sp
303 .LP
304 The following command finds the advertised web pages on the local network (the
305 same list that Safari shows):
307 .sp
308 .in +2
309 .nf
310 dns-sd -B _http._tcp
311 .fi
312 .in -2
313 .sp
315 .SH ATTRIBUTES
316 .sp
317 .LP
318 See \fBattributes\fR(5) for descriptions of the following attributes:
319 .sp
321 .sp
322 .TS
323 box;
324 c | c
325 l | l .
326 ATTRIBUTE TYPE ATTRIBUTE VALUE
327 _
328 Interface Stability Volatile
329 .TE
331 .SH SEE ALSO
332 .sp
333 .LP
334 \fBmdnsd\fR(1M), \fBping\fR(1M), \fBtraceroute\fR(1M), \fBresolv.conf\fR(4),
335 \fBattributes\fR(5)