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