RFC 6763
DNS-Based Service Discovery
Internet Engineering Task Force (IETF) S. Cheshire Request for Comments: 6763 M. Krochmal Category: Standards Track Apple Inc. ISSN: 2070-1721 February 2013 DNS-Based Service DiscoveryAbstract
This document specifies how DNS resource records are named and structured to facilitate service discovery. Given a type of service that a client is looking for, and a domain in which the client is looking for that service, this mechanism allows clients to discover a list of named instances of that desired service, using standard DNS queries. This mechanism is referred to as DNS-based Service Discovery, or DNS-SD. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc6763. Copyright Notice Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Table of Contents
1. Introduction ....................................................3 2. Conventions and Terminology Used in This Document ...............5 3. Design Goals ....................................................5 4. Service Instance Enumeration (Browsing) .........................6 4.1. Structured Service Instance Names ..........................6 4.2. User Interface Presentation ................................9 4.3. Internal Handling of Names .................................9 5. Service Instance Resolution ....................................10 6. Data Syntax for DNS-SD TXT Records .............................11 6.1. General Format Rules for DNS TXT Records ..................11 6.2. DNS-SD TXT Record Size ....................................12 6.3. DNS TXT Record Format Rules for Use in DNS-SD .............13 6.4. Rules for Keys in DNS-SD Key/Value Pairs ..................14 6.5. Rules for Values in DNS-SD Key/Value Pairs ................16 6.6. Example TXT Record ........................................17 6.7. Version Tag ...............................................17 6.8. Service Instances with Multiple TXT Records ...............18 7. Service Names ..................................................19 7.1. Selective Instance Enumeration (Subtypes) .................21 7.2. Service Name Length Limits ................................23 8. Flagship Naming ................................................25 9. Service Type Enumeration .......................................27 10. Populating the DNS with Information ...........................27 11. Discovery of Browsing and Registration Domains (Domain Enumeration) ..................................................28 12. DNS Additional Record Generation ..............................30 12.1. PTR Records ..............................................30 12.2. SRV Records ..............................................30 12.3. TXT Records ..............................................31 12.4. Other Record Types .......................................31 13. Working Examples ..............................................31 13.1. What web pages are being advertised from dns-sd.org? .....31 13.2. What printer-configuration web pages are there? ..........31 13.3. How do I access the web page called "Service Discovery"? ..............................................32 14. IPv6 Considerations ...........................................32 15. Security Considerations .......................................32 16. IANA Considerations ...........................................32 17. Acknowledgments ...............................................33 18. References ....................................................33 18.1. Normative References .....................................33 18.2. Informative References ...................................34 Appendix A. Rationale for Using DNS as a Basis for Service Discovery .............................................37
Appendix B. Ordering of Service Instance Name Components ..........38 B.1. Semantic Structure ........................................38 B.2. Network Efficiency ........................................39 B.3. Operational Flexibility ...................................39 Appendix C. What You See Is What You Get ..........................40 Appendix D. Choice of Factory-Default Names .......................42 Appendix E. Name Encodings in the Domain Name System ..............44 Appendix F. "Continuous Live Update" Browsing Model ...............45 Appendix G. Deployment History ....................................471. Introduction
This document specifies how DNS resource records are named and structured to facilitate service discovery. Given a type of service that a client is looking for, and a domain in which the client is looking for that service, this mechanism allows clients to discover a list of named instances of that desired service, using standard DNS queries. This mechanism is referred to as DNS-based Service Discovery, or DNS-SD. This document proposes no change to the structure of DNS messages, and no new operation codes, response codes, resource record types, or any other new DNS protocol values. This document specifies that a particular service instance can be described using a DNS SRV [RFC2782] and DNS TXT [RFC1035] record. The SRV record has a name of the form "<Instance>.<Service>.<Domain>" and gives the target host and port where the service instance can be reached. The DNS TXT record of the same name gives additional information about this instance, in a structured form using key/value pairs, described in Section 6. A client discovers the list of available instances of a given service type using a query for a DNS PTR [RFC1035] record with a name of the form "<Service>.<Domain>", which returns a set of zero or more names, which are the names of the aforementioned DNS SRV/TXT record pairs. This specification is compatible with both Multicast DNS [RFC6762] and with today's existing Unicast DNS server and client software. When used with Multicast DNS, DNS-SD can provide zero-configuration operation -- just connect a DNS-SD/mDNS device, and its services are advertised on the local link with no further user interaction [ZC]. When used with conventional Unicast DNS, some configuration will usually be required -- such as configuring the device with the DNS domain(s) in which it should advertise its services, and configuring it with the DNS Update [RFC2136] [RFC3007] keys to give it permission to do so. In rare cases, such as a secure corporate network behind a
firewall where no DNS Update keys are required, zero-configuration operation may be achieved by simply having the device register its services in a default registration domain learned from the network (see Section 11, "Discovery of Browsing and Registration Domains"), but this is the exception and usually security credentials will be required to perform DNS updates. Note that when using DNS-SD with Unicast DNS, the Unicast DNS-SD service does NOT have to be provided by the same DNS server hardware that is currently providing an organization's conventional host name lookup service. While many people think of "DNS" exclusively in the context of mapping host names to IP addresses, in fact, "the DNS is a general (if somewhat limited) hierarchical database, and can store almost any kind of data, for almost any purpose" [RFC2181]. By delegating the "_tcp" and "_udp" subdomains, all the workload related to DNS-SD can be offloaded to a different machine. This flexibility, to handle DNS-SD on the main DNS server or not, at the network administrator's discretion, is one of the benefits of using DNS. Even when the DNS-SD functions are delegated to a different machine, the benefits of using DNS remain: it is mature technology, well understood, with multiple independent implementations from different vendors, a wide selection of books published on the subject, and an established workforce experienced in its operation. In contrast, adopting some other service discovery technology would require every site in the world to install, learn, configure, operate, and maintain some entirely new and unfamiliar server software. Faced with these obstacles, it seems unlikely that any other service discovery technology could hope to compete with the ubiquitous deployment that DNS already enjoys. For further discussion, see Appendix A, "Rationale for Using DNS as a Basis for Service Discovery". This document is written for two audiences: for developers creating application software that offers or accesses services on the network, and for developers creating DNS-SD libraries to implement the advertising and discovery mechanisms. For both audiences, understanding the entire document is helpful. For developers creating application software, this document provides guidance on choosing instance names, service names, and other aspects that play a role in creating a good overall user experience. However, also understanding the underlying DNS mechanisms used to provide the service discovery facilities helps application developers understand the capabilities and limitations of those underlying mechanisms (e.g., name length limits). For library developers writing software to construct the DNS records (to advertise a service) and generate the DNS queries (to discover and use a service), understanding the ultimate user-experience goals helps them provide APIs that can meet those goals.
2. Conventions and Terminology Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119].3. Design Goals
Of the many properties a good service discovery protocol needs to have, three of particular importance are: (i) The ability to query for services of a certain type in a certain logical domain, and receive in response a list of named instances (network browsing or "Service Instance Enumeration"). (ii) Given a particular named instance, the ability to efficiently resolve that instance name to the required information a client needs to actually use the service, i.e., IP address and port number, at the very least (Service Instance Resolution). (iii) Instance names should be relatively persistent. If a user selects their default printer from a list of available choices today, then tomorrow they should still be able to print on that printer -- even if the IP address and/or port number where the service resides have changed -- without the user (or their software) having to repeat the step (i) (the initial network browsing) a second time. In addition, if it is to become successful, a service discovery protocol should be so simple to implement that virtually any device capable of implementing IP should not have any trouble implementing the service discovery software as well. These goals are discussed in more detail in the remainder of this document. A more thorough treatment of service discovery requirements may be found in "Requirements for a Protocol to Replace the AppleTalk Name Binding Protocol (NBP)" [RFC6760]. That document draws upon examples from two decades of operational experience with AppleTalk to develop a list of universal requirements that are broadly applicable to any potential service discovery protocol.
4. Service Instance Enumeration (Browsing)
Traditional DNS SRV records [RFC2782] are useful for locating instances of a particular type of service when all the instances are effectively indistinguishable and provide the same service to the client. For example, SRV records with the (hypothetical) name "_http._tcp.example.com." would allow a client to discover servers implementing the "_http._tcp" service (i.e., web servers) for the "example.com." domain. The unstated assumption is that all these servers offer an identical set of web pages, and it doesn't matter to the client which of the servers it uses, as long as it selects one at random according to the weight and priority rules laid out in the DNS SRV specification [RFC2782]. Instances of other kinds of service are less easily interchangeable. If a word processing application were to look up the (hypothetical) SRV record "_ipp._tcp.example.com." to find the list of Internet Printing Protocol (IPP) [RFC2910] printers at Example Co., then picking one at random and printing on it would probably not be what the user wanted. The remainder of this section describes how SRV records may be used in a slightly different way, to allow a user to discover the names of all available instances of a given type of service, and then select, from that list, the particular instance they desire.4.1. Structured Service Instance Names
This document borrows the logical service-naming syntax and semantics from DNS SRV records, but adds one level of indirection. Instead of requesting records of type "SRV" with name "_ipp._tcp.example.com.", the client requests records of type "PTR" (pointer from one name to another in the DNS namespace) [RFC1035]. In effect, if one thinks of the domain name "_ipp._tcp.example.com." as being analogous to an absolute path to a directory in a file system, then DNS-SD's PTR lookup is akin to performing a listing of that directory to find all the entries it contains. (Remember that domain names are expressed in reverse order compared to path names -- an absolute path name starts with the root on the left and is read from left to right, whereas a fully qualified domain name starts with the root on the right and is read from right to left. If the fully qualified domain name "_ipp._tcp.example.com." were expressed as a file system path name, it would be "/com/example/_tcp/_ipp".)
The result of this PTR lookup for the name "<Service>.<Domain>" is a
set of zero or more PTR records giving Service Instance Names of the
form:
Service Instance Name = <Instance> . <Service> . <Domain>
For explanation of why the components are in this order, see Appendix
B, "Ordering of Service Instance Name Components".
4.1.1. Instance Names
The <Instance> portion of the Service Instance Name is a user-
friendly name consisting of arbitrary Net-Unicode text [RFC5198]. It
MUST NOT contain ASCII control characters (byte values 0x00-0x1F and
0x7F) [RFC20] but otherwise is allowed to contain any characters,
without restriction, including spaces, uppercase, lowercase,
punctuation -- including dots -- accented characters, non-Roman text,
and anything else that may be represented using Net-Unicode. For
discussion of why the <Instance> name should be a user-visible, user-
friendly name rather than an invisible machine-generated opaque
identifier, see Appendix C, "What You See Is What You Get".
The <Instance> portion of the name of a service being offered on the
network SHOULD be configurable by the user setting up the service, so
that he or she may give it an informative name. However, the device
or service SHOULD NOT require the user to configure a name before it
can be used. A sensible choice of default name can in many cases
allow the device or service to be accessed without any manual
configuration at all. The default name should be short and
descriptive, and SHOULD NOT include the device's Media Access Control
(MAC) address, serial number, or any similar incomprehensible
hexadecimal string in an attempt to make the name globally unique.
For discussion of why <Instance> names don't need to be (and SHOULD
NOT be) made unique at the factory, see Appendix D, "Choice of
Factory-Default Names".
This <Instance> portion of the Service Instance Name is stored
directly in the DNS as a single DNS label of canonical precomposed
UTF-8 [RFC3629] "Net-Unicode" (Unicode Normalization Form C)
[RFC5198] text. For further discussion of text encodings, see
Appendix E, "Name Encodings in the Domain Name System".
DNS labels are currently limited to 63 octets in length. UTF-8
encoding can require up to four octets per Unicode character, which
means that in the worst case, the <Instance> portion of a name could
be limited to fifteen Unicode characters. However, the Unicode
characters with longer octet lengths under UTF-8 encoding tend to be the more rarely used ones, and tend to be the ones that convey greater meaning per character. Note that any character in the commonly used 16-bit Unicode Basic Multilingual Plane [Unicode6] can be encoded with no more than three octets of UTF-8 encoding. This means that an instance name can contain up to 21 Kanji characters, which is a sufficiently expressive name for most purposes.4.1.2. Service Names
The <Service> portion of the Service Instance Name consists of a pair of DNS labels, following the convention already established for SRV records [RFC2782]. The first label of the pair is an underscore character followed by the Service Name [RFC6335]. The Service Name identifies what the service does and what application protocol it uses to do it. The second label is either "_tcp" (for application protocols that run over TCP) or "_udp" (for all others). For more details, see Section 7, "Service Names".4.1.3. Domain Names
The <Domain> portion of the Service Instance Name specifies the DNS subdomain within which those names are registered. It may be "local.", meaning "link-local Multicast DNS" [RFC6762], or it may be a conventional Unicast DNS domain name, such as "ietf.org.", "cs.stanford.edu.", or "eng.us.ibm.com." Because Service Instance Names are not host names, they are not constrained by the usual rules for host names [RFC1033] [RFC1034] [RFC1035], and rich-text service subdomains are allowed and encouraged, for example: Building 2, 1st Floor . example . com . Building 2, 2nd Floor . example . com . Building 2, 3rd Floor . example . com . Building 2, 4th Floor . example . com . In addition, because Service Instance Names are not constrained by the limitations of host names, this document recommends that they be stored in the DNS, and communicated over the wire, encoded as straightforward canonical precomposed UTF-8 [RFC3629] "Net-Unicode" (Unicode Normalization Form C) [RFC5198] text. In cases where the DNS server returns a negative response for the name in question, client software MAY choose to retry the query using the "Punycode" algorithm [RFC3492] to convert the UTF-8 name to an IDNA "A-label" [RFC5890], beginning with the top-level label, then issuing the query
repeatedly, with successively more labels translated to IDNA A-labels each time, and giving up if it has converted all labels to IDNA A-labels and the query still fails.4.2. User Interface Presentation
The names resulting from the Service Instance Enumeration PTR lookup are presented to the user in a list for the user to select one (or more). Typically, only the first label is shown (the user-friendly <Instance> portion of the name). In the common case the <Service> and <Domain> are already known to the client software, these having been provided implicitly by the user in the first place, by the act of indicating the service being sought, and the domain in which to look for it. Note that the software handling the response should be careful not to make invalid assumptions though, since it *is* possible, though rare, for a service enumeration in one domain to return the names of services in a different domain. Similarly, when using subtypes (see Section 7.1, "Selective Instance Enumeration") the <Service> of the discovered instance may not be exactly the same as the <Service> that was requested. For further discussion of Service Instance Enumeration (browsing) user-interface considerations, see Appendix F, "'Continuous Live Update' Browsing Model". Once the user has selected the desired named instance, the Service Instance Name may then be used immediately, or saved away in some persistent user-preference data structure for future use, depending on what is appropriate for the application in question.4.3. Internal Handling of Names
If client software takes the <Instance>, <Service>, and <Domain> portions of a Service Instance Name and internally concatenates them together into a single string, then because the <Instance> portion is allowed to contain any characters, including dots, appropriate precautions MUST be taken to ensure that DNS label boundaries are properly preserved. Client software can do this in a variety of ways, such as character escaping. This document RECOMMENDS that if concatenating the three portions of a Service Instance Name, any dots in the <Instance> portion be escaped following the customary DNS convention for text files: by preceding literal dots with a backslash (so "." becomes "\."). Likewise, any backslashes in the <Instance> portion should also be escaped by preceding them with a backslash (so "\" becomes "\\").
Having done this, the three components of the name may be safely concatenated. The backslash-escaping allows literal dots in the name (escaped) to be distinguished from label-separator dots (not escaped), and the resulting concatenated string may be safely passed to standard DNS APIs like res_query(), which will interpret the backslash-escaped string as intended.5. Service Instance Resolution
When a client needs to contact a particular service, identified by a Service Instance Name, previously discovered via Service Instance Enumeration (browsing), it queries for the SRV and TXT records of that name. The SRV record for a service gives the port number and target host name where the service may be found. The TXT record gives additional information about the service, as described in Section 6, "Data Syntax for DNS-SD TXT Records". SRV records are extremely useful because they remove the need for preassigned port numbers. There are only 65535 TCP port numbers available. These port numbers are traditionally allocated one per application protocol [RFC6335]. Some protocols like the X Window System have a block of 64 TCP ports allocated (6000-6063). Using a different TCP port for each different instance of a given service on a given machine is entirely sensible, but allocating each application its own large static range, as was done for the X Window System, is not a practical way to do that. On any given host, most TCP ports are reserved for services that will never run on that particular host in its lifetime. This is very poor utilization of the limited port space. Using SRV records allows each host to allocate its available port numbers dynamically to those services actually running on that host that need them, and then advertise the allocated port numbers via SRV records. Allocating the available listening port numbers locally on a per-host basis as needed allows much better utilization of the available port space than today's centralized global allocation. In the event that more than one SRV is returned, clients MUST correctly interpret the priority and weight fields -- i.e., lower- numbered priority servers should be used in preference to higher- numbered priority servers, and servers with equal priority should be selected randomly in proportion to their relative weights. However, in the overwhelmingly common case, a single advertised DNS-SD service instance is described by exactly one SRV record, and in this common case the priority and weight fields of the SRV record SHOULD both be set to zero.
6. Data Syntax for DNS-SD TXT Records
Some services discovered via Service Instance Enumeration may need more than just an IP address and port number to completely identify the service instance. For example, printing via the old Unix LPR (port 515) protocol [RFC1179] often specifies a queue name [BJP]. This queue name is typically short and cryptic, and need not be shown to the user. It should be regarded the same way as the IP address and port number: it is another component of the addressing information required to identify a specific instance of a service being offered by some piece of hardware. Similarly, a file server may have multiple volumes, each identified by its own volume name. A web server typically has multiple pages, each identified by its own URL. In these cases, the necessary additional data is stored in a TXT record with the same name as the SRV record. The specific nature of that additional data, and how it is to be used, is service- dependent, but the overall syntax of the data in the TXT record is standardized, as described below. Every DNS-SD service MUST have a TXT record in addition to its SRV record, with the same name, even if the service has no additional data to store and the TXT record contains no more than a single zero byte. This allows a service to have explicit control over the Time to Live (TTL) of its (empty) TXT record, rather than using the default negative caching TTL, which would otherwise be used for a "no error no answer" DNS response. Note that this requirement for a mandatory TXT record applies exclusively to DNS-SD service advertising, i.e., services advertised using the PTR+SRV+TXT convention specified in this document. It is not a requirement of SRV records in general. The DNS SRV record datatype [RFC2782] may still be used in other contexts without any requirement for accompanying PTR and TXT records.6.1. General Format Rules for DNS TXT Records
A DNS TXT record can be up to 65535 (0xFFFF) bytes long. The total length is indicated by the length given in the resource record header in the DNS message. There is no way to tell directly from the data alone how long it is (e.g., there is no length count at the start, or terminating NULL byte at the end). Note that when using Multicast DNS [RFC6762] the maximum packet size is 9000 bytes, including the IP header, UDP header, and DNS message header, which imposes an upper limit on the size of TXT records of about 8900 bytes. In practice the maximum sensible size of a DNS-SD TXT record is smaller even than this, typically at most a few hundred bytes, as described below in Section 6.2.
The format of the data within a DNS TXT record is one or more strings, packed together in memory without any intervening gaps or padding bytes for word alignment. The format of each constituent string within the DNS TXT record is a single length byte, followed by 0-255 bytes of text data. These format rules for TXT records are defined in Section 3.3.14 of the DNS specification [RFC1035] and are not specific to DNS-SD. DNS-SD specifies additional rules for what data should be stored in those constituent strings when used for DNS-SD service advertising, i.e., when used to describe services advertised using the PTR+SRV+TXT convention specified in this document. An empty TXT record containing zero strings is not allowed [RFC1035]. DNS-SD implementations MUST NOT emit empty TXT records. DNS-SD clients MUST treat the following as equivalent: o A TXT record containing a single zero byte. (i.e., a single empty string.) o An empty (zero-length) TXT record. (This is not strictly legal, but should one be received, it should be interpreted as the same as a single empty string.) o No TXT record. (i.e., an NXDOMAIN or no-error-no-answer response.)6.2. DNS-SD TXT Record Size
The total size of a typical DNS-SD TXT record is intended to be small -- 200 bytes or less. In cases where more data is justified (e.g., LPR printing [BJP]), keeping the total size under 400 bytes should allow it to fit in a single 512-byte DNS message [RFC1035]. In extreme cases where even this is not enough, keeping the size of the TXT record under 1300 bytes should allow it to fit in a single 1500-byte Ethernet packet. Using TXT records larger than 1300 bytes is NOT RECOMMENDED at this time. Note that some Ethernet hardware vendors offer chipsets with Multicast DNS [RFC6762] offload, so that computers can sleep and still be discoverable on the network. Early versions of such chipsets were sometimes quite limited: for example, some were
(unwisely) limited to handling TXT records no larger than 256 bytes (which meant that LPR printer services with larger TXT records did not work). Developers should be aware of this real-world limitation, and should understand that even hardware which is otherwise perfectly capable may have low-power and sleep modes that are more limited.6.3. DNS TXT Record Format Rules for Use in DNS-SD
DNS-SD uses DNS TXT records to store arbitrary key/value pairs conveying additional information about the named service. Each key/value pair is encoded as its own constituent string within the DNS TXT record, in the form "key=value" (without the quotation marks). Everything up to the first '=' character is the key (Section 6.4). Everything after the first '=' character to the end of the string (including subsequent '=' characters, if any) is the value (Section 6.5). No quotation marks are required around the value, even if it contains spaces, '=' characters, or other punctuation marks. Each author defining a DNS-SD profile for discovering instances of a particular type of service should define the base set of key/value attributes that are valid for that type of service. Using this standardized key/value syntax within the TXT record makes it easier for these base definitions to be expanded later by defining additional named attributes. If an implementation sees unknown keys in a service TXT record, it MUST silently ignore them. The target host name and TCP (or UDP) port number of the service are given in the SRV record. This information -- target host name and port number -- MUST NOT be duplicated using key/value attributes in the TXT record. The intention of DNS-SD TXT records is to convey a small amount of useful additional information about a service. Ideally, it should not be necessary for a client to retrieve this additional information before it can usefully establish a connection to the service. For a well-designed application protocol, even if there is no information at all in the TXT record, it should be possible, knowing only the host name, port number, and protocol being used, to communicate with that listening process and then perform version- or feature- negotiation to determine any further options or capabilities of the service instance. For example, when connecting to an AFP (Apple Filing Protocol) server [AFP] over TCP, the client enters into a protocol exchange with the server to determine which version of AFP the server implements and which optional features or capabilities (if any) are available. For protocols designed with adequate in-band version- and feature- negotiation, any information in the TXT record should be viewed as a
performance optimization -- when a client discovers many instances of a service, the TXT record allows the client to know some rudimentary information about each instance without having to open a TCP connection to each one and interrogate every service instance separately. Care should be taken when doing this to ensure that the information in the TXT record is in agreement with the information that would be retrieved by a client connecting over TCP. There are legacy protocols that provide no feature negotiation capability, and in these cases it may be useful to convey necessary information in the TXT record. For example, when printing using LPR [RFC1179], the LPR protocol provides no way for the client to determine whether a particular printer accepts PostScript, what version of PostScript, etc. In this case it is appropriate to embed this information in the TXT record [BJP], because the alternative would be worse -- passing around written instructions to the users, arcane manual configuration of "/etc/printcap" files, etc. The engineering decision about what keys to define for the TXT record needs to be decided on a case-by-case basis for each service type. For some service types it is appropriate to communicate information via the TXT record as well as (or instead of) via in-band communication in the application protocol.6.4. Rules for Keys in DNS-SD Key/Value Pairs
The key MUST be at least one character. DNS-SD TXT record strings beginning with an '=' character (i.e., the key is missing) MUST be silently ignored. The key SHOULD be no more than nine characters long. This is because it is beneficial to keep packet sizes small for the sake of network efficiency. When using DNS-SD in conjunction with Multicast DNS [RFC6762] this is important because multicast traffic is especially expensive on 802.11 wireless networks [IEEEW], but even when using conventional Unicast DNS, keeping the TXT records small helps improve the chance that responses will fit within the original DNS 512-byte size limit [RFC1035]. Also, each constituent string of a DNS TXT record is limited to 255 bytes, so excessively long keys reduce the space available for that key's values. The keys in key/value pairs can be as short as a single character. A key name needs only to be unique and unambiguous within the context of the service type for which it is defined. A key name is intended solely to be a machine-readable identifier, not a human-readable essay giving detailed discussion of the purpose of a parameter, with a URL for a web page giving yet more details of the specification. For ease of development and debugging, it can be valuable to use key
names that are mnemonic textual names, but excessively verbose keys are wasteful and inefficient, hence the recommendation to keep them to nine characters or fewer. The characters of a key MUST be printable US-ASCII values (0x20-0x7E) [RFC20], excluding '=' (0x3D). Spaces in the key are significant, whether leading, trailing, or in the middle -- so don't include any spaces unless you really intend that. Case is ignored when interpreting a key, so "papersize=A4", "PAPERSIZE=A4", and "Papersize=A4" are all identical. If there is no '=' in a DNS-SD TXT record string, then it is a boolean attribute, simply identified as being present, with no value. A given key SHOULD NOT appear more than once in a TXT record. The reason for this simplifying rule is to facilitate the creation of client libraries that parse the TXT record into an internal data structure (such as a hash table or dictionary object that maps from keys to values) and then make that abstraction available to client code. The rule that a given key may not appear more than once simplifies these abstractions because they aren't required to support the case of returning more than one value for a given key. If a client receives a TXT record containing the same key more than once, then the client MUST silently ignore all but the first occurrence of that attribute. For client implementations that process a DNS-SD TXT record from start to end, placing key/value pairs into a hash table using the key as the hash table key, this means that if the implementation attempts to add a new key/value pair into the table and finds an entry with the same key already present, then the new entry being added should be silently discarded instead. Client implementations that retrieve key/value pairs by searching the TXT record for the requested key should search the TXT record from the start and simply return the first matching key they find.
When examining a TXT record for a given key, there are therefore four
categories of results that may be returned:
* Attribute not present (Absent)
* Attribute present, with no value
(e.g., "passreq" -- password required for this service)
* Attribute present, with empty value
(e.g., "PlugIns=" -- the server supports plugins, but none are
presently installed)
* Attribute present, with non-empty value
(e.g., "PlugIns=JPEG,MPEG2,MPEG4")
Each author defining a DNS-SD profile for discovering instances of a
particular type of service should define the interpretation of these
different kinds of result. For example, for some keys, there may be
a natural true/false boolean interpretation:
* Absent implies 'false'
* Present implies 'true'
For other keys it may be sensible to define other semantics, such as
value/no-value/unknown:
* Present with value implies that value.
(e.g., "Color=4" for a four-color ink-jet printer
or "Color=6" for a six-color ink-jet printer)
* Present with empty value implies 'false'.
(e.g., not a color printer)
* Absent implies 'Unknown'.
(e.g., a print server connected to some unknown printer where the
print server doesn't actually know if the printer does color or
not -- which gives a very bad user experience and should be
avoided wherever possible)
Note that this is a hypothetical example, not an example of actual
key/value keys used by DNS-SD network printers, which are documented
in the "Bonjour Printing Specification" [BJP].
6.5. Rules for Values in DNS-SD Key/Value Pairs
If there is an '=' in a DNS-SD TXT record string, then everything
after the first '=' to the end of the string is the value. The value
can contain any eight-bit values including '='. The value MUST NOT
be enclosed in additional quotation marks or any similar punctuation; any quotation marks, or leading or trailing spaces, are part of the value. The value is opaque binary data. Often the value for a particular attribute will be US-ASCII [RFC20] or UTF-8 [RFC3629] text, but it is legal for a value to be any binary data. Generic debugging tools should generally display all attribute values as a hex dump, with accompanying text alongside displaying the UTF-8 interpretation of those bytes, except for attributes where the debugging tool has embedded knowledge that the value is some other kind of data. Authors defining DNS-SD profiles SHOULD NOT generically convert binary attribute data types into printable text using hexadecimal representation, Base-64 [RFC4648], or Unix-to-Unix (UU) encoding, merely for the sake of making the data appear to be printable text when seen in a generic debugging tool. Doing this simply bloats the size of the TXT record, without actually making the data any more understandable to someone looking at it in a generic debugging tool.6.6. Example TXT Record
The TXT record below contains three syntactically valid key/value strings. (The meaning of these key/value pairs, if any, would depend on the definitions pertaining to the service in question that is using them.) ------------------------------------------------------- | 0x09 | key=value | 0x08 | paper=A4 | 0x07 | passreq | -------------------------------------------------------6.7. Version Tag
It is recommended that authors defining DNS-SD profiles include an attribute of the form "txtvers=x", where "x" is a decimal version number in US-ASCII [RFC20] text (e.g., "txtvers=1" or "txtvers=8"), in their definition, and require it to be the first key/value pair in the TXT record. This information in the TXT record can be useful to help clients maintain backwards compatibility with older implementations if it becomes necessary to change or update the specification over time. Even if the profile author doesn't anticipate the need for any future incompatible changes, having a version number in the TXT record provides useful insurance should incompatible changes become unavoidable [RFC6709]. Clients SHOULD ignore TXT records with a txtvers number higher (or lower) than the version(s) they know how to interpret.
Note that the version number in the txtvers tag describes the version of the specification governing the defined keys and the meaning of those keys for that particular TXT record, not the version of the application protocol that will be used if the client subsequently decides to contact that service. Ideally, every DNS-SD TXT record specification starts at txtvers=1 and stays that way forever. Improvements can be made by defining new keys that older clients silently ignore. The only reason to increment the version number is if the old specification is subsequently found to be so horribly broken that there's no way to do a compatible forward revision, so the txtvers number has to be incremented to tell all the old clients they should just not even try to understand this new TXT record. If there is a need to indicate which version number(s) of the application protocol the service implements, the recommended key for this is "protovers".6.8. Service Instances with Multiple TXT Records
Generally speaking, every DNS-SD service instance has exactly one TXT record. However, it is possible for a particular protocol's DNS-SD advertising specification to state that it allows multiple TXT records. In this case, each TXT record describes a different variant of the same logical service, offered using the same underlying protocol on the same port, described by the same SRV record. Having multiple TXT records to describe a single service instance is very rare, and to date, of the many hundreds of registered DNS-SD service types [SN], only one makes use of this capability, namely LPR printing [BJP]. This capability is used when a printer conceptually supports multiple logical queue names, where each different logical queue name implements a different page description language, such as 80-column monospaced plain text, seven-bit Adobe PostScript, eight- bit ("binary") PostScript, or some proprietary page description language. When multiple TXT records are used to describe multiple logical LPR queue names for the same underlying service, printers include two additional keys in each TXT record: 'qtotal', which specifies the total number of TXT records associated with this SRV record, and 'priority', which gives the printer's relative preference for this particular TXT record. Clients then select the most preferred TXT record that meets the client's needs [BJP]. The only reason multiple TXT records are used is because the LPR protocol lacks in-band feature-negotiation capabilities for the client and server to agree on a data representation for the print job, so this information has to be communicated out-of-band instead using the DNS- SD TXT records. Future protocol designs should not follow this bad example by mimicking this inadequacy of the LPR printing protocol.
(next page on part 2)
