-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathrfc5854.xml
More file actions
2299 lines (1713 loc) · 90.7 KB
/
rfc5854.xml
File metadata and controls
2299 lines (1713 loc) · 90.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="US-ASCII"?>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes" ?>
<?rfc tocdepth="3" ?>
<?rfc tocindent="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc rfcedstyle="yes" ?>
<?rfc subcompact="no" ?>
<!DOCTYPE rfc
PUBLIC "" "rfc2629.dtd">
<rfc number="5854" category="std" >
<!-- [rfced] Please note that after you have approved the document,
post-xml2rfc changes will be made to update the header and
boilerplate as described in RFC 5741.
-->
<front>
<title abbrev="Metalink Download Description Format">The Metalink Download Description Format</title>
<author initials="A." surname="Bryan" fullname="Anthony Bryan">
<organization></organization>
<address>
<postal>
<street></street>
<city>Pompano Beach</city>
<region>FL</region>
<country>USA</country>
</postal>
<email>anthonybryan@gmail.com</email>
<uri>http://www.metalinker.org</uri>
</address>
</author>
<author initials="T." surname="Tsujikawa" fullname="Tatsuhiro Tsujikawa">
<organization></organization>
<address>
<postal>
<street></street>
<city></city>
<region>Shiga</region>
<country>Japan</country>
</postal>
<email>tatsuhiro.t@gmail.com</email>
<uri>http://aria2.sourceforge.net</uri>
</address>
</author>
<author initials="N." surname="McNab" fullname="Neil McNab">
<organization></organization>
<!-- [rfced] N. McNab, would you like to add an organization here? Or
be listed as "Consultant"? -->
<address>
<postal>
<street></street>
<city>San Diego</city>
<region>CA</region>
<country>USA</country>
</postal>
<email>neil@nabber.org</email>
<uri>http://www.nabber.org</uri>
</address>
</author>
<author initials="P." surname="Poeml" fullname="Dr. med. Peter Poeml">
<organization>MirrorBrain</organization>
<address>
<postal>
<street>Venloer Str. 317</street>
<city>Koeln</city>
<code>50823</code>
<country>DE</country>
</postal>
<phone>+49 221 6778 333 8</phone>
<email>peter@poeml.de</email>
<uri>http://mirrorbrain.org/~poeml/</uri>
</address>
</author>
<date month="May" year="2010"/>
<!--[rfced] Please insert any keywords (beyond those that appear in
the title) for use on http://www.rfc-editor.org/rfcsearch.html.
-->
<keyword>file transfer</keyword>
<keyword>mirrors</keyword>
<keyword>data integrity</keyword>
<keyword>hash</keyword>
<keyword>xml</keyword>
<keyword>http</keyword>
<keyword>hypertext transfer protocol</keyword>
<keyword>ftp</keyword>
<keyword>file transfer protocol</keyword>
<keyword>metadata</keyword>
<keyword>torrent</keyword>
<abstract>
<t>This document specifies Metalink, an XML-based download description
format. Metalink describes download locations
(mirrors), cryptographic hashes, and other information. Clients can
transparently use this information to reliably transfer
files.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>Metalink is a document format based on Extensible Markup Language (XML) that describes a file or list
of files to be downloaded from a server. Metalinks can list a number of
files, each with an extensible set of attached metadata.
Each listed file can have a description, multiple cryptographic hashes, and a list of Uniform Resource Identifiers (URIs) from which it is
available.</t>
<t>Often, identical copies of a file are accessible in multiple locations
on the Internet over a variety of protocols, such as File Transfer Protocol (FTP), Hypertext Transfer Protocol (HTTP), and
Peer-to-Peer (P2P). In some cases, users are shown a list of these multiple
download locations (mirror servers) and must manually select one based on
geographical location, priority, or bandwidth. This is done to distribute
the load across multiple servers, and to give human users the opportunity
to choose a download location that they expect to work best for them.</t>
<t>At times, individual servers can be
slow, outdated, or unreachable, but this cannot be determined until the
download has been initiated. This can lead to the user canceling the
download and needing to restart it. During downloads, errors in
transmission can corrupt the file. There are no easy ways to repair
these files. For large downloads, this can be especially troublesome. Any
of the number of problems that can occur during a download lead to
frustration on the part of users, and bandwidth wasted with retransmission.</t>
<t>Knowledge about availability of a download on mirror servers can be
acquired and maintained by the operators of the origin server or by a third
party. This knowledge, together with cryptographic hashes,
digital signatures, and more, can be stored in a machine-readable Metalink
file. The Metalink file can transfer this knowledge to the user agent,
which can peruse it in automatic ways or present the information to a human user.
User agents can fall back to alternate
mirrors if the current one has an issue. Thereby, clients
are enabled to work their way to a successful download under adverse
circumstances. All this can be done transparently to the human user and the
download is much more reliable and efficient. In contrast, a traditional
HTTP redirect to one mirror conveys only comparatively minimal information --
a referral to a single server, and there is no provision in the HTTP protocol to
handle failures.</t>
<t>Other features that some clients provide include multi-source
downloads, where chunks of a file are downloaded from multiple mirrors
(and optionally, Peer-to-Peer) simultaneously, which frequently results
in a faster download. Metalinks can leverage HTTP, FTP, and Peer-to-Peer
protocols together, because regardless of the protocol over
which the Metalink
was obtained, it can make a resource accessible through other protocols.
If the Metalink was obtained from a trusted source, included verification
metadata can solve trust issues when downloading files from replica
servers operated by third parties. Metalinks also provide structured
information about downloads that can be indexed by search engines.</t>
<section title="Examples"><t><figure>
<preamble>A brief, Metalink Document that describes a single file:</preamble>
<artwork type="example">
<?xml version="1.0" encoding="UTF-8"?>
<metalink xmlns="urn:ietf:params:xml:ns:metalink">
<file name="example.ext">
<size>14471447</size>
<url>ftp://ftp.example.com/example.ext</url>
<url>http://example.com/example.ext</url>
<metaurl mediatype="torrent">
http://example.com/example.ext.torrent</metaurl>
</file>
</metalink>
</artwork></figure></t>
<t>
<figure>
<preamble>A more extensive Metalink Document that describes two files:</preamble>
<artwork type="example">
<?xml version="1.0" encoding="UTF-8"?>
<metalink xmlns="urn:ietf:params:xml:ns:metalink">
<published>2009-05-15T12:23:23Z</published>
<file name="example.ext">
<size>14471447</size>
<identity>Example</identity>
<version>1.0</version>
<language>en</language>
<description>
A description of the example file for download.
</description>
<hash type="sha-256">f0ad929cd259957e160ea442eb80986b5f01...</hash>
<url location="de"
priority="1">ftp://ftp.example.com/example.ext</url>
<url location="fr"
priority="1">http://example.com/example.ext</url>
<metaurl mediatype="torrent"
priority="2">http://example.com/example.ext.torrent</metaurl>
</file>
<file name="example2.ext">
<size>14471447</size>
<identity>Example2</identity>
<version>1.0</version>
<language>en</language>
<description>
Another description for a second file.
</description>
<hash type="sha-256">2f548ce50c459a0270e85a7d63b2383c5523...</hash>
<url location="de"
priority="1">ftp://ftp.example.com/example2.ext</url>
<url location="fr"
priority="1">http://example.com/example2.ext</url>
<metaurl mediatype="torrent"
priority="2">http://example.com/example2.ext.torrent</metaurl>
</file>
</metalink></artwork>
</figure>
</t>
</section>
<section title="Namespace and Version" anchor="namespace.and.version">
<t>The XML Namespaces URI <xref target="REC-xml-names"/> for the XML data
format described in this specification is:</t>
<t>urn:ietf:params:xml:ns:metalink</t>
<t>For convenience, this data format may be referred to as
"Metalink", which this specification uses internally.</t>
</section>
<section title="Notational Conventions">
<t>This specification describes conformance of Metalink
Documents. Additionally, it places some requirements on Metalink
Processors.</t>
<t>This specification uses the namespace prefix "metalink:" for
the Namespace URI identified in <xref target="namespace.and.version"/>, above. Note that
the choice of namespace prefix is arbitrary and not
semantically significant.</t>
<t>Metalink is specified using terms from the XML Infoset <xref target="REC-xml-infoset"/>. However, this
specification uses a shorthand for two common terms: the
phrase "Information Item" is omitted when naming Element
Information Items and Attribute Information Items. Therefore,
when this specification uses the term "element," it is
referring to an Element Information Item in Infoset
terms. Likewise, when it uses the term "attribute," it is
referring to an Attribute Information Item.</t>
<t>Some sections of this specification are illustrated with fragments
of a non-normative RELAX NG Compact schema <xref target="RELAX-NG"/>. However, the text of this specification provides the definition of
conformance. A complete schema appears in <xref target="schema"/>.
</t>
<t>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 BCP 14, <xref target="RFC2119"/>, as scoped to those conformance targets.</t>
</section>
</section>
<section title="Metalink Documents" anchor="metalink.documents">
<t>This specification describes Metalink Documents.</t>
<t>A Metalink Document describes a file or group of files,
how to access them, and metadata that identifies them. Its root is the <xref target="element.metalink" format="none">metalink:metalink</xref> element.</t>
<figure>
<artwork type="application/relax-ng-compact-syntax">
namespace metalink = "urn:ietf:params:xml:ns:metalink"
start = metalinkMetalink</artwork>
</figure>
<t>Metalink Documents are specified in terms of the
XML Information Set, serialized as XML 1.0 <xref target="REC-xml"/> and identified with the
"application/metalink4+xml" media type.</t>
<t>Metalink Documents MUST be
well-formed XML. This specification does not define a Document Type Definition (DTD) for
Metalink Documents, and hence it does not require them to be valid (in
the sense used by XML).</t>
<t>Metalink allows the use of Internationalized Resource Identifiers (IRIs), encoded according to <xref target="RFC3987"/>. Every
URI <xref target="RFC3986"/> is also an IRI, so a URI may be used wherever an IRI is named below.
<!--[rfced] Please rephrase to make the sentence above more clear.
Original:
Every URI [RFC3986] is also
an IRI, so a URI may be used wherever below an IRI is named.
Suggested:
Every URI [RFC3986] is also
an IRI, so a URI may be used wherever an IRI is named below.
-->
There is one special
consideration: when an IRI that is not also a URI is given for
dereferencing, it MUST be mapped to a URI using the steps in
Section 3.1 of <xref target="RFC3987"/>.</t>
<t>Any element defined by this specification MAY have an
xml:lang attribute, whose content indicates the natural language
for the element and its descendents. The language context is only
significant for elements and attributes declared to be
"Language-Sensitive" by this specification. Requirements
regarding the content and interpretation of xml:lang are
specified in <xref target="REC-xml">XML 1.0</xref>,
Section 2.12.
<figure>
<iref item="metalinkCommonAttributes grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkCommonAttributes" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkCommonAttributes =
attribute xml:lang { metalinkLanguageTag }?,
undefinedAttribute*</artwork> </figure></t>
<t>All leading and trailing whitespace is part of the element content and MUST NOT be ignored. Consequently, it is disallowed for elements where the defined type does not allow whitespace, such as dates, integers, or IRIs.
Some XML-generating implementations erroneously insert whitespace around values by default, and such implementations will generate invalid Metalink Documents.</t>
<t>Metalink Documents that do not follow this specification are invalid and SHOULD NOT be used by Metalink Processors.</t>
<t>Metalink is an extensible format. See <xref target="extending_metalink"/>
of this document for a full description of how Metalink Documents can
be extended.</t>
</section>
<section title="Common Metalink Constructs">
<t>Many Metalink elements share common structures. This section
defines those structures and their requirements for convenient
reference by the appropriate element definitions.</t>
<t>When an element is identified as being a particular kind of
construct, it inherits the corresponding requirements from that
construct's definition in this section.</t>
<section title="Text Constructs" anchor="text.constructs">
<t>A Text construct contains human-readable text, usually short
in length.
<figure>
<iref item="metalinkTextConstruct grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkTextConstruct" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkTextConstruct =
metalinkCommonAttributes,
text</artwork></figure></t>
<t>For example, a <xref target="element.description" format="none">metalink:description</xref> with text content:
<figure>
<artwork type="example">
...
<description>
A description of the example file for download.
</description>
...</artwork>
</figure>
</t>
<t>The content of the Text
construct MUST NOT contain child elements. Such text is
intended to be presented to humans in a readable fashion.
Thus, whitespace could be collapsed (including
line breaks), and text could be displayed using typographic
techniques such as justification and proportional
fonts.</t>
</section>
<section title="Date Constructs" anchor="date.constructs">
<t>A Date construct is an element whose content MUST conform
to the "date-time" production in <xref target="RFC3339"/>. In addition, an uppercase "T" character
MUST be used to separate date and time, and an uppercase "Z"
character MUST be present in the absence of a numeric time zone
offset.
<figure>
<iref item="metalinkDateConstruct grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkDateConstruct" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkDateConstruct =
metalinkCommonAttributes,
xsd:dateTime</artwork></figure></t>
<t>Such date values happen to be compatible with the following
specifications:
<xref target="ISO.8601.1988"/>,
<xref target="NOTE-datetime-19980827"/>,
and <xref target="REC-xmlschema-2-20041028"/>.</t>
<t>Example Date constructs:
<figure>
<artwork type="example">
...
<updated>2010-05-01T12:15:02Z</updated>
...
<updated>2010-05-01T12:15:02.25Z</updated>
...
<updated>2010-05-01T12:15:02+01:00</updated>
...
<updated>2010-05-01T12:15:02.25+01:00</updated>
...
</artwork>
</figure>
</t>
</section>
</section>
<section title="Metalink Element Definitions">
<section title="Container Elements">
<section anchor="element.metalink" title="The "metalink:metalink" Element">
<iref item="XML Elements" subitem="metalink" primary="true"/>
<iref item="metalink XML element" primary="true"/>
<t>The "metalink:metalink" element is the document (i.e., top-level) element
of a Metalink Document, acting as a container for metadata and
data associated with the listed files. It contains one or more <xref target="element.file" format="none">metalink:file</xref> child elements that consist of
Metadata elements.
<figure>
<iref item="metalinkMetalink grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkMetalink" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkMetalink =
element metalink:metalink {
metalinkCommonAttributes,
(metalinkFile+
& metalinkGenerator?
& metalinkOrigin?
& metalinkPublished?
& metalinkUpdated?
& extensionElement*)
}</artwork></figure></t>
<t>The following child elements are defined by this specification
(note that the presence of some of these elements is required):</t>
<t>
<list style="symbols">
<t><xref target="element.metalink" format="none">metalink:metalink</xref> elements MUST contain one or more <xref target="element.file" format="none">metalink:file</xref> elements.</t>
<t><xref target="element.metalink" format="none">metalink:metalink</xref> elements MAY contain exactly one <xref target="element.generator" format="none">metalink:generator</xref> element and MUST NOT contain more than one such element.</t>
<t><xref target="element.metalink" format="none">metalink:metalink</xref> elements SHOULD contain exactly one <xref target="element.origin" format="none">metalink:origin</xref> element and MUST NOT contain more than one such element.</t>
<t><xref target="element.metalink" format="none">metalink:metalink</xref> elements MAY contain exactly one <xref target="element.published" format="none">metalink:published</xref> element and MUST NOT contain more than one such element.</t>
<t><xref target="element.metalink" format="none">metalink:metalink</xref> elements MAY contain exactly one <xref target="element.updated" format="none">metalink:updated</xref> element and MUST NOT contain more than one such element.</t>
</list></t>
<section toc="exclude" title="Providing Textual Content">
<t>Experience teaches that downloads providing textual
content are, in general, more useful than those that do
not. Some applications (one example is full-text indexers)
require a minimum amount of text to function
reliably and predictably. Metalink publishers should be aware
of this. It is RECOMMENDED that each <xref target="element.file" format="none">metalink:file</xref>
element contain a non-empty <xref target="element.description" format="none">metalink:description</xref> element, a
non-empty <xref target="element.identity" format="none">metalink:identity</xref> element, a non-empty <xref target="element.version" format="none">metalink:version</xref> element, and a non-empty
<xref target="element.publisher" format="none">metalink:publisher</xref> element when these elements are present. However, the
absence of <xref target="element.description" format="none">metalink:description</xref>, <xref target="element.identity" format="none">metalink:identity</xref>, <xref target="element.version" format="none">metalink:version</xref>, and <xref target="element.publisher" format="none">metalink:publisher</xref> is not an error, and Metalink
Processors MUST NOT fail to function correctly as a
consequence of such an absence.</t>
</section>
</section>
<section anchor="element.file" title="The "metalink:file" Element">
<iref item="XML Elements" subitem="file" primary="true"/>
<iref item="file XML element" primary="true"/>
<t>The "<xref target="element.file" format="none">metalink:file</xref>" element represents an individual file,
acting as a container for metadata and data associated with
the file. Each unique file described in a Metalink Document MUST have its own <xref target="element.file" format="none">metalink:file</xref> element.</t>
<t>All <xref target="element.url" format="none">metalink:url</xref> elements contained in each <xref target="element.file" format="none">metalink:file</xref> element SHOULD lead to identical files. That is,
each <xref target="element.url" format="none">metalink:url</xref> element should be an alternative location for the same file and each
<xref target="element.metaurl" format="none">metalink:metaurl</xref> element should provide metadata to retrieve the same file in another way, such as a Peer-to-Peer network. Refer to Sections <xref target="element.metaurl" format="counter"/> and <xref target="element.url" format="counter"/> for more information.
<figure>
<iref item="metalinkFile grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkFile" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkFile =
element metalink:file {
metalinkCommonAttributes,
attribute name { text },
(metalinkCopyright?
& metalinkDescription?
& metalinkHash*
& metalinkIdentity?
& metalinkLanguage*
& metalinkLogo?
& metalinkMetaURL*
& metalinkOS*
& metalinkPieces*
& metalinkPublisher?
& metalinkSignature?
& metalinkSize?
& metalinkURL*
& metalinkVersion?
& extensionElement*)
}</artwork></figure></t>
<t>This specification assigns no significance to the order of
<xref target="element.file" format="none">metalink:file</xref> elements or to the order of
<xref target="element.url" format="none">metalink:url</xref> or <xref target="element.metaurl" format="none">metalink:metaurl</xref> elements. Significance is determined by the value of the "priority" attribute of the <xref target="element.url" format="none">metalink:url</xref> or <xref target="element.metaurl" format="none">metalink:metaurl</xref> elements.</t>
<t>The following child elements are defined by this specification
(the presence of some of them is required):</t>
<t>
<list style="symbols">
<t><xref target="element.file" format="none">metalink:file</xref> elements MAY contain exactly one <xref target="element.copyright" format="none">metalink:copyright</xref>
element and MUST NOT contain more than one such element.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements MAY contain exactly one <xref target="element.description" format="none">metalink:description</xref>
element and MUST NOT contain more than one such element.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements MAY contain exactly one <xref target="element.identity" format="none">metalink:identity</xref>
element and MUST NOT contain more than one such element.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements MAY contain one or more <xref target="element.hash" format="none">metalink:hash</xref> elements.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements MAY contain one or more <xref target="element.language" format="none">metalink:language</xref>
elements.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements MAY contain exactly one <xref target="element.logo" format="none">metalink:logo</xref>
element and MUST NOT contain more than one such element.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements MAY contain one or more <xref target="element.os" format="none">metalink:os</xref>
element.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements MUST contain at least one <xref target="element.url" format="none">metalink:url</xref> element or at least one <xref target="element.metaurl" format="none">metalink:metaurl</xref> element. Typically, <xref target="element.file" format="none">metalink:file</xref> elements contain more than one <xref target="element.url" format="none">metalink:url</xref> element to provide multiple download sources.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements MAY contain one or more <xref target="element.pieces" format="none">metalink:pieces</xref> elements.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements MAY contain exactly one <xref target="element.publisher" format="none">metalink:publisher</xref>
element and MUST NOT contain more than one such element.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements MAY contain one or more <xref target="element.signature" format="none">metalink:signature</xref> elements.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements SHOULD contain exactly one <xref target="element.size" format="none">metalink:size</xref>
element and MUST NOT contain more than one such element.</t>
<t><xref target="element.file" format="none">metalink:file</xref> elements MAY contain exactly one <xref target="element.version" format="none">metalink:version</xref>
element and MUST NOT contain more than one such element.</t>
</list>
</t>
<section title="The "name" Attribute">
<t><xref target="element.file" format="none">metalink:file</xref> elements MUST have a "name" attribute, which contains the local file name to which the downloaded file will be written. Hence, if a Metalink Document contains multiple <xref target="element.file" format="none">metalink:file</xref> elements, the value of the "name" attribute MUST be unique for each.
<figure>
<preamble>Directory information can also be contained in a "path/file" format only, as in:</preamble>
<artwork type="example">
<file name="debian-amd64/sarge/Contents-amd64.gz">
</artwork></figure></t>
<t>In this example, a subdirectory "debian-amd64/sarge/" will be created
and a file named "Contents-amd64.gz" will be created inside it.</t>
<t><list style='empty'><t>Security Note:
The path MUST NOT contain any directory traversal directives or
information. The path MUST be relative. The path MUST NOT begin with a "/", "./", or
"../"; contain "/../"; or end with "/..".</t></list></t>
</section>
</section>
<section anchor="element.pieces" title="The "metalink:pieces" Element">
<iref item="XML Elements" subitem="pieces" primary="true"/>
<iref item="pieces XML element" primary="true"/>
<t>The "<xref target="element.pieces" format="none">metalink:pieces</xref>" element acts as a container for a list of cryptographic hashes of
contiguous, non-overlapping pieces of the file. The cryptographic hashes MUST be listed in the same order as the corresponding pieces appear in the file, starting at
the beginning of the file. Metalink Documents MAY contain one or multiple <xref target="element.pieces" format="none">metalink:pieces</xref> container elements, if each "type" attribute of <xref target="element.pieces" format="none">metalink:pieces</xref> has a unique value.
<figure>
<iref item="metalinkPieces grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkPieces" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkPieces =
element metalink:pieces {
attribute length { xsd:positiveInteger },
attribute type { text },
metalinkHash+
}</artwork></figure></t>
<section title="The "type" Attribute">
<t><xref target="element.pieces" format="none">metalink:pieces</xref> elements MUST have a "type" attribute.
</t>
<t>The Internet Assigned Numbers Authority (IANA) registry named "Hash Function Textual Names" defines values for hash types. See <xref target="security.hash"/> for security implications.</t>
</section>
<section title="The "length" Attribute" anchor="piece.length">
<t><xref target="element.pieces" format="none">metalink:pieces</xref> elements MUST have a "length" attribute, which is a positive integer
that describes the length of the pieces of the file in octets. The whole file is divided into non-overlapping pieces of this length,
starting from the beginning of the file. That is, every piece MUST be the same size, apart from
the last piece, which is the remainder. The last piece extends to the end of the file, and it therefore MAY be shorter than the other pieces.
</t>
</section>
</section>
</section>
<section title="Metadata Elements">
<section anchor="element.copyright" title="The "metalink:copyright" Element">
<iref item="XML Elements" subitem="copyright" primary="true"/>
<iref item="copyright XML element" primary="true"/>
<t>The "<xref target="element.copyright" format="none">metalink:copyright</xref>" element is a Text construct that conveys a
human-readable copyright for a file. It is Language-Sensitive.
<figure>
<iref item="metalinkCopyright grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkCopyright" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkCopyright =
element metalink:copyright {
metalinkTextConstruct
}</artwork></figure></t>
</section>
<section anchor="element.description" title="The "metalink:description" Element">
<iref item="XML Elements" subitem="description" primary="true"/>
<iref item="description XML element" primary="true"/>
<t>The "<xref target="element.description" format="none">metalink:description</xref>" element is a Text construct that conveys a
human-readable file description. It is Language-Sensitive.
<figure>
<iref item="metalinkDescription grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkDescription" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkDescription =
element metalink:description {
metalinkTextConstruct
}</artwork></figure></t>
</section>
<section anchor="element.generator" title="The "metalink:generator" Element">
<iref item="XML Elements" subitem="generator" primary="true"/>
<iref item="generator XML element" primary="true"/>
<t>The "<xref target="element.generator" format="none">metalink:generator</xref>" element's content identifies the generating agent name and version used to generate a Metalink Document, for debugging and other purposes.
<figure>
<iref item="metalinkGenerator grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkGenerator" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkGenerator =
element metalink:generator {
metalinkTextConstruct
}</artwork></figure></t>
<t>The <xref target="element.generator" format="none">metalink:generator</xref> element's content is defined below in ABNF notation <xref target="RFC5234"/>.
<!-- [rfced] In the ABNF below, in the rule for separators,
should <"> be changed to DQUOTE ?
This note is from Bill's ABNF parser (http://tools.ietf.org/tools/bap/abnf.cgi)
fyi: suggest DQUOTE or %x22 instead of <">.
-->
<figure>
<iref item="metalinkGenerator ABNF" primary="true"/>
<iref item="ABNF" subitem="metalinkGenerator" primary="true"/>
<artwork type="ABNF">
token = 1*<any CHAR except CTLs or separators>
separators = "(" / ")" / "<" / ">" / "@"
/ "," / ";" / ":" / "\" / DQUOTE
/ "/" / "[" / "]" / "?" / "="
/ "{" / "}" / SP / HTAB
agent = token ["/" agent-version]
agent-version = token
</artwork></figure></t>
<!-- "-->
<t>Examples:
<figure>
<artwork type="example">
...
<generator>MirrorBrain/2.11</generator>
...
<generator>MirrorManager/1.2.11</generator>
...
<generator>metalinktools/0.3.6</generator>
...
<generator>MetalinkEditor/1.2.0</generator>
...
</artwork>
</figure>
</t>
<t>Although any token character MAY appear in an agent-version, this token SHOULD only be used for a version identifier (i.e., successive versions of the same agent
SHOULD only differ in the agent-version portion of the agent value).</t>
</section>
<section anchor="element.hash" title="The "metalink:hash" Element">
<iref item="XML Elements" subitem="hash" primary="true"/>
<iref item="hash XML element" primary="true"/>
<t>The "<xref target="element.hash" format="none">metalink:hash</xref>" element is a Text construct that conveys a cryptographic
hash for a file. All hashes are encoded in lowercase hexadecimal format. Hashes are used to verify the integrity of a complete file or portion of a file to determine if the file has been transferred without any errors.
<figure>
<iref item="metalinkHash grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkHash" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkHash =
element metalink:hash {
attribute type { text }?,
text
}</artwork></figure></t>
<t>Metalink Documents MAY contain one or multiples hashes of a complete file. <xref target="element.hash" format="none">metalink:hash</xref> elements
with a "type" attribute MUST contain a hash of the complete file. In this example, both SHA-1 and SHA-256 hashes of the complete file are included.
<figure>
<artwork type="example">
...
<hash type="sha-1">a97fcf6ba9358f8a6f62beee4421863d3e52b080</hash>
<hash type="sha-256">fc87941af7fd7f03e53b34af393f4c14923d74...</hash>
...</artwork>
</figure>
</t>
<t>Metalink Documents MAY also contain hashes for individual pieces of a file. <xref target="element.hash" format="none">metalink:hash</xref> elements that are inside a <xref target="element.pieces" format="none">metalink:pieces</xref> container element have a hash for that specific piece or chunk of the file, and are of the same hash type as the <xref target="element.pieces" format="none">metalink:pieces</xref> element in which they are contained. Metalink Documents MAY contain one or multiple <xref target="element.pieces" format="none">metalink:pieces</xref> container elements, if each "type" attribute of <xref target="element.pieces" format="none">metalink:pieces</xref> has a unique value.</t>
<t><xref target="element.hash" format="none">metalink:hash</xref> elements without a "type" attribute MUST contain a hash for that specific piece or chunk of the file and MUST be listed in the
same order as the corresponding pieces appear in the file, starting at the beginning of the file. The size of the piece is equal to the value of the "length" attribute of the <xref target="element.pieces" format="none">metalink:pieces</xref> element, apart from the last piece, which is the remainder. See <xref target="piece.length"/> for more information on the size of pieces.</t>
<t>In this example, SHA-1 and SHA-256 hashes of the complete file are included, along with four SHA-1 piece hashes.
<figure>
<artwork type="example">
...
<hash type="sha-1">a97fcf6ba9358f8a6f62beee4421863d3e52b080</hash>
<hash type="sha-256">fc87941af7fd7f03e53b34af393f4c14923d74...</hash>
<pieces length="1048576" type="sha-1">
<hash>d96b9a4b92a899c2099b7b31bddb5ca423bb9b30</hash>
<hash>10d68f4b1119014c123da2a0a6baf5c8a6d5ba1e</hash>
<hash>3e84219096435c34e092b17b70a011771c52d87a</hash>
<hash>67183e4c3ab892d3ebe8326b7d79eb62d077f487</hash>
</pieces>
...</artwork>
</figure>
</t>
<section title="The "type" Attribute">
<t><xref target="element.hash" format="none">metalink:hash</xref> elements MUST have a "type" attribute, if and only if
it contains a hash of the complete file. The IANA registry named "Hash Function Textual Names" defines values for hash types. <xref target="element.hash" format="none">metalink:hash</xref> elements MUST NOT have a "type" attribute, if they are inside a <xref target="element.pieces" format="none">metalink:pieces</xref> container element. See <xref target="security.hash"/> for security implications.</t>
</section>
</section>
<section anchor="element.identity" title="The "metalink:identity" Element">
<iref item="XML Elements" subitem="identity" primary="true"/>
<iref item="identity XML element" primary="true"/>
<t>The "<xref target="element.identity" format="none">metalink:identity</xref>" element is a Text construct that conveys a
human-readable identity for a file. For example, the identity of Firefox 3.5 would be "Firefox".
<figure>
<iref item="metalinkIdentity grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkIdentity" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkIdentity =
element metalink:identity {
metalinkTextConstruct
}</artwork></figure></t>
</section>
<section anchor="element.language" title="The "metalink:language" Element">
<iref item="XML Elements" subitem="language" primary="true"/>
<iref item="language XML element" primary="true"/>
<t>The "<xref target="element.language" format="none">metalink:language</xref>" element is a Text construct that conveys a
code for the language of a file, per <xref target="RFC5646"/>.</t>
<t>Multiple <xref target="element.language" format="none">metalink:language</xref> elements are allowed, for instance, to describe a file such as an binary installation program that provides multiple language options, a
movie with multiple language tracks, or a document in multiple languages.
<figure>
<iref item="metalinkLanguage grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkLanguage" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkLanguage =
element metalink:language {
metalinkTextConstruct
}</artwork></figure></t>
</section>
<section anchor="element.logo" title="The "metalink:logo" Element">
<iref item="XML Elements" subitem="logo" primary="true"/>
<iref item="logo XML element" primary="true"/>
<t>The "<xref target="element.logo" format="none">metalink:logo</xref>" element's content is an IRI reference <xref target="RFC3987"/> that identifies an image that provides visual
identification for a file.
<figure>
<iref item="metalinkLogo grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkLogo" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkLogo =
element metalink:logo {
metalinkCommonAttributes,
(metalinkUri)
}</artwork></figure></t>
<t>The image SHOULD have an aspect ratio of one (horizontal)
to one (vertical) and SHOULD be suitable for presentation
at a small size.</t>
</section>
<section anchor="element.metaurl" title="The "metalink:metaurl" Element">
<iref item="XML Elements" subitem="metaurl" primary="true"/>
<iref item="metaurl XML element" primary="true"/>
<t>The "<xref target="element.metaurl" format="none">metalink:metaurl</xref>" element contains the IRI of a metadata file, also known as a metainfo file, about a resource to download. For example, this could be the IRI of a BitTorrent .torrent file, a Metalink Document, or other type of metadata file. Note that
the information in the <xref target="element.hash" format="none">metalink:hash</xref> element does not apply to these metadata files but to the files that are described by them.
<figure>
<iref item="metalinkMetaURL grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkMetaURL" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkMetaURL =
element metalink:metaurl {
metalinkCommonAttributes,
attribute priority { xsd:positiveInteger {
maxInclusive = "999999"}}?,
attribute mediatype { text },
attribute name { text }?,
(metalinkUri)
}</artwork></figure></t>
<section title="The "priority" Attribute">
<t><xref target="element.metaurl" format="none">metalink:metaurl</xref>
elements MAY have a priority attribute. Values MUST be positive integers between 1 and 999999. Lower values indicate a higher priority. <xref target="element.metaurl" format="none">metalink:metaurl</xref>
elements without a priority attribute are considered to have the lowest priority, i.e., 999999. The priority values of <xref target="element.metaurl" format="none">metalink:metaurl</xref> and <xref target="element.url" format="none">metalink:url</xref> elements are compared and those with the lowest values, starting with 1, are used first. Multiple <xref target="element.metaurl" format="none">metalink:metaurl</xref> and <xref target="element.url" format="none">metalink:url</xref> elements MAY have the same
priority, i.e., one BitTorrent .torrent file and three FTP URIs could have priority="1". See also the "priority" attribute of the <xref target="element.url" format="none">metalink:url</xref> element.</t>
</section>
<section title="The "mediatype" Attribute">
<t><xref target="element.metaurl" format="none">metalink:metaurl</xref> elements MUST have a "mediatype" attribute that indicates
the Multipurpose Internet Mail Extensions (MIME) media type <xref target="RFC4288"/> of the metadata file available at the IRI. In the case of BitTorrent as specified in <xref target="BITTORRENT"/>, the value "torrent" is REQUIRED. Types without "/" are reserved. Currently, "torrent" is the only reserved value.</t>
<t>Values for this attribute are defined below in ABNF notation <xref target="RFC5234"/>.
<figure>
<iref item="metaurl mediatype ABNF" primary="true"/>
<iref item="ABNF" subitem="metaurl mediatype" primary="true"/>
<artwork type="ABNF">
media-type = (type-name "/" subtype-name) / media-reserved
media-reserved = "torrent"
type-name = <Defined in Section 4.2 of RFC 4288>
subtype-name = <Defined in Section 4.2 of RFC 4288>
</artwork></figure></t>
</section>
<section title="The "name" Attribute">
<t><xref target="element.metaurl" format="none">metalink:metaurl</xref> elements MAY have a "name" attribute that indicates
a specific file in a BitTorrent .torrent file or a Metalink Document that describes multiple files.</t>
<t>
<figure>
<preamble>Directory information can also be contained in a "path/file" format only, as in:</preamble>
<artwork type="example">
<metaurl
mediatype="torrent" name="debian-amd64/sarge/Contents-amd64.gz">
</artwork></figure></t>
<t>In this example, a file named "Contents-amd64.gz" is indicated, in a "debian-amd64/sarge/" subdirectory.
The path MUST NOT contain any directory traversal directives or
information. The path MUST be relative. The path MUST NOT begin with a "/", "./", or
"../"; contain "/../"; or end with "/..".</t>
</section>
</section>
<section anchor="element.origin" title="The "metalink:origin" Element">
<iref item="XML Elements" subitem="origin" primary="true"/>
<iref item="origin XML element" primary="true"/>
<t>The "<xref target="element.origin" format="none">metalink:origin</xref>" element is an IRI where the Metalink Document was originally published. If the dynamic attribute of <xref target="element.origin" format="none">metalink:origin</xref> is "true", then updated
versions of the Metalink can be found at this IRI.
<figure>
<iref item="metalinkOrigin grammar production" primary="true"/>
<iref item="Grammar" subitem="metalinkOrigin" primary="true"/>
<artwork type="application/relax-ng-compact-syntax">
metalinkOrigin =
element metalink:origin {
metalinkCommonAttributes,
attribute dynamic { xsd:boolean }?,
(metalinkUri)
}</artwork></figure></t>
<section title="The "dynamic" Attribute">
<t>The <xref target="element.origin" format="none">metalink:origin</xref> element MAY have a "dynamic" attribute, set to "true" or "false", which tells if a Metalink at the origin IRI will contain dynamic updated information or if it is static and not likely to be updated.</t>
</section>
</section>
<section anchor="element.os" title="The "metalink:os" Element">
<iref item="XML Elements" subitem="os" primary="true"/>
<iref item="os XML element" primary="true"/>