mDNSShared/mDNS.1

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