asciidoctor-rfc 0.1.0 → 0.2.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (130) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +5 -0
  3. data/.oss-guides.rubocop.yml +1077 -0
  4. data/.rspec +1 -0
  5. data/.rubocop.yml +19 -1063
  6. data/.travis.yml +3 -2
  7. data/Guardfile +22 -0
  8. data/README.adoc +1151 -0
  9. data/Rakefile +1 -1
  10. data/asciidoctor-rfc.gemspec +20 -3
  11. data/bin/asciidoctor-rfc2 +15 -0
  12. data/bin/asciidoctor-rfc3 +15 -0
  13. data/bin/rspec +0 -1
  14. data/lib/asciidoctor-rfc.rb +4 -0
  15. data/lib/asciidoctor/rfc/common/base.rb +218 -0
  16. data/lib/asciidoctor/rfc/common/front.rb +120 -0
  17. data/lib/asciidoctor/rfc/v2/base.rb +341 -0
  18. data/lib/asciidoctor/rfc/v2/blocks.rb +192 -0
  19. data/lib/asciidoctor/rfc/v2/converter.rb +64 -0
  20. data/lib/asciidoctor/rfc/v2/front.rb +69 -0
  21. data/lib/asciidoctor/rfc/v2/inline_anchor.rb +102 -0
  22. data/lib/asciidoctor/rfc/v2/lists.rb +134 -0
  23. data/lib/asciidoctor/rfc/v2/table.rb +112 -0
  24. data/lib/asciidoctor/rfc/v2/validate.rb +738 -0
  25. data/lib/asciidoctor/rfc/v2/validate2.rng +716 -0
  26. data/lib/asciidoctor/rfc/v3/base.rb +358 -0
  27. data/lib/asciidoctor/rfc/v3/blocks.rb +203 -0
  28. data/lib/asciidoctor/rfc/v3/converter.rb +64 -0
  29. data/lib/asciidoctor/rfc/v3/front.rb +115 -0
  30. data/lib/asciidoctor/rfc/v3/inline_anchor.rb +90 -0
  31. data/lib/asciidoctor/rfc/v3/lists.rb +190 -0
  32. data/lib/asciidoctor/rfc/v3/svg.rng +9081 -0
  33. data/lib/asciidoctor/rfc/v3/table.rb +65 -0
  34. data/lib/asciidoctor/rfc/v3/validate.rb +2168 -0
  35. data/lib/asciidoctor/rfc/v3/validate.rng +2143 -0
  36. data/lib/asciidoctor/rfc/version.rb +2 -2
  37. data/spec/asciidoctor/rfc/v2/appendix_spec.rb +124 -0
  38. data/spec/asciidoctor/rfc/v2/area_spec.rb +60 -0
  39. data/spec/asciidoctor/rfc/v2/author_spec.rb +444 -0
  40. data/spec/asciidoctor/rfc/v2/comments_spec.rb +316 -0
  41. data/spec/asciidoctor/rfc/v2/crossref_spec.rb +205 -0
  42. data/spec/asciidoctor/rfc/v2/date_spec.rb +166 -0
  43. data/spec/asciidoctor/rfc/v2/dlist_spec.rb +108 -0
  44. data/spec/asciidoctor/rfc/v2/document_spec.rb +161 -0
  45. data/spec/asciidoctor/rfc/v2/example_spec.rb +50 -0
  46. data/spec/asciidoctor/rfc/v2/front_spec.rb +75 -0
  47. data/spec/asciidoctor/rfc/v2/image_spec.rb +81 -0
  48. data/spec/asciidoctor/rfc/v2/indexterm_spec.rb +66 -0
  49. data/spec/asciidoctor/rfc/v2/inline_formatting_spec.rb +177 -0
  50. data/spec/asciidoctor/rfc/v2/keyword_spec.rb +63 -0
  51. data/spec/asciidoctor/rfc/v2/listing_spec.rb +59 -0
  52. data/spec/asciidoctor/rfc/v2/literal_spec.rb +53 -0
  53. data/spec/asciidoctor/rfc/v2/olist_spec.rb +147 -0
  54. data/spec/asciidoctor/rfc/v2/paragraph_spec.rb +68 -0
  55. data/spec/asciidoctor/rfc/v2/preamble_spec.rb +140 -0
  56. data/spec/asciidoctor/rfc/v2/quote_spec.rb +24 -0
  57. data/spec/asciidoctor/rfc/v2/references_spec.rb +96 -0
  58. data/spec/asciidoctor/rfc/v2/section_spec.rb +260 -0
  59. data/spec/asciidoctor/rfc/v2/sidebar_spec.rb +32 -0
  60. data/spec/asciidoctor/rfc/v2/table_spec.rb +293 -0
  61. data/spec/asciidoctor/rfc/v2/ulist_spec.rb +96 -0
  62. data/spec/asciidoctor/rfc/v2/workgroup_spec.rb +60 -0
  63. data/spec/asciidoctor/rfc/v3/appendix_spec.rb +130 -0
  64. data/spec/asciidoctor/rfc/v3/area_spec.rb +63 -0
  65. data/spec/asciidoctor/rfc/v3/author_spec.rb +540 -0
  66. data/spec/asciidoctor/rfc/v3/comments_spec.rb +308 -0
  67. data/spec/asciidoctor/rfc/v3/crossref_spec.rb +269 -0
  68. data/spec/asciidoctor/rfc/v3/date_spec.rb +149 -0
  69. data/spec/asciidoctor/rfc/v3/dlist_spec.rb +121 -0
  70. data/spec/asciidoctor/rfc/v3/document_spec.rb +109 -0
  71. data/spec/asciidoctor/rfc/v3/example_spec.rb +34 -0
  72. data/spec/asciidoctor/rfc/v3/front_spec.rb +43 -0
  73. data/spec/asciidoctor/rfc/v3/image_spec.rb +81 -0
  74. data/spec/asciidoctor/rfc/v3/indexterm_spec.rb +69 -0
  75. data/spec/asciidoctor/rfc/v3/inline_formatting_spec.rb +319 -0
  76. data/spec/asciidoctor/rfc/v3/keyword_spec.rb +33 -0
  77. data/spec/asciidoctor/rfc/v3/link_spec.rb +34 -0
  78. data/spec/asciidoctor/rfc/v3/listing_spec.rb +59 -0
  79. data/spec/asciidoctor/rfc/v3/literal_spec.rb +51 -0
  80. data/spec/asciidoctor/rfc/v3/olist_spec.rb +168 -0
  81. data/spec/asciidoctor/rfc/v3/paragraph_spec.rb +73 -0
  82. data/spec/asciidoctor/rfc/v3/preamble_spec.rb +112 -0
  83. data/spec/asciidoctor/rfc/v3/quote_spec.rb +91 -0
  84. data/spec/asciidoctor/rfc/v3/references_spec.rb +147 -0
  85. data/spec/asciidoctor/rfc/v3/section_spec.rb +198 -0
  86. data/spec/asciidoctor/rfc/v3/series_info_spec.rb +151 -0
  87. data/spec/asciidoctor/rfc/v3/sidebar_spec.rb +30 -0
  88. data/spec/asciidoctor/rfc/v3/table_spec.rb +275 -0
  89. data/spec/asciidoctor/rfc/v3/ulist_spec.rb +74 -0
  90. data/spec/asciidoctor/rfc/v3/workgroup_spec.rb +33 -0
  91. data/spec/examples/davies-template-bare-06.adoc +361 -0
  92. data/spec/examples/davies-template-bare-06.xml.orig +426 -0
  93. data/spec/examples/example-v2.adoc +181 -0
  94. data/spec/examples/example-v2.xml +675 -0
  95. data/spec/examples/example-v3.adoc +185 -0
  96. data/spec/examples/example-v3.xml +1009 -0
  97. data/spec/examples/mib-doc-template-xml-06.adoc +596 -0
  98. data/spec/examples/mib-doc-template-xml-06.xml.orig +654 -0
  99. data/spec/examples/rfc1149.md +76 -0
  100. data/spec/examples/rfc1149.md.2.xml +94 -0
  101. data/spec/examples/rfc1149.md.3.xml +93 -0
  102. data/spec/examples/rfc1149.md.adoc +65 -0
  103. data/spec/examples/rfc2100.md +149 -0
  104. data/spec/examples/rfc2100.md.2.xml +169 -0
  105. data/spec/examples/rfc2100.md.3.xml +163 -0
  106. data/spec/examples/rfc2100.md.adoc +136 -0
  107. data/spec/examples/rfc3514.md +203 -0
  108. data/spec/examples/rfc3514.md.2.xml +238 -0
  109. data/spec/examples/rfc3514.md.3.xml +258 -0
  110. data/spec/examples/rfc3514.md.adoc +324 -0
  111. data/spec/examples/rfc5841.md +342 -0
  112. data/spec/examples/rfc5841.md.2.xml +393 -0
  113. data/spec/examples/rfc5841.md.3.xml +449 -0
  114. data/spec/examples/rfc5841.md.adoc +414 -0
  115. data/spec/examples/rfc6350.adoc +3499 -0
  116. data/spec/examples/rfc6350.bib +763 -0
  117. data/spec/examples/rfc748.md +79 -0
  118. data/spec/examples/rfc748.md.2.xml +116 -0
  119. data/spec/examples/rfc748.md.3.xml +109 -0
  120. data/spec/examples/rfc748.md.adoc +80 -0
  121. data/spec/examples/rfc7511.md +257 -0
  122. data/spec/examples/rfc7511.md.2.xml +300 -0
  123. data/spec/examples/rfc7511.md.3.xml +347 -0
  124. data/spec/examples/rfc7511.md.adoc +417 -0
  125. data/spec/spec_helper.rb +115 -5
  126. metadata +274 -9
  127. data/.hound.yml +0 -3
  128. data/README.md +0 -84
  129. data/lib/asciidoctor/rfc.rb +0 -7
  130. data/spec/asciidoctor-rfc/.keep +0 -0
@@ -0,0 +1,654 @@
1
+ <?txt version="1.0" encoding="US-ASCII"?>
2
+ <!-- change the "txt" on the previous line to "xml" to make this a valid XML2RFC template -->
3
+ <!-- this is version 5 of this xml2rfc template -->
4
+ <!--
5
+ DOCTYPE processing
6
+
7
+ To use this XML template, the rfc2629.dtd from the xml2rfc distribution should
8
+ be in the local directory. The xml2rfc distribution is available from
9
+ http://xml.resource.org/
10
+
11
+ The ENTITY clauses create an include of the named XML files, which
12
+ contains references written in xml2rfc format.
13
+
14
+ XML2RFC offers an include feature described in the XML2RFC README
15
+ file. That syntax, however, contradicts the DTD requirements to
16
+ have <reference> elements within the <references> element, so an
17
+ XML parser is likely to find your XML file invalid. It may be
18
+ possible that XML2RFC will change their DTD so that the XML file
19
+ remains valid when their style of include is used.
20
+
21
+ Some editors, such as XXE, resolve the ENTITY clauses before displaying the
22
+ document to be edited.
23
+ -->
24
+ <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
25
+ <!ENTITY rfc2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
26
+ <!ENTITY rfc2223 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2223.xml">
27
+ <!ENTITY rfc2578 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2578.xml">
28
+ <!ENTITY rfc2579 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2579.xml">
29
+ <!ENTITY rfc2580 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2580.xml">
30
+ <!ENTITY rfc2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
31
+ <!ENTITY rfc3410 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3410.xml">
32
+ <!ENTITY rfc4181 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4181.xml">
33
+ ]>
34
+ <?rfc toc="yes"?>
35
+ <?rfc symrefs="yes"?>
36
+ <?rfc compact="yes"?>
37
+ <?rfc subcompact="no"?>
38
+ <?rfc strict="no"?>
39
+ <?rfc rfcedstyle="yes"?>
40
+ <?rfc comments="yes"?>
41
+ <?rfc inline="yes"?>
42
+
43
+ <!-- Document section
44
+
45
+ Specify the category attribute per RFC2026
46
+ options are info, std, bcp, or exp.
47
+
48
+ docname is the name of the output document. This is optional;
49
+ the default is to use the base portion of the XML filename.
50
+
51
+ For Internet-drafts, indicate which intellectual property notice
52
+ to use per the rules of RFC3978. The value (as of this template) can be:
53
+ trust200902 -
54
+ noModificationTrust200902 -
55
+ noDerivativesTrust200902 -
56
+ pre5378Trust200902 -
57
+
58
+ The Intellectual Property section will be generated automatically by
59
+ XML2RFC, based on the ipr attribute in the rfc element.
60
+
61
+ If this document obsoletes an RFC, specify the RFC in the "obsoletes" attribute
62
+ If this document updates an RFC, specify the RFC in the "updates" attribute
63
+ -->
64
+ <rfc category="historic" docName="Your MIB Document name here rev07" ipr="trust200902">
65
+ <front>
66
+ <!--
67
+ Enter the full document title and an abbreviated version
68
+ to use in the page header.
69
+ -->
70
+
71
+ <title abbrev="Your MIB Module document name">Your MIB module document name</title>
72
+
73
+ <!-- copy the author block as many times as needed, one for each author.-->
74
+
75
+ <!-- If the author is acting as editor, use the <role=editor> attribute-->
76
+
77
+ <!-- see RFC2223 for guidelines regarding author names -->
78
+
79
+ <author fullname="Editor name" initials="Y" role="editor"
80
+ surname="Name">
81
+ <organization>Editor affiliation</organization>
82
+
83
+ <address>
84
+ <postal>
85
+ <street>Editor affiliation address</street>
86
+
87
+ <city>Editor affiliation address</city>
88
+
89
+ <country>Editor affiliation address</country>
90
+ </postal>
91
+
92
+ <phone>Editor address</phone>
93
+
94
+ <email>Editor email</email>
95
+ </address>
96
+ </author>
97
+
98
+ <!-- month and day will be generated automatically by XML2RFC;
99
+ be sure the year is current.-->
100
+
101
+ <date year="2008" month="January" day="1" />
102
+
103
+ <!-- IETF area is optional -->
104
+
105
+ <area>Operations &amp; Management Area</area>
106
+
107
+ <!--WG name at the upperleft corner of the doc,
108
+ IETF is fine for non-WG IETF submissions -->
109
+
110
+ <workgroup>Internet Engineering Task Force</workgroup>
111
+
112
+ <keyword>Network Management</keyword>
113
+
114
+ <keyword>Management Information Base</keyword>
115
+
116
+ <keyword>MIB</keyword>
117
+
118
+ <keyword>SMIv2</keyword>
119
+
120
+ <!--add additional keywords here for IETF website search engine -->
121
+ <abstract>
122
+
123
+ <t> <cref>This template is for authors of IETF specifications containing MIB
124
+ modules. This template can be used as a starting point to produce
125
+ specifications that comply with the Operations &amp; Management Area
126
+ guidelines for MIB module internet drafts. Throughout the template, the marker "[TEMPLATE TODO]" is used as a placeholder to indicate an
127
+ element or text that requires replacement or removal. All the places with [TEMPLATE TODO] markers
128
+ should be replaced or removed before the document is submitted.</cref></t>
129
+
130
+ <t>This memo defines a portion of the Management Information Base (MIB)
131
+ for use with network management protocols. In particular it defines
132
+ objects for managing [TEMPLATE TODO].</t>
133
+
134
+
135
+ <t><cref>[TEMPLATE TODO]: describe what functionality will be managed using this MIB
136
+ module. It can be good to mention the protocol being managed, and
137
+ whether there is a particular aspect of the protocol to be managed, or a
138
+ particular goal of the module. But keep it brief. Remember, don't put any citations
139
+ in the abstract, and expand your acronyms. </cref></t>
140
+
141
+
142
+ </abstract>
143
+
144
+ <note title="Foreword to template users">
145
+ <t>This template is intended to help authors write the surrounding text needed in a
146
+ MIB module internet draft, but does not provide a template for writing
147
+ the MIB module itself.</t>
148
+
149
+ <t>Throughout this template, the marker "[TEMPLATE TODO]" is used as a reminder
150
+ to the template user to indicate an element or text that requires
151
+ replacement or removal by the template user before submission to the
152
+ internet draft editor. All [TEMPLATE TODO] markers should be resolved and removed
153
+ before you submit your document to the internet-draft editor.</t>
154
+
155
+ <t>For updated information on MIB module guidelines and templates, see
156
+ <xref target="RFC4181"></xref> and the OPS Area web page and wiki.</t>
157
+
158
+ <t>For information on writing internet drafts or RFCs, see
159
+ http://www.ietf.org/ietf/1id-guidelines.txt and
160
+ RFC2223(bis) <xref target="RFC2223"></xref>, and look
161
+ at http://www.ietf.org/ID-Checklist.html for issues to note when writing
162
+ drafts.</t>
163
+
164
+ <t>This template is not meant to be a complete list of everything
165
+ needed to write MIB module internet drafts, but to summarize the often-needed
166
+ basic features to get a document containing a MIB module started. An
167
+ important purpose of the template is to aid authors in developing an
168
+ internet draft that is laid out in a manner consistent with other internet
169
+ drafts containing MIB modules. Internet drafts submitted for advancement
170
+ to the standards track typically require review by a MIB Doctor. This
171
+ template standardizes the layout and naming of sections, includes the
172
+ appropriate boilerplate text, and facilitates the development of tools
173
+ to automate the checking of MIB module internet drafts, to speed the WG
174
+ and IESG review processes.</t>
175
+
176
+ <t>An XML2RFC template is also available. For information on XML2RFC, see
177
+ RFC2629 <xref target="RFC2629"></xref>, and documentation available at
178
+ http://xml.resource.org. The XML2RFC version includes
179
+ advice describing how to fill in each section of the template. XML2RFC generates the
180
+ actual internet-draft from your information, and automatically handles getting up-to-date
181
+ boilerplates, references, and it handles many idnits issues.</t>
182
+
183
+ <t>Within the template, there is reference to a SAMPLE-MIB; all references
184
+ to SAMPLE-MIB should be removed from your internet draft, and should be
185
+ replaced by references to your MIB module, as appropriate.</t>
186
+
187
+ <t>[TEMPLATE TODO] THIS section, the complete section entitled "Note: Foreword to
188
+ template users" should be removed by the template user from their
189
+ document before submission.</t>
190
+
191
+ <t>[TEMPLATE TODO] Remove all page headings from the template document, and
192
+ replace them with the appropriate headings for your internet draft.</t>
193
+ </note>
194
+
195
+ <note title="Note to RFC Editor re: [TEMPLATE TODO] markers">
196
+ <t>Note to RFC Editor: When a document is developed using this template, the editor of the
197
+ document should replace or remove all the places marked [TEMPLATE TODO] before submitting the document.
198
+ If there are still [TEMPLATE TODO] markers, please send the document back to the editor.</t>
199
+ </note>
200
+
201
+ </front>
202
+
203
+ <middle>
204
+ <section title="Introduction">
205
+ <!--You can echo the abstract in the Introduction, providing citations here,
206
+ but you should provide more than just the abstract. -->
207
+
208
+ <t>This memo defines a portion of the Management Information Base (MIB)
209
+ for use with network management protocols. In particular it defines
210
+ objects for managing the [TEMPLATE TODO].</t>
211
+
212
+ <t><cref>[TEMPLATE TODO]: describe what functionality will be managed using this MIB
213
+ module. Include citations for protocol specifications, architectures, related MIB modules, and protocol-specific
214
+ management requirements. Provide an overview of why a MIB module is appropriate for this protocol, whether there is a
215
+ particular aspect of the protocol to be managed, and how the module is expected to be used to
216
+ achieve particular goals. Highlight anything 'different' about the module. For example,
217
+ a read-only MIB module.</cref></t>
218
+
219
+ </section>
220
+
221
+ <section title="The Internet-Standard Management Framework">
222
+ <t><cref>The title and text for this section has been copied from the
223
+ official boilerplate, and should not be modified unless the official boilerplate text
224
+ from the OPS Area web site has changed. See RFC4818
225
+ section 3.1 for a discussion of the boilerplate section.</cref></t>
226
+
227
+ <t>For a detailed overview of the documents that describe the current
228
+ Internet-Standard Management Framework, please refer to section 7 of RFC
229
+ 3410 <xref target="RFC3410"></xref>.</t>
230
+
231
+ <t>Managed objects are accessed via a virtual information store, termed
232
+ the Management Information Base or MIB. MIB objects are generally
233
+ accessed through the Simple Network Management Protocol (SNMP). Objects
234
+ in the MIB are defined using the mechanisms defined in the Structure of
235
+ Management Information (SMI). This memo specifies a MIB module that is
236
+ compliant to the SMIv2, which is described in STD 58, RFC 2578 <xref
237
+ target="RFC2578"></xref>, STD 58, RFC 2579 <xref
238
+ target="RFC2579"></xref> and STD 58, RFC 2580 <xref
239
+ target="RFC2580"></xref>.</t>
240
+ </section>
241
+
242
+ <section title="Conventions">
243
+ <t><cref>[TEMPLATE TODO] This boilerplate should be used if the RFC2119 key words
244
+ are used in the internet draft. The text in this section has been
245
+ copied from the official boilerplate, and should not be modified. </cref></t>
246
+
247
+ <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
248
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
249
+ document are to be interpreted as described in BCP 14, RFC 2119 <xref
250
+ target="RFC2119"></xref>.</t>
251
+
252
+ </section>
253
+
254
+ <!-- ********************************************* -->
255
+
256
+ <section title="Overview">
257
+
258
+ <t><cref>[TEMPLATE TODO] The narrative part should include an overview section that
259
+ describes the scope and field of application of the MIB modules
260
+ defined by the specification. See RFC4181 section 3.2 for a
261
+ discussion of the Narrative section.
262
+ </cref></t>
263
+
264
+ <t></t>
265
+
266
+ </section>
267
+
268
+
269
+ <section title="Structure of the MIB Module">
270
+
271
+ <t><cref>[TEMPLATE TODO] The narrative part SHOULD include one or more sections to
272
+ briefly describe the structure of the MIB modules defined in the
273
+ specification.</cref></t>
274
+
275
+
276
+ <section title="Textual Conventions">
277
+
278
+ <t><cref>[TEMPLATE TODO] describe the textual conventions defined in the MIB
279
+ module, and their purpose. It may be helpful to highlight any textual conventions
280
+ imported from partner documents. Generic and Common Textual Conventions can be found summarized at
281
+ the OPS Area web site. If there are no textual conventions used in your MIB module,
282
+ this section should be removed.</cref></t>
283
+
284
+ <t></t>
285
+ </section>
286
+
287
+ <section title="The [TEMPLATE TODO] Subtree">
288
+
289
+ <t><cref>[TEMPLATE TODO] copy this section for each subtree in the MIB module, and
290
+ describe the purpose of the subtree. For example, "The fooStats subtree
291
+ provides information for identifying fault conditions and performance
292
+ degradation of the foo functionality."</cref></t>
293
+
294
+ </section>
295
+
296
+ <section title="The Notifications Subtree">
297
+
298
+ <t><cref>[TEMPLATE TODO] describe the notifications defined in the MIB module, and
299
+ their purpose. Include a discussion of congestion control. You might
300
+ want to discuss throttling as well. See RFC2914.</cref></t>
301
+
302
+ </section>
303
+
304
+ <section title="The Table Structures">
305
+
306
+ <t><cref>[TEMPLATE TODO] Describe the tables in the MIB module, their purpose, and their
307
+ reltionship to each other. If the row in one table is related to a row in
308
+ another table, what happens when one of the rows is deleted? Should the
309
+ related row be deleted as well? Consider both directions.</cref>
310
+ </t>
311
+
312
+ </section>
313
+ </section>
314
+
315
+ <section title="Relationship to Other MIB Modules">
316
+
317
+ <t><cref>[TEMPLATE TODO]: The narrative part should include a section that specifies the
318
+ relationship (if any) of the MIB modules contained in this internet drafts to
319
+ other standards, particularly to standards containing other MIB
320
+ modules. If the MIB modules defined by the specification import
321
+ definitions from other MIB modules or are always implemented in
322
+ conjunction with other MIB modules, then those facts should be noted in
323
+ the narrataive section, as should any special interpretations of objects
324
+ in other MIB modules. Note that citations may NOT be put into the MIB
325
+ module portions of the internet draft, but documents used for Imported items
326
+ are Normative references, so the citations should exist in the narrative
327
+ section of the internet draft. The preferred
328
+ way to fill in a REFERENCE clause in a MIB module is of the form: "Guidelines
329
+ for Writing an IANA Considerations Section in RFCs", RFC2434, section 2.3.</cref></t>
330
+
331
+ <section title="Relationship to the [TEMPLATE TODO] MIB">
332
+
333
+ <t><cref>Example: The Interface MIB [RFC2863] requires that any
334
+ MIB module which is an adjunct of the Interface MIB clarify specific
335
+ areas within the Interface MIB. These areas were intentionally left
336
+ vague in the Interface MIB to avoid over-constraining the MIB, thereby
337
+ precluding management of certain media-types. Section 4 of [RFC2863] enumerates several
338
+ areas which a media-specific MIB must clarify. The implementor is
339
+ referred to [RFC2863] in order to understand the
340
+ general intent of these areas.</cref></t>
341
+
342
+ </section>
343
+
344
+ <section title="MIB modules required for IMPORTS">
345
+
346
+ <t><cref>[TEMPLATE TODO]: Citations are not permitted within a MIB module, but any
347
+ module mentioned in an IMPORTS clause or document mentioned in a
348
+ REFERENCE clause is a Normative reference, and must be cited someplace
349
+ within the narrative sections. If there are imported items in the MIB
350
+ module, such as Textual Conventions, that are not already cited, they
351
+ can be cited in text here. Since relationships to other MIB modules
352
+ should be described in the narrative text, this section is typically
353
+ used to cite modules from which Textual Conventions are imported. Example: "The following MIB module IMPORTS objects from SNMPv2-SMI [RFC2578],
354
+ SNMPv2-TC [RFC2579],
355
+ SNMPv2-CONF [RFC2580], and IF-MIB [RFC2863]."</cref></t>
356
+
357
+ </section>
358
+ </section>
359
+
360
+ <section title="Definitions">
361
+ <t><cref>This section contains the actual MIB module(s).
362
+ These MIB modules MUST be written in SMIv2 [RFC2578] [RFC2579]
363
+ [RFC2580]. See Section 4 of RFC 4181 for guidelines on SMIv2 usage.
364
+ See Appendix C of RFC 4181 for suggested naming conventions.</cref></t>
365
+
366
+ <figure>
367
+ <artwork><![CDATA[
368
+ [TEMPLATE TODO]: put your valid MIB module here.
369
+ A list of tools that can help automate the process of
370
+ checking MIB definitions can be found at the OPS
371
+ Area web site.]]></artwork>
372
+ </figure>
373
+ </section>
374
+
375
+ <section title="Security Considerations">
376
+
377
+ <t><cref>[TEMPLATE TODO] Each internet draft that defines one or more MIB modules MUST
378
+ contain a section that discusses security considerations relevant to
379
+ those modules. This section MUST be patterned after the latest approved
380
+ template (available at the OPS Area web site).
381
+ </cref></t>
382
+
383
+ <t><cref>[TEMPLATE TODO] if you have any read-write and/or read-create objects, please
384
+ describe their specific sensitivity or vulnerability. RFC 2669 has a very good example.
385
+ </cref></t>
386
+
387
+
388
+ <t>There are a number of management objects defined in this MIB module
389
+ with a MAX-ACCESS clause of read-write and/or read-create. Such objects
390
+ may be considered sensitive or vulnerable in some network environments.
391
+ The support for SET operations in a non-secure environment without
392
+ proper protection can have a negative effect on network operations.
393
+ These are the tables and objects and their
394
+ sensitivity/vulnerability:</t>
395
+
396
+ <t><list style="symbols">
397
+ <t></t>
398
+
399
+ <!--
400
+ <t><cref>[TEMPLATE TODO] writeable tables and managed objects that could be especially disruptive
401
+ if abused and the associated security risks should be spelled out.</cref></t>
402
+ -->
403
+ </list></t>
404
+
405
+ <t><cref>[TEMPLATE TODO] else if there are no read-write or read-create objects in your MIB module,
406
+ use the following boilerplate paragraph.</cref></t>
407
+
408
+ <t>There are no management objects defined in this MIB module that have
409
+ a MAX-ACCESS clause of read-write and/or read-create. So, if this MIB
410
+ module is implemented correctly, then there is no risk that an intruder
411
+ can alter or create any management objects of this MIB module via direct
412
+ SNMP SET operations.</t>
413
+
414
+ <t><cref>For all MIB modules you must evaluate whether any readable objects
415
+ are sensitive or vulnerable (for instance, if they might reveal customer
416
+ information or violate personal privacy laws such as those of the
417
+ European Union if exposed to unathorized parties).</cref></t>
418
+
419
+ <t>Some of the readable objects in this MIB module (i.e., objects with a
420
+ MAX-ACCESS other than not-accessible) may be considered sensitive or
421
+ vulnerable in some network environments. It is thus important to control
422
+ even GET and/or NOTIFY access to these objects and possibly to even
423
+ encrypt the values of these objects when sending them over the network
424
+ via SNMP. These are the tables and objects and their
425
+ sensitivity/vulnerability: <list style="symbols">
426
+ <t></t>
427
+
428
+ <t><cref>[TEMPLATE TODO] you should explicitly list by name any readable objects that
429
+ are sensitive or vulnerable and the associated security risks should
430
+ be spelled out.</cref></t>
431
+
432
+ </list></t>
433
+
434
+ <t><cref>[TEMPLATE TODO] The following three boilerplate paragraphs
435
+ should not be changed without very good reason. Changes will almost
436
+ certainly require justification during IESG review.</cref></t>
437
+
438
+ <t>SNMP versions prior to SNMPv3 did not include adequate security.
439
+ Even if the network itself is secure (for example by using IPsec),
440
+ there is no control as to who on the secure network is
441
+ allowed to access and GET/SET (read/change/create/delete) the objects
442
+ in this MIB module.</t>
443
+
444
+ <t> Implementations SHOULD provide the security features described by the
445
+ SNMPv3 framework (see [RFC3410]), and implementations claiming compliance
446
+ to the SNMPv3 standard MUST include full support for authentication and
447
+ privacy via the User-based Security Model (USM) [RFC3414] with the AES
448
+ cipher algorithm [RFC3826]. Implementations MAY also provide support for
449
+ the Transport Security Model (TSM) [RFC5591] in combination with a secure
450
+ transport such as SSH [RFC5592] or TLS/DTLS [RFC6353]. </t>
451
+
452
+ <t>Further, deployment of SNMP versions prior to SNMPv3 is NOT
453
+ RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to enable
454
+ cryptographic security. It is then a customer/operator responsibility to
455
+ ensure that the SNMP entity giving access to an instance of this MIB
456
+ module is properly configured to give access to the objects only to
457
+ those principals (users) that have legitimate rights to indeed GET or
458
+ SET (change/create/delete) them.</t>
459
+ </section>
460
+
461
+ <section title="IANA Considerations">
462
+
463
+ <t><cref>[TEMPLATE TODO] In order to comply with IESG policy as set forth in
464
+ http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is
465
+ submitted to the IESG for publication MUST contain an IANA
466
+ Considerations section. The requirements for this section vary depending
467
+ what actions are required of the IANA. See "Guidelines for Writing an IANA
468
+ Considerations Section in RFCs" [RFC2434]. and see RFC4181 section 3.5 for more
469
+ information on writing an IANA clause for a MIB module internet draft.</cref></t>
470
+
471
+ <t>Option #1:</t>
472
+
473
+ <figure>
474
+ <preamble></preamble>
475
+
476
+ <artwork><![CDATA[
477
+ The MIB module in this document uses the following IANA-assigned
478
+ OBJECT IDENTIFIER values recorded in the SMI Numbers registry:
479
+
480
+ Descriptor OBJECT IDENTIFIER value
481
+ ---------- -----------------------
482
+ sampleMIB { mib-2 XXX }
483
+ ]]></artwork>
484
+
485
+ <postamble></postamble>
486
+ </figure>
487
+
488
+ <t></t>
489
+
490
+ <t>Option #2:</t>
491
+
492
+ <t>Editor's Note (to be removed prior to publication): the IANA is
493
+ requested to assign a value for "XXX" under the 'mib-2' subtree and to
494
+ record the assignment in the SMI Numbers registry. When the assignment
495
+ has been made, the RFC Editor is asked to replace "XXX" (here and in the
496
+ MIB module) with the assigned value and to remove this note.</t>
497
+
498
+ <t>Note well: prior to official assignment by the IANA, an internet
499
+ draft MUST use placeholders (such as "XXX" above) rather than actual
500
+ numbers. See RFC4181 Section 4.5 for an example of how this is done in
501
+ an internet draft MIB module.</t>
502
+
503
+ <t>Option #3:</t>
504
+
505
+ <t>This memo includes no request to IANA.</t>
506
+ </section>
507
+
508
+ <!-- The Author's Addresses section will be generated automatically by XML2RFC
509
+ from the front information. -->
510
+
511
+ <section title="Contributors">
512
+ <!--
513
+
514
+ <t><cref>[TEMPLATE TODO] This optional section can be used to mention contributors to your internet draft.</cref></t>
515
+ -->
516
+ </section>
517
+ </middle>
518
+
519
+ <back>
520
+
521
+ <!-- References Section -->
522
+
523
+ <!-- Section 4.7f of [RFC2223bis] specifies the requirements for the
524
+ references sections. In particular, there MUST be separate lists of
525
+ normative and informative references, each in a separate section.
526
+ The style SHOULD follow that of recently published RFCs.
527
+
528
+ The standard MIB boilerplate available at
529
+ the OPS Area web site includes lists of
530
+ normative and informative references that MUST appear in all IETF
531
+ specifications that contain MIB modules. If items from other MIB
532
+ modules appear in an IMPORTS statement in the Definitions section,
533
+ then the specifications containing those MIB modules MUST be included
534
+ in the list of normative references. When items are imported from an
535
+ IANA-maintained MIB module the corresponding normative reference
536
+ SHALL reference the on-line version of that MIB module. It is the
537
+ policy of the RFC Editor that all references must be cited in the
538
+ text; such citations MUST appear in the overview section where
539
+ documents containing imported definitions (other than those already
540
+ mentioned in the MIB boilerplate) are required to be mentioned (cf.
541
+ Section 3.2).
542
+
543
+ In general, each normative reference SHOULD reference the most recent
544
+ version of the specification in question.
545
+ -->
546
+
547
+ <references title="Normative References">
548
+ <!-- [TEMPLATE TODO] rfc2119, 2578, 2579, and 2580 are required to support MIB
549
+ module boilerplate text. -->
550
+
551
+ &rfc2119;
552
+
553
+ &rfc2578;
554
+
555
+ &rfc2579;
556
+
557
+ &rfc2580;
558
+
559
+ </references>
560
+
561
+ <references title="Informative References">
562
+
563
+ <!-- RFC3410 is required to support the boilerplate text.-->
564
+ &rfc2223;
565
+ &rfc3410;
566
+
567
+ &rfc2629;
568
+
569
+ &rfc4181;
570
+
571
+ </references>
572
+
573
+ <references title="URL References">
574
+ <reference anchor="idguidelines">
575
+ <front>
576
+ <title>http://www.ietf.org/ietf/1id-guidelines.txt</title>
577
+ <author>
578
+ <organization>IETF Internet Drafts editor</organization>
579
+ </author>
580
+ <date year=""></date>
581
+ </front>
582
+ </reference>
583
+ <reference anchor="idnits">
584
+ <front>
585
+ <title>http://www.ietf.org/ID-Checklist.html</title>
586
+ <author>
587
+ <organization>IETF Internet Drafts editor</organization>
588
+ </author>
589
+ <date year=""></date>
590
+ </front>
591
+ </reference>
592
+ <reference anchor="xml2rfc">
593
+ <front>
594
+ <title>http://xml.resource.org</title>
595
+ <author>
596
+ <organization>XML2RFC tools and documentation</organization>
597
+ </author>
598
+ <date year=""></date>
599
+ </front>
600
+ </reference>
601
+ <reference anchor="ops">
602
+ <front>
603
+ <title>http://www.ops.ietf.org</title>
604
+ <author>
605
+ <organization>the IETF OPS Area</organization>
606
+ </author>
607
+ <date year=""></date>
608
+ </front>
609
+ </reference>
610
+ <reference anchor="ietf">
611
+ <front>
612
+ <title>http://tools.ietf.org</title>
613
+ <author>
614
+ <organization>IETF Tools Team</organization>
615
+ </author>
616
+ <date year=""></date>
617
+ </front>
618
+ </reference>
619
+
620
+ </references>
621
+ <!--
622
+ <section anchor="appendix" title="Appendix A">
623
+ <t>You can add appendices just as regular sections, the only
624
+ difference is that they go under "back" element, and get letters
625
+ instead of numbers</t>
626
+ </section>
627
+ -->
628
+
629
+ <section title="Change Log ">
630
+ <t>Note to RFC Editor: if this document does not obsolete an existing RFC,
631
+ please remove this appendix before publication as an RFC.</t>
632
+ <!--
633
+ from draft 12 to draft 13
634
+ <t><list style="numbers">
635
+ <t></t>
636
+ </list></t>
637
+ -->
638
+ </section>
639
+
640
+ <section title="Open Issues">
641
+ <t>Note to RFC Editor: please remove this appendix before publication as an RFC.</t>
642
+ <!--
643
+ <t><list style="numbers">
644
+ <t>Contributor addresses need to be updated</t>
645
+ </list></t>
646
+ -->
647
+ </section>
648
+
649
+ <!--
650
+ $Id: mib-doc-template.xml,v 1.5 2008/04/08 17:39:56 H73653 Exp $
651
+
652
+ -->
653
+ </back>
654
+ </rfc>