mDNSShared/mDNS.1

   1 .\" Copyright (c) 2004 Apple Computer, Inc. All Rights Reserved.
   2 .\"
   3 .\" @APPLE_LICENSE_HEADER_START@
   4 .\"
   5 .\" This file contains Original Code and/or Modifications of Original Code
   6 .\" as defined in and that are subject to the Apple Public Source License
   7 .\" Version 2.0 (the 'License'). You may not use this file except in
   8 .\" compliance with the License. Please obtain a copy of the License at
   9 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  10 .\" file.
  11 .\"
  12 .\" The Original Code and all software distributed under the License are
  13 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  17 .\" Please see the License for the specific language governing rights and
  18 .\" limitations under the License.
  19 .\"
  20 .\" @APPLE_LICENSE_HEADER_END@
  21 .\"
  22 .\" $Log: mDNS.1,v $
  23 .\" Revision 1.3  2004/05/19 00:31:28  cheshire
  24 .\" Add missing "name type domain" for -L option
  25 .\"
  26 .\" Revision 1.2  2004/05/18 18:58:29  cheshire
  27 .\" Refinements from Soren Spies
  28 .\"
  29 .\" Revision 1.1  2004/04/22 02:52:53  cheshire
  30 .\" <rdar://problem/3597463>: mDNSResponder missing man pages: mDNS
  31 .\"
  32 .\"
  33 .\"
  34 .Dd April 2004              \" Date
  35 .Dt mDNS 1                  \" Document Title
  36 .Os Darwin                  \" Operating System
  37 .\"
  38 .Sh NAME
  39 .Nm mDNS
  40 .Nd Multicast DNS Service Discovery (mDNS-SD) Test Tool \" For whatis
  41 .\"
  42 .Sh SYNOPSIS
  43 .Nm Fl R Ar name type domain port Op Ar key=value ...
  44 .Pp
  45 .Nm Fl B Ar      type domain
  46 .Pp
  47 .Nm Fl L Ar name type domain
  48 .\"
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 command is a network diagnostic tool, much like
  53 .Xr ping 8 or
  54 .Xr traceroute 8 .
  55 Unlike those tools, most of its functionality is implemented in library
  56 code that is available to any application. The API that it uses is
  57 described in
  58 .Pa /usr/include/dns_sd.h .
  59 .Pp
  60 The
  61 .Nm
  62 command is primarily intended for interactive use.
  63 Because its command-line arguments and output format are subject to change,
  64 invoking it from a shell script will generally be fragile. Additionally,
  65 the asynchronous nature of Multicast DNS Service Discovery does
  66 not lend itself easily to script-oriented programming. For example,
  67 calls like "browse" never complete; the action of performing a "browse"
  68 sets in motion machinery to notify the client whenever instances of
  69 that service type appear or disappear from the network. These
  70 notifications continue to be delivered indefinitely, for minutes,
  71 hours, or even days, as services come and go, until the client
  72 explicitly terminates the call. This style of asynchronous interaction
  73 works best with applications that are either multi-threaded, or use a
  74 main event-handling loop to receive keystrokes, network data, and other
  75 asynchronous event notifications as they happen.
  76 .Pp
  77 .Bl -tag -width R
  78 .It Fl R Ar name type domain port Op Ar key=value ...
  79 register (advertise) a service in the specified
  80 .Ar domain
  81 with the given
  82 .Ar name
  83 and
  84 .Ar type
  85 as listening (on the current machine) on
  86 .Ar port.
  87 .Pp
  88 .Ar name
  89 can be arbitrary unicode text, containing any legal unicode characters
  90 (including dots, spaces, slashes, colons, etc. without restriction),
  91 up to 63 UTF-8 bytes long.
  92 .Ar type
  93 must be of the form "_app-proto._tcp" or "_app-proto._udp", where
  94 "app-proto" is an application protocol name registered at
  95 .Pa http://www.dns-sd.org/ServiceTypes.html .
  96 .Pp
  97 .Ar domain
  98 is the domain in which to register the service.
  99 In current implementations, only the local multicast domain "local" is
 100 supported. In the future, registering will be supported in any arbitrary
 101 domain that has a working DNS Update server [RFC 2136]. The
 102 .Ar domain
 103 "." is a synonym for "pick a sensible default" which today
 104 means "local".
 105 .Pp
 106 .Ar port
 107 is a number from 0 to 65535, and is the TCP or UDP port number upon
 108 which the service is listening.
 109 .Pp
 110 Additional attributes of the service may optionally be described by
 111 key/value pairs, which are stored in the advertised service's DNS TXT
 112 record. Allowable keys and values are listed with the service
 113 registration at
 114 .Pa http://www.dns-sd.org/ServiceTypes.html .
 115 .It Fl B Ar type domain
 116 browse for instances of service
 117 .Ar type
 118 in
 119 .Ar domain .
 120 .Pp
 121 For valid
 122 .Ar type Ns s
 123 see
 124 .Pa http://www.dns-sd.org/ServiceTypes.html
 125 as described above. Omitting the
 126 .Ar domain
 127 or using "." means "pick a sensible default."
 128 .It Fl L Ar name type domain
 129 look up and display the information necessary to contact and use the
 130 named service: the hostname of the machine where that service is
 131 available, the port number on which the service is listening, and (if
 132 present) TXT record attributes describing properties of the service.
 133 .Pp
 134 Note that in a typical application, browsing happens rarely, while lookup
 135 (or "resolving") happens every time the service is used. For example, a
 136 user browses the network to pick a default printer fairly rarely, but once
 137 a default printer has been picked, that named service is resolved to its
 138 current IP address and port number every time the user presses Cmd-P to
 139 print.
 140 .El
 141 .Sh EXAMPLES
 142 .Pp
 143 To advertise the existence of LPR printing service on port 515 on this
 144 machine, such that it will be discovered by the Mac OS X printing software
 145 and other mDNS-SD compatible printing clients, use:
 146 .Pp
 147 .Dl mDNS -R \&"My Test\&" _printer._tcp. \&. 515 pdl=application/postscript
 148 .Pp
 149 For this registration to be useful, you need to actually have LPR service
 150 available on port 515. Advertising a service that does not exist is not
 151 very useful, and will be confusing and annoying to other people on the
 152 network.
 153 .Pp
 154 Similarly, to advertise a web page being served by an HTTP
 155 server on port 80 on this machine, such that it will show up in the
 156 Rendezvous list in Safari and other mDNS-SD compatible Web clients, use:
 157 .Pp
 158 .Dl mDNS -R \&"My Test\&" _http._tcp \&. 80 path=/path-to-page.html
 159 .Pp
 160 To find the advertised web pages on the local network (the same list that
 161 Safari shows), use:
 162 .Pp
 163 .Dl mDNS -B _http._tcp
 164 .Pp
 165 While that command is running, in another window, try the "mDNS -R"
 166 example given above to advertise a web page, and you should see the
 167 "Add" event reported to the "mDNS -B" window. Now press Ctrl-C in the
 168 "mDNS -R" window and you should see the "Remove" event reported to the
 169 "mDNS -B" window.
 170 .Pp
 171 .Sh FILES
 172 .Pa /usr/bin/mDNS \" Pathname
 173 .\"
 174 .Sh SEE ALSO
 175 .Xr mDNSResponder 8
 176 .\"
 177 .Sh BUGS
 178 .Nm
 179 bugs are tracked in Apple Radar component "mDNSResponder".
 180 .\"
 181 .Sh HISTORY
 182 The
 183 .Nm
 184 command first appeared in Mac OS X 10.3 (Panther).