Internet-Draft DNS Web Service Discovery August 2021
Hallam-Baker Expires 6 February 2022 [Page]
Network Working Group
Intended Status:
P. M. Hallam-Baker

DNS Web Service Discovery


This document describes a standardized approach to discovering Web Service Endpoints from a DNS name. Services are advertised using the DNS SRV and TXT records and the HTTP Well Known Service conventions.

This document is also available online at

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 6 February 2022.

1. Introduction

Web services are traditionally identified by means of a URI specifying a Web Service Endpoint (WSE). This is approach is unsatisfactory in many situations:

  • Specification of the Web Service requires the transport and presentation protocols to be fixed.
  • The discovery mechanism does not provide support for load balancing or fault tolerance.
  • The identifiers are unsuited for human interaction.

The last consideration is a particular concern where an account identifier is exposed to the user. Attempts to 'teach' users to use URIs as account identifiers have been predictably unsuccessful. Users expect and require accounts to be of the form and not

The Web Service discovery process described in this specification builds on the approach specified in DNS-Based Service Discovery [RFC6763]. This uses DNS SRV records as the basis for service discovery and TXT records as the basis for service description. This approach allows Web Services to make use of the load balancing and fault tolerance features of SRV and the service negotiation capabilities provided by the service description.

One difficulty that is frequently encountered in attempting to make use of DNS records for service discovery is that it is not always possible for an application process to access this information. Specifications address the world as it actually is rather than as some believe it should be have proven more robust in real world deployment than those that do not. The discovery process defined includes a fallback strategy to enable clients to achieve Web Service discovery in these circumstances.

Another difficulty that is encountered is that the SRV record maps service names to host names rather than Web Service Endpoints. A convention is thus required to map a host name and protocol prefix to a Web Service Endpoint. The HTTP Well Known Service [RFC5785] mechanism is used for this purpose.

While the approach adopted in this specification closely follows that of [RFC6763], there is an important difference in that the earlier specification sets out a framework which Web Services may apply to develop a discovery approach that suits their particular needs while this specification defines exactly one such approach. In particular, the use of a common set of TXT keys to specify service parameters enables service discovery and negotiation to be delegated to common support libraries rather than being implemented independently in each application.

2. Definitions

This section presents the related specifications and standard, the terms that are used as terms of art within the documents and the terms used as requirements language.

2.1. Requirements Language

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 [RFC2119].

2.2. Defined Terms

Web Service

An Internet service provided by one or more Web Service Hosts that are addressable by a single Web Service Endpoint and are intended to provide logically equivalent services.

Web Service Endpoint (WSE)

A URI that specifies a Web Service or Web Service Host.

Web Service Host

The actual machine (physical or virtual) that provides a Web Service

3. Service Discovery

Service discovery is the process of resolving the address of a Web Service to a Web Service Endpoint, a URI [RFC3986] at which the service is provided.

3.1. Host Identification

The first step in service discovery is to resolve the <domain> and <service> identifiers to the IP address of a host that provides that service.

3.1.1. SRV Host discovery

A client attempting to connect to the service first attempts to locate an SRV record [RFC2782] for the specified service:

_<service>._tcp.<domain>  SRV  <priority> <weight> <port> <host>

Where <service> is the IANA assigned service name, <priority> and <weight> are the SRV priority and weight parameters specified in [RFC2782], <port> is the TCP port number and <host> is the DNS name of the host for which the service advertisement is made.

If no SRV records are found, the client MAY abort the connection or attempt use of the Fallback Discovery process described below.

3.2. Service Description

The second step in service discovery is to identify the attributes of the Web Service and Web Service Hosts providing that service.

3.2.1. TXT Service and Host Description

A service MAY advertise service and/or host description information using TXT records as described in DNS-Based Service Discovery [RFC6763] . These have the following format:

_<service>._tcp.<domain>  TXT "<key>=<value> [<tag>=<value>]*"
_<service>._tcp.<host>  TXT "<key>=<value> [<tag>=<value>]*"

Where <domain> and <host> are the domain names specified in the corresponding SRV records.

Service descriptions specified under the domain address of the service apply to all host instances of the service. Descriptions specified under the domain address of a host instance apply only to that host instance and take precedence over values specified at the service level.

The following keys are currently defined:


The path to use to construct the Web Service Endpoint.


The service version(s) supported in the format <max>-<min>


An IANA media type specifying a supported encoding format

3.3. Service Selection

Web Service Hosts that do not meet the requirements of the client attempting to create a connection are eliminated before applying SRV service selection criteria specified in [RFC2782].

Clients SHOULD limit the number of connections attempted before abandoning the attempt to connect.

3.4. Web Service Endpoint Determination

Having selected a Web Service Host, the client determines the Web Service Endpoint as follows:

  • If the description of the host specifies a path key, the corresponding value is used as the path, otherwise,
  • if the description of the service specifies a path key, the corresponding value is used as the path, otherwise,
  • the path is /.well-known/srv/<service>

3.5. DNS Fallback

Despite the fact that SRV records have been a part of the DNS standard for 20 years, it is not uncommon for network intermediaries to implement SRV record resolution incorrectly or block it entirely. If no SRV record is found, a client MAY perform fallback discovery if explicitly authorized to do so by the corresponding Web Service protocol specification.

The Web Service Endpoint used is:


Fallback discovery constrains the service provider to use a specific DNS configuration and provides inferior load balancing or fault tolerance capabilities to use of SRV records. It does however ensure that the service is reachable in situations where it would otherwise be unavailable.

3.6. Example

The Mathematical Mesh has the Well-Known Service name of 'MMM'. Accounts used in the Mathematical Mesh follow the [RFC5322] format of <user>@<domain>.

Alice has the account and the DNS configuration file for has the following entries: SRV 0 10 80 SRV 0 40 80 TXT "version=1.0-2.0"       CNAME     A     A TXT "path=/service"     A     A

The client attempts to resolve the address as follows:

  1. Client attempts to resolve SRV and TXT records for
  2. DNS resolver returns two SRV entries and one TXT entry
  3. Client makes a random selection between host1 (20% weighting) and host2 (80% weighting). Chooses host1.
  4. Client resolves A/AAAA for and TXT for
  5. DNS resolver returns A= and TXT=none
  6. Client attempts to POST Web Service request to at host address
  7. The host at returns 503 Service Unavailable
  8. Client resolves A/AAAA for and TXT for
  9. DNS resolver returns A= and TXT "path=/service"
  10. Client attempts to POST Web Service request to at host address
  11. Request succeeds, session proceeds.

If the same client is used in a network location where the SRV record resolution fails due to a faulty firewall configuration, the resolution proceeds as follows:

  1. Client attempts to resolve SRV record for
  2. DNS resolver returns 'not found'
  3. Client attempts to resolve A and AAAA record
  4. DNS resolver returns,
  5. Client makes a random selection between (50% weighting) and (50% weighting). Chooses host1.
  6. Client attempts to POST Web Service request to at host address
  7. The host at returns 503 Service Unavailable
  8. Client attempts to POST Web Service request to at host address
  9. Request succeeds, session proceeds.

Note that the main differences between these two scenarios is that the use of the SRV record allows the service configuration to account for load balancing with tiers of fallback support and use of service description information while the use of round robin A/AAAA records does not.

4. Further Work

4.1. Additional Description Keys

The use of service and host descriptions to specify security enhancements is currently being considered. This provides a superset of the capabilities specified in [RFC6698].

  • Specify minimum TLS version.
  • Specify trust roots more flexibly
  • Specify client authentication requirements
  • Use of security enhancements other than TLS.
  • Publish public keys to be used to protect negotiation of security enhancements

The use of service and host descriptions to specify use of non-HTTP presentation transports is currently being considered.

4.2. Service Scaling

This document considers the problem of establishing a connection to a Host providing a particular Web Service. When constructing services at very large scale (e.g. millions of concurrent users), it becomes desirable to enable discovery of a Web Service Host responsible for a particular partition of that data (e.g. a particular user account).

Since this is clearly a different problem, it is judged that the best approach is to give it a different name and rule it out of scope of the present work.

5. Security Considerations

A treatment of the security considerations will follow.

6. IANA Considerations

The following registrations are required:

6.1. Well-Known URIs

The following registration is requested in the well-known URI registry in accordance with [RFC5785]

URI suffix


Change controller

Phillip Hallam-Baker,

Specification document(s):

[This document]

Related information


7. Normative References

Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, DOI 10.17487/RFC2782, , <>.
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <>.
Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, DOI 10.17487/RFC5785, , <>.
Cheshire, S. and M. Krochmal, "DNS-Based Service Discovery", RFC 6763, DOI 10.17487/RFC6763, , <>.

8. Informative References

Hallam-Baker, P., "DNS Web Service Discovery", Work in Progress, Internet-Draft, draft-hallambaker-web-service-discovery-05, , <>.
Resnick, P., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, , <>.
Hoffman, P. and J. Schlyter, "The DNS-Based Authentication of Named Entities (DANE) Transport Layer Security (TLS) Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, , <>.