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 |
---|
47 | The |
---|
48 | .Nm |
---|
49 | command is a network diagnostic tool, much like |
---|
50 | .Xr ping 8 |
---|
51 | or |
---|
52 | .Xr traceroute 8 . |
---|
53 | However, unlike those tools, most of its functionality is not implemented in the |
---|
54 | .Nm |
---|
55 | executable itself, but in library code that is available to any application. |
---|
56 | The library API that |
---|
57 | .Nm |
---|
58 | uses is documented in |
---|
59 | .Pa /usr/include/dns_sd.h . |
---|
60 | The |
---|
61 | .Nm |
---|
62 | command replaces the older |
---|
63 | mDNS |
---|
64 | command. |
---|
65 | .Pp |
---|
66 | The |
---|
67 | .Nm |
---|
68 | command is primarily intended for interactive use. |
---|
69 | Because its command-line arguments and output format are subject to change, |
---|
70 | invoking it from a shell script will generally be fragile. Additionally, |
---|
71 | the asynchronous nature of DNS Service Discovery does |
---|
72 | not lend itself easily to script-oriented programming. For example, |
---|
73 | calls like "browse" never complete; the action of performing a "browse" |
---|
74 | sets in motion machinery to notify the client whenever instances of |
---|
75 | that service type appear or disappear from the network. These |
---|
76 | notifications continue to be delivered indefinitely, for minutes, |
---|
77 | hours, or even days, as services come and go, until the client |
---|
78 | explicitly terminates the call. This style of asynchronous interaction |
---|
79 | works best with applications that are either multi-threaded, or use a |
---|
80 | main event-handling loop to receive keystrokes, network data, and other |
---|
81 | asynchronous event notifications as they happen. |
---|
82 | .br |
---|
83 | If you wish to perform DNS Service Discovery operations from a |
---|
84 | scripting language, then the best way to do this is not to execute the |
---|
85 | .Nm |
---|
86 | command and then attempt to decipher the textual output, but instead to |
---|
87 | directly call the DNS-SD APIs using a binding for your chosen language. |
---|
88 | .br |
---|
89 | For example, if you are programming in Ruby, then you can |
---|
90 | directly call DNS-SD APIs using the dnssd package documented at |
---|
91 | .Pa <http://rubyforge.org/projects/dnssd/> . |
---|
92 | .br |
---|
93 | Similar bindings for other languages are also in development. |
---|
94 | .Pp |
---|
95 | .Bl -tag -width E |
---|
96 | .It Nm Fl E |
---|
97 | return a list of domains recommended for registering(advertising) services. |
---|
98 | .Pp |
---|
99 | .It Nm Fl F |
---|
100 | return a list of domains recommended for browsing services. |
---|
101 | .Pp |
---|
102 | Normally, on your home network, the only domain you are likely to see is "local". |
---|
103 | However if your network administrator has created Domain Enumeration records, |
---|
104 | then 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 ... |
---|
107 | register (advertise) a service in the specified |
---|
108 | .Ar domain |
---|
109 | with the given |
---|
110 | .Ar name |
---|
111 | and |
---|
112 | .Ar type |
---|
113 | as listening (on the current machine) on |
---|
114 | .Ar port. |
---|
115 | .Pp |
---|
116 | .Ar name |
---|
117 | can be arbitrary unicode text, containing any legal unicode characters |
---|
118 | (including dots, spaces, slashes, colons, etc. without restriction), |
---|
119 | up to 63 UTF-8 bytes long. |
---|
120 | .Ar type |
---|
121 | must 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 |
---|
126 | is the domain in which to register the service. |
---|
127 | In current implementations, only the local multicast domain "local" is |
---|
128 | supported. In the future, registering will be supported in any arbitrary |
---|
129 | domain that has a working DNS Update server [RFC 2136]. The |
---|
130 | .Ar domain |
---|
131 | "." is a synonym for "pick a sensible default" which today |
---|
132 | means "local". |
---|
133 | .Pp |
---|
134 | .Ar port |
---|
135 | is a number from 0 to 65535, and is the TCP or UDP port number upon |
---|
136 | which the service is listening. |
---|
137 | .Pp |
---|
138 | Additional attributes of the service may optionally be described by |
---|
139 | key/value pairs, which are stored in the advertised service's DNS TXT |
---|
140 | record. Allowable keys and values are listed with the service |
---|
141 | registration 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 |
---|
144 | browse for instances of service |
---|
145 | .Ar type |
---|
146 | in |
---|
147 | .Ar domain . |
---|
148 | .Pp |
---|
149 | For valid |
---|
150 | .Ar type Ns s |
---|
151 | see |
---|
152 | .Pa http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml . |
---|
153 | as described above. Omitting the |
---|
154 | .Ar domain |
---|
155 | or using "." means "pick a sensible default." |
---|
156 | .It Nm Fl L Ar name type domain |
---|
157 | look up and display the information necessary to contact and use the |
---|
158 | named service: the hostname of the machine where that service is |
---|
159 | available, the port number on which the service is listening, and (if |
---|
160 | present) TXT record attributes describing properties of the service. |
---|
161 | .Pp |
---|
162 | Note 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 |
---|
164 | user browses the network to pick a default printer fairly rarely, but once |
---|
165 | a default printer has been picked, that named service is resolved to its |
---|
166 | current IP address and port number every time the user presses Cmd-P to |
---|
167 | print. |
---|
168 | .Pp |
---|
169 | .It Nm Fl P Ar name type domain port host IP Op Ar key=value ... |
---|
170 | create a proxy advertisement for a service running on(offered by) some other machine. |
---|
171 | The two new options are Host, a name for the device and IP, the address of it. |
---|
172 | .Pp |
---|
173 | The service for which you create a proxy advertisement does not necessarily have to be on your local network. |
---|
174 | You can set up a local proxy for a website on the Internet. |
---|
175 | .Pp |
---|
176 | .It Nm Fl q Ar name rrtype rrclass |
---|
177 | look up any DNS name, resource record type, and resource record class, |
---|
178 | not necessarily DNS-SD names and record types. |
---|
179 | If rrtype is not specified, it queries for the IPv4 address of the name, |
---|
180 | if rrclass is not specified, IN class is assumed. If the name is not a fully |
---|
181 | qualified domain name, then search domains may be appended. |
---|
182 | .Pp |
---|
183 | .It Nm Fl Z Ar type domain |
---|
184 | browse for service instances and display output in zone file format. |
---|
185 | .Pp |
---|
186 | .It Nm Fl G Ns \ v4/v6/v4v6 Ar name |
---|
187 | look up the IP address information of the name. |
---|
188 | If v4 is specified, the IPv4 address of the name is looked up, |
---|
189 | if v6 is specified the IPv6 address is looked up. If v4v6 is specified both the IPv4 and IPv6 |
---|
190 | address is looked up. If the name is not a fully qualified domain name, |
---|
191 | then search domains may be appended. |
---|
192 | .Pp |
---|
193 | .It Nm Fl V |
---|
194 | return the version of the currently running daemon/system service. |
---|
195 | .El |
---|
196 | .Sh EXAMPLES |
---|
197 | .Pp |
---|
198 | To advertise the existence of LPR printing service on port 515 on this |
---|
199 | machine, such that it will be discovered by the Mac OS X printing software |
---|
200 | and 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 |
---|
204 | For this registration to be useful, you need to actually have LPR service |
---|
205 | available on port 515. Advertising a service that does not exist is not |
---|
206 | very useful, and will be confusing and annoying to other people on the |
---|
207 | network. |
---|
208 | .Pp |
---|
209 | Similarly, to advertise a web page being served by an HTTP |
---|
210 | server on port 80 on this machine, such that it will show up in the |
---|
211 | Bonjour 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 |
---|
215 | To find the advertised web pages on the local network (the same list that |
---|
216 | Safari shows), use: |
---|
217 | .Pp |
---|
218 | .Dl Nm Fl B Ns \ _http._tcp |
---|
219 | .Pp |
---|
220 | While that command is running, in another window, try the |
---|
221 | .Nm Fl R |
---|
222 | example given above to advertise a web page, and you should see the |
---|
223 | "Add" event reported to the |
---|
224 | .Nm Fl B |
---|
225 | window. Now press Ctrl-C in the |
---|
226 | .Nm Fl R |
---|
227 | window and you should see the "Remove" event reported to the |
---|
228 | .Nm Fl B |
---|
229 | window. |
---|
230 | .Pp |
---|
231 | In the example below, the www.apple.com web page is advertised as a service called "apple", |
---|
232 | running 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 |
---|
236 | The Bonjour menu in the Safari web browser will now show "apple". |
---|
237 | The same IP address can be reached by entering apple.local in the web browser. |
---|
238 | In either case, the request will be resolved to the IP address and browser will show |
---|
239 | contents associated with www.apple.com. |
---|
240 | .Pp |
---|
241 | If a client wants to be notified of changes in server state, it can |
---|
242 | initiate a query for the service's particular record and leave it running. |
---|
243 | For 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 |
---|
247 | Everytime status of that user(someone) changes, you will see a new TXT record result reported. |
---|
248 | .Pp |
---|
249 | You 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 |
---|
261 | bugs are tracked in Apple Radar component "mDNSResponder". |
---|
262 | .\" |
---|
263 | .Sh HISTORY |
---|
264 | The |
---|
265 | .Nm |
---|
266 | command first appeared in Mac OS X 10.4 (Tiger). |
---|