doc: state klog.krb is obsolete
[openafs.git] / doc / protocol / rfc5864.txt
1 This file is a copy of RFC 5864 as published by the RFC Editor with the
2 addition of the following license grant.
3
4    As a special additional grant of rights as permitted by section 3(e) of
5    the IETF Trust License Policy (December 28, 2009), in addition to the
6    rights granted in the Copyright Notice below, Russ Allbery, as the sole
7    author of this document, releases it under the following license:
8
9    Copyright 2009, 2010 Russ Allbery <rra@stanford.edu>
10    Copyright 2010 IETF Trust
11
12    Permission to use, copy, modify, and distribute this document for any
13    purpose and without fee is hereby granted, provided that the above
14    copyright notice appear in all copies and that both that copyright
15    notice and this permission notice appear in supporting documentation,
16    and that the name of its authors not be used in advertising or
17    publicity pertaining to distribution of this document without specific,
18    written prior permission.  Its authors make no representations about
19    the suitability of this document for any purpose.  It is provided "as
20    is" without express or implied warranty.
21
22    THIS DOCUMENT IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
23    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
24    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
25
26
27
28
29
30
31 Internet Engineering Task Force (IETF)                        R. Allbery
32 Request for Comments: 5864                           Stanford University
33 Updates: 1183                                                 April 2010
34 Category: Standards Track
35 ISSN: 2070-1721
36
37
38                     DNS SRV Resource Records for AFS
39
40 Abstract
41
42    This document specifies how to use DNS (Domain Name Service) SRV RRs
43    (Resource Records) to locate services for the AFS distributed file
44    system and how the priority and weight values of the SRV RR should be
45    interpreted in the server ranking system used by AFS.  It updates RFC
46    1183 to deprecate the use of the AFSDB RR to locate AFS cell database
47    servers and provides guidance for backward compatibility.
48
49 Status of This Memo
50
51    This is an Internet Standards Track document.
52
53    This document is a product of the Internet Engineering Task Force
54    (IETF).  It represents the consensus of the IETF community.  It has
55    received public review and has been approved for publication by the
56    Internet Engineering Steering Group (IESG).  Further information on
57    Internet Standards is available in Section 2 of RFC 5741.
58
59    Information about the current status of this document, any errata,
60    and how to provide feedback on it may be obtained at
61    http://www.rfc-editor.org/info/rfc5864.
62
63 Copyright Notice
64
65    Copyright (c) 2010 IETF Trust and the persons identified as the
66    document authors.  All rights reserved.
67
68    This document is subject to BCP 78 and the IETF Trust's Legal
69    Provisions Relating to IETF Documents
70    (http://trustee.ietf.org/license-info) in effect on the date of
71    publication of this document.  Please review these documents
72    carefully, as they describe your rights and restrictions with respect
73    to this document.  Code Components extracted from this document must
74    include Simplified BSD License text as described in Section 4.e of
75    the Trust Legal Provisions and are provided without warranty as
76    described in the Simplified BSD License.
77
78
79
80
81
82 Allbery                      Standards Track                    [Page 1]
83 \f
84 RFC 5864                   DNS SRV RRs for AFS                April 2010
85
86
87 Table of Contents
88
89    1. Overview and Rationale ..........................................2
90    2. Scope ...........................................................3
91    3. Requirements Notation ...........................................3
92    4. DNS SRV RRs for AFS .............................................4
93       4.1. Interpretation as AFS Preference Ranks .....................5
94    5. Use of AFSDB RRs ................................................6
95    6. Example .........................................................8
96    7. Security Considerations .........................................9
97    8. References ......................................................9
98       8.1. Normative References .......................................9
99       8.2. Informative References ....................................10
100
101 1.  Overview and Rationale
102
103    AFS (a registered trademark of IBM Corporation) is a distributed file
104    system (see [AFS1] and [AFS2]).  Its most widely used implementations
105    are [OPENAFS] and [ARLA].
106
107    AFS is organized administratively into cells.  Each AFS cell consists
108    of one or more Volume Location Database (VLDB) servers, one or more
109    Protection Service (PTS) servers, and one or more file servers and
110    volume servers, plus possible additional services not relevant to
111    this document.  Data stored in AFS is divided into collections of
112    files called volumes.  An AFS protocol client, when accessing a file
113    within a specific AFS cell, first contacts a VLDB server for that
114    cell to determine the file server for the AFS volume in which that
115    file is located, and then contacts that file server directly to
116    access the file.  A client may also need to contact a PTS server for
117    that cell to register before accessing files in that cell or to query
118    protection database information.
119
120    An AFS client therefore needs to determine, for a given AFS cell, the
121    VLDB and possibly the PTS servers for that cell.  (Traditionally, the
122    VLDB and PTS servers are provided by the same host.)  Once the client
123    is in contact with the VLDB server, it locates file and volume
124    servers through AFS protocol queries to the VLDB server.  Originally,
125    VLDB server information was configured separately on each client in a
126    file called the CellServDB file.  [RFC1183] specified the DNS RR
127    (Resource Record) AFSDB to locate VLDB servers for AFS.
128
129    Subsequent to [RFC1183], a general DNS RR was defined by [RFC2782]
130    for service location for any service.  This DNS SRV RR has several
131    advantages over the AFSDB RR:
132
133
134
135
136
137
138 Allbery                      Standards Track                    [Page 2]
139 \f
140 RFC 5864                   DNS SRV RRs for AFS                April 2010
141
142
143    o  AFSDB RRs do not support priority or ranking, leaving AFS cell
144       administrators without a way to indicate which VLDB servers
145       clients should prefer.
146
147    o  AFSDB RRs do not include protocol or port information, implicitly
148       assuming that all VLDB servers will be contacted over the standard
149       port and the UDP.  Future changes to the AFS protocol may require
150       separate VLDB server lists for UDP and TCP traffic, and some uses
151       of AFS, such as providing VLDB service for multiple cells from the
152       same systems, require use of different ports.
153
154    o  Clients using AFSDB RRs must assume that VLDB and PTS services are
155       provided by the same host, but it may be useful to separate VLDB
156       servers from PTS servers.
157
158    o  DNS SRV RRs are in widespread use, whereas AFSDB RRs are a little-
159       known and little-supported corner of the DNS protocol.
160
161    For those reasons, it is desirable to move AFS service location from
162    the AFSDB RR to DNS SRV RRs.
163
164 2.  Scope
165
166    This document describes the format and use of DNS SRV RRs for AFS
167    service location and deprecates the AFSDB RR.  It also provides
168    guidance for transition from the AFSDB RR to DNS SRV RRs and
169    recommendations for backward compatibility.
170
171    Documentation of the AFS protocol, the exact purpose and use of the
172    VLDB and PTS services, and other information about AFS are outside
173    the scope of this document.
174
175    AFSDB RRs may also be used for locating servers for the Open Software
176    Foundation's (OSF's) Distributed Computing Environment (DCE)
177    authenticated naming system, as described in [RFC1183].  Service
178    location for DCE servers is outside the scope of this document and is
179    not modified by this specification.
180
181 3.  Requirements Notation
182
183    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
184    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
185    document are to be interpreted as described in [RFC2119].
186
187
188
189
190
191
192
193
194 Allbery                      Standards Track                    [Page 3]
195 \f
196 RFC 5864                   DNS SRV RRs for AFS                April 2010
197
198
199 4.  DNS SRV RRs for AFS
200
201    The label of a DNS SRV RR, as defined in [RFC2782], is:
202
203        _<service>._<proto>.<name>
204
205    The following values for <service> advertise servers providing AFS
206    services:
207
208    afs3-vlserver:  servers providing AFS VLDB services.
209
210    afs3-prserver:  servers providing AFS PTS services.
211
212    Other AFS services, such as file and volume management services, are
213    located through the VLDB service and therefore do not use DNS SRV
214    RRs.
215
216    <proto> MUST be "udp" for the current AFS protocol, which uses Rx
217    over UDP.  Other values may be used for future revisions of the AFS
218    protocol supporting other protocols, such as Rx over TCP.
219
220    <name> MUST be the AFS cell name for which the identified server
221    provides AFS services.  Clients MUST query DNS SRV RRs only for a
222    <name> value exactly matching the AFS cell of interest.  They MUST
223    NOT remove leading components to search for more general DNS SRV RRs.
224    The AFS cell "prod.example.com" and the AFS cell "example.com" are
225    entirely different cells in the AFS protocol and VLDB servers for the
226    latter cannot provide information for the former.
227
228       NOTE: As with AFSDB RRs, this means that DNS SRV RRs can only be
229       used to locate AFS services for cells whose naming matches the
230       structure of the DNS.  This is not a requirement of the AFS
231       protocol, but sites creating new AFS cells SHOULD use names that
232       follow the structure of the DNS and that result in DNS SRV RRs
233       under their administrative control.  This both permits use of DNS
234       SRV RRs instead of client configuration and helps avoid naming
235       conflicts between separate AFS cells.
236
237    DNS SRV RRs include a priority and a weight.  As defined in the DNS
238    SRV RR specification [RFC2782], clients MUST attempt to contact the
239    target host with the lowest-numbered priority they can reach.  AFS
240    clients that use a ranked algorithm to determine which server to
241    contact MUST therefore assign a sufficiently distinct rank to targets
242    with different priorities such that targets with a higher-numbered
243    priority are only contacted if all targets with a lower-numbered
244    priority are inaccessible.  See Section 4.1 for more information.
245
246
247
248
249
250 Allbery                      Standards Track                    [Page 4]
251 \f
252 RFC 5864                   DNS SRV RRs for AFS                April 2010
253
254
255    If there are multiple targets with an equal priority, the weight
256    value of the DNS SRV RR SHOULD be used as input to a weighted
257    algorithm for selecting servers.  As specified by [RFC2782], larger
258    weights SHOULD be given a proportionately higher probability of being
259    selected.  In the presence of records containing weights greater than
260    0, records with weight 0 should have a very small chance of being
261    selected.  A weight of 0 SHOULD be used if all targets with that
262    priority are weighted equally.  AFS clients MAY take into account
263    network performance and other protocol metrics along with SRV RR
264    weights when selecting servers, thereby possibly selecting different
265    servers than a system based purely on the SRV RRs would indicate.
266    However, such information MUST NOT override the priority information
267    in the SRV RR.
268
269    DNS SRV RRs, like all DNS RRs, have a time-to-live (TTL), after which
270    the SRV record information is no longer valid (see [RFC1034]).  DNS
271    RRs SHOULD be discarded after their TTL, and after the DNS query
272    repeated.  This applies to DNS SRV RRs for AFS as it does for any
273    other DNS RR.  Any information derived from the DNS SRV RRs, such as
274    preference ranks, MUST be discarded when the DNS SRV RR is expired.
275
276    Implementations are not required to re-run the weighted server
277    selection algorithm for each call.  Instead, they MAY reuse the
278    results of the algorithm until the DNS SRV RRs expire.  Clients could
279    therefore use a specific server for the lifetime of the DNS SRV
280    records, which may affect the load distribution properties that DNS
281    SRV records provide.  Server operators should account for this effect
282    when setting the TTL of those records.
283
284    AFS clients MAY remember which targets are inaccessible by that
285    client and ignore those targets when determining which server to
286    contact first.  Clients that do this SHOULD have a mechanism to retry
287    targets that were previously inaccessible and reconsider them
288    according to their current priority and weight if they become
289    accessible again.
290
291 4.1.  Interpretation as AFS Preference Ranks
292
293    Several AFS implementations use a ranking algorithm that assigns
294    numbers representing a preference rank to each server when the client
295    first contacts that AFS cell and then prefers the server with the
296    lowest rank unless that server goes down.  Clients using this
297    algorithm SHOULD assign their ranks as follows:
298
299    1.  Sort targets by priority and assign a base rank value to each
300        target based on its priority.  Each base rank value MUST be
301        sufficiently different from the base rank assigned to any higher-
302        numbered priority so that higher-numbered targets will only be
303
304
305
306 Allbery                      Standards Track                    [Page 5]
307 \f
308 RFC 5864                   DNS SRV RRs for AFS                April 2010
309
310
311        attempted if lower-numbered targets cannot be reached.  It MUST,
312        in other words, be farther from the base rank of any distinct
313        priority than any possible automatic adjustment in the rank.
314        When calculating base ranks, observe that the numeric value of a
315        priority has no meaning.  Only the ordering of distinct priority
316        values between multiple SRV RR targets needs to be reflected in
317        the base ranks.
318
319    2.  For each group of targets with the same priority, follow the
320        algorithm in [RFC2782] to order those targets.  Then, assign
321        those targets ranks formed by incrementing the base weight for
322        that priority such that the first selected target has the lowest
323        rank, the second selected target has the next-lowest rank, and so
324        on.
325
326    After assignment of ranks, the AFS client MAY then adjust the ranks
327    dynamically based on network performance and other protocol metrics,
328    provided that such adjustments are sufficiently small compared to the
329    difference between base ranks that they cannot cause servers with a
330    higher-numbered priority to be contacted instead of a server with a
331    lower-numbered priority.
332
333    The TTL of the DNS SRV RRs MUST be honored by invalidating and
334    regenerating the server preference ranks with new DNS information
335    once that TTL has expired.  However, accumulated network and protocol
336    metrics may be retained and reapplied to the new rankings.
337
338    AFS server preference ranks are conventionally numbers between 1 and
339    65535.  DNS SRV RR priorities are numbers between 0 and 65535.
340    Implementations following this algorithm could therefore encounter
341    problems assigning sufficiently distinct base rank values in
342    exceptional cases of very large numbers of DNS SRV RR targets with
343    different priorities.  However, an AFS cell configuration with
344    thousands of DNS SRV RR targets for an AFS VLDB or PTS service with
345    meaningfully distinct priorities is highly improbable.  AFS client
346    implementations encountering a DNS SRV RR containing targets with
347    more distinct priority values than can be correctly represented as
348    base ranks SHOULD fall back to generating ranks based solely on
349    priorities, ignoring other rank inputs, and disabling dynamic
350    adjustment of ranks.  Implementations MUST be able to assign distinct
351    base ranks as described above for at least ten distinct priority
352    values.
353
354 5.  Use of AFSDB RRs
355
356    Since many AFS client implementations currently support AFSDB RRs but
357    do not support DNS SRV RRs, AFS cells providing DNS SRV RRs SHOULD
358    also provide AFSDB RRs.  However, be aware that AFSDB RRs do not
359
360
361
362 Allbery                      Standards Track                    [Page 6]
363 \f
364 RFC 5864                   DNS SRV RRs for AFS                April 2010
365
366
367    provide priority or weighting information; all servers listed in
368    ASFDB RRs are treated as equal.  AFSDB RRs also do not provide port
369    information.
370
371    An AFS cell using DNS SRV RRs SHOULD therefore also provide an AFSDB
372    RR listing all AFS servers for which the following statements are all
373    true:
374
375    o  The server provides both VLDB and PTS service on the standard
376       ports (7003 and 7002, respectively).
377
378    o  The server provides these services via Rx over UDP.
379
380    o  The server either has the lowest-numbered priority of those listed
381       in the DNS SRV RRs or the AFS cell administrator believes it
382       reasonable for clients using AFSDB RRs to use this server by
383       preference.
384
385    The above is a default recommendation.  AFS cell administrators MAY
386    use different lists of servers in the AFSDB RRs and DNS SRV RRs if
387    desired for specific effects based on local knowledge of which
388    clients use AFSDB RRs and which clients use DNS SRV RRs.  However,
389    AFS servers SHOULD NOT be advertised with AFSDB RRs unless they
390    provide VLDB and PTS services via UDP on the standard ports.  (This
391    falls shy of MUST NOT because it may be useful in some unusual
392    circumstances to advertise, via an AFSDB RR, a server that provides
393    only one of the two services, but be aware that such a configuration
394    may confuse legacy clients.)
395
396    An AFS cell SHOULD have at least one VLDB and at least one PTS server
397    providing service on the standard ports of 7003 and 7002,
398    respectively, since clients without DNS SRV RR support cannot locate
399    servers on non-standard ports.
400
401    Clients SHOULD query DNS SRV RRs by default but SHOULD then fall back
402    on AFSDB RRs if no DNS SRV RRs are found.  In the absence of DNS SRV
403    RRs, an AFSDB RR of <subtype> 1 SHOULD be treated as equivalent to
404    the following pair of DNS SRV RRs:
405
406        _afs3-vlserver._udp.<cell> <ttl> IN SRV 0 0 7003 <hostname>
407        _afs3-prserver._udp.<cell> <ttl> IN SRV 0 0 7002 <hostname>
408
409    <cell> is the label of the AFSDB RR, <ttl> is its TTL and <hostname>
410    is the <hostname> value of the AFSDB RR as specified in [RFC1183].
411    This is the fully-qualified domain name of the server.
412
413
414
415
416
417
418 Allbery                      Standards Track                    [Page 7]
419 \f
420 RFC 5864                   DNS SRV RRs for AFS                April 2010
421
422
423 6.  Example
424
425    The following example includes TCP AFS services, separation of a PTS
426    server from a VLDB server, and use of non-standard ports, all
427    features that either assume future AFS protocol development or are
428    not widely supported by current clients.  This example is intended to
429    show the range of possibilities for AFS DNS SRV RRs, not as a
430    practical example for an existing cell.  This is a part of the zone
431    file for a fictional example.com domain with AFS services.
432
433        $ORIGIN example.com.
434        @                    SOA   dns.example.com. root.example.com. (
435                                     2009100201 3600 3600 604800 86400 )
436                             NS    dns.example.com.
437        _afs3-vlserver._udp  SRV   0 2 7003 afsdb1.example.com.
438        _afs3-vlserver._udp  SRV   0 4 7003 afsdb2.example.com.
439        _afs3-vlserver._udp  SRV   1 0 65500 afsdb3.example.com.
440
441        _afs3-vlserver._tcp  SRV   0 0 7003 afsdb3.example.com.
442
443        _afs3-prserver._udp  SRV   0 0 7002 afsdb1.example.com.
444
445        _afs3-prserver._tcp  SRV   0 0 7002 afsdb3.example.com.
446
447        @                    AFSDB 1 afsdb1.example.com.
448
449        dns                  A     192.0.2.9
450        afsdb1               A     192.0.2.10
451        afsdb2               A     192.0.2.11
452        afsdb3               A     192.0.2.12
453
454    In this example, the AFS cell name is example.com.
455
456    afsdb1, afsdb2, and afsdb3 all provide VLDB service via UDP.  The
457    first two have the same priority but have weights indicating that
458    afsdb1 should get about twice as many clients as afsdb2. afsdb3
459    should only be used for UDP VLDB service if afsdb1 and afsdb2 are not
460    accessible and provides that service on a non-standard port (65500).
461
462    Only one host, afsdb1, provides UDP PTS service.
463
464    afsdb3 provides a hypothetical TCP version of AFS VLDB and PTS
465    service on the standard ports and is the only server providing these
466    services over TCP for this cell.  Such a TCP-based AFS protocol did
467    not exist at the time this document was written.  This example only
468    shows what the record would look like in a hypothetical future if
469    such a protocol were developed.
470
471
472
473
474 Allbery                      Standards Track                    [Page 8]
475 \f
476 RFC 5864                   DNS SRV RRs for AFS                April 2010
477
478
479    An AFSDB RR is provided for backward compatibility with older
480    clients.  It lists only afsdb1, since only that host provides both
481    VLDB and PTS service over UDP on the standard ports.
482
483 7.  Security Considerations
484
485    Use of DNS SRV RRs for AFS service locations poses the same security
486    issues as the existing AFSDB RRs.  Specifically, unless the integrity
487    and authenticity of the DNS response are checked, an attacker may
488    forge DNS replies and thereby direct clients at a VLDB or PTS server
489    under the control of the attacker.  From there, the attacker may
490    deceive an AFS client about the volumes and file servers in a cell
491    and about the contents of files and directories in that cell.  If the
492    client uses cell data in a trusted way, such as by executing programs
493    out of that AFS cell or using data from the cell as input to other
494    programs, the attacker may be able to further compromise the security
495    of the client and trick it into taking action under the attacker's
496    control.
497
498    This attack can be prevented if the server is authenticated, since
499    the client can then detect a failure to authenticate the attacker's
500    servers and thereby detect possible impersonation.  However, this
501    applies only to authenticated AFS access, and much AFS access is
502    unauthenticated.  Furthermore, clients after failure to authenticate
503    may fall back to unauthenticated access, which the attacker's servers
504    may permit.
505
506    Using an integrity-protected DNS system such as DNS Security (DNSSEC)
507    [RFC4033] can prevent this attack via DNS.  However, the underlying
508    vulnerability is inherent in the current AFS protocol and may be
509    exploited in ways other than DNS forgery, such as by forging the
510    results of VLDB queries for an AFS cell.  Addressing it properly
511    requires changes to the AFS protocol allowing clients to always
512    authenticate AFS services and discard unauthenticated data.  Even in
513    the absence of a DNS system with integrity protection, addition of
514    DNS SRV RRs does not make this vulnerability more severe, only opens
515    another equivalent point of attack.
516
517 8.  References
518
519 8.1.  Normative References
520
521    [RFC1034]  Mockapetris, P., "Domain names - concepts and facilities",
522               STD 13, RFC 1034, November 1987.
523
524    [RFC1183]  Everhart, C., Mamakos, L., Ullmann, R., and P.
525               Mockapetris, "New DNS RR Definitions", RFC 1183,
526               October 1990.
527
528
529
530 Allbery                      Standards Track                    [Page 9]
531 \f
532 RFC 5864                   DNS SRV RRs for AFS                April 2010
533
534
535    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
536               Requirement Levels", BCP 14, RFC 2119, March 1997.
537
538    [RFC2782]  Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
539               specifying the location of services (DNS SRV)", RFC 2782,
540               February 2000.
541
542 8.2.  Informative References
543
544    [AFS1]     Howard, J., Kazar, M., Menees, S., Nichols, D.,
545               Satyanarayanan, M., Sidebotham, R., and M. West, "Scale
546               and Performance in a Distributed File System", ACM Trans.
547               on Computer Systems 6(1), February 1988.
548
549    [AFS2]     Howard, J., "An Overview of the Andrew File System", CMU-
550               ITC 88-062, February 1988.
551
552    [ARLA]     Assar Westerlund, et al., "Arla", May 2001,
553               <http://www.stacken.kth.se/project/arla/html/arla.html>.
554
555    [OPENAFS]  IBM Corporation, et al., "OpenAFS Documentation",
556               April 2000, <http://docs.openafs.org/>.
557
558    [RFC4033]  Arends, R., Austein, R., Larson, M., Massey, D., and S.
559               Rose, "DNS Security Introduction and Requirements",
560               RFC 4033, March 2005.
561
562 Author's Address
563
564    Russ Allbery
565    Stanford University
566    P.O. Box 20066
567    Stanford, CA  94309
568    US
569
570    EMail: rra@stanford.edu
571    URI:   http://www.eyrie.org/~eagle/
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586 Allbery                      Standards Track                   [Page 10]
587 \f