Guidelines for Authors and Reviewers of MIB Documents
RFC 4181 устанавливает рекомендации для авторов и рецензентов спецификаций IETF на пути стандартизации, содержащих модули MIB. Он охватывает структуру документа, требования к разделам безопасности, IANA и ссылок, а также правила использования SMIv2, типов данных, таблиц, уведомлений, утверждений о соответствии и пересмотра модулей. Документ содержит контрольный перечень для рецензирования и рекомендуемые соглашения об именовании и структуре OID. Применимые части могут служить основой для рецензирования других документов MIB.
Рабочая группа по сетевым вопросам C. Heard, ред.
Запрос комментариев: 4181 Сентябрь 2005
BCP: 111
Категория: Лучшая современная практика
Руководство для авторов и рецензентов MIB-документов
Статус настоящего меморандума
Этот документ устанавливает Лучшую современную практику Интернета для
интернет-сообщества и запрашивает обсуждение и предложения по
улучшениям. Распространение настоящего меморандума не ограничено.
Уведомление об авторских правах
Авторское право (C) The Internet Society (2005).
Аннотация
Этот меморандум содержит рекомендации для авторов и рецензентов
спецификаций IETF на пути стандартизации, содержащих MIB-модули.
Применимые части могут использоваться в качестве основы для
рецензирования других MIB-документов.
Содержание
1. Введение .......................................................3
2. Терминология ...................................................3
3. Общие рекомендации по документированию .........................4
3.1. Раздел стандартного текста MIB ............................4
3.2. Повествовательные разделы ................................5
3.3. Раздел определений .......................................5
3.4. Раздел «Соображения безопасности» ........................5
3.5. Раздел «Соображения IANA» ................................6
3.5.1. Документы, создающие новое пространство имён ......6
3.5.2. Документы, требующие назначений в
существующих пространствах имён ...................7
3.5.3. Документы без запросов к IANA .....................8
3.6. Разделы ссылок ...........................................8
3.7. Уведомления об авторских правах ..........................9
3.8. Раздел интеллектуальной собственности ...................10
4. Рекомендации по использованию SMIv2 ...........................10
4.1. Имена модулей ...........................................10
4.2. Дескрипторы, имена TC и метки ............................10
4.3. Иерархия именования .....................................11
4.4. Оператор IMPORTS ........................................11
4.5. Вызов MODULE-IDENTITY ...................................12
4.6. Текстовые соглашения и определения объектов .............14
Heard Лучшая современная практика [Страница 1]
RFC 4181 Руководство для MIB-документов Сентябрь 2005
4.6.1. Использование типов данных .......................14
4.6.1.1. INTEGER, Integer32, Gauge32 и
Unsigned32 ...............................14
4.6.1.2. Counter32 и Counter64 ...................16
4.6.1.3. CounterBasedGauge64 .....................17
4.6.1.4. OCTET STRING ............................17
4.6.1.5. OBJECT IDENTIFIER .......................18
4.6.1.6. Конструкция BITS ........................19
4.6.1.7. IpAddress ...............................19
4.6.1.8. TimeTicks ...............................19
4.6.1.9. TruthValue ..............................19
4.6.1.10. Другие типы данных .....................19
4.6.2. Клаузы DESCRIPTION и REFERENCE ...................20
4.6.3. Клауза DISPLAY-HINT ..............................21
4.6.4. Определения концептуальных таблиц ................21
4.6.5. Значения OID, назначенные объектам ...............23
4.6.6. Ограничения длины OID и индексирование таблиц ....24
4.7. Определения уведомлений .................................24
4.8. Операторы соответствия ..................................25
4.8.1. Примечание относительно этих примеров и RFC 2578 .27
4.9. Редакции MIB-модулей ....................................28
5. Благодарности ................................................31
6. Соображения безопасности .....................................32
7. Соображения IANA .............................................32
Приложение A: Контрольный список рецензирования MIB .............33
Приложение B: Часто используемые текстовые соглашения ...........34
Приложение C: Предлагаемые соглашения об именовании .............36
Приложение D: Предлагаемая компоновка OID .......................37
Нормативные ссылки ..............................................38
Информационные ссылки ...........................................40
Heard Лучшая современная практика [Страница 2]
RFC 4181 Руководство для MIB-документов Сентябрь 2005
1. Введение
Некоторое время назад IESG ввела политику, требующую экспертного
рецензирования спецификаций IETF на пути стандартизации, содержащих
MIB-модули. Эти рецензирования были установлены, чтобы обеспечить
следование такими спецификациями сложившейся практике документирования
IETF и соответствие содержащихся в них MIB-модулей определённым
общепринятым стандартам качества, включая (но не ограничиваясь этим)
соблюдение всех синтаксических и семантических требований SMIv2
(STD 58) [RFC2578] [RFC2579] [RFC2580], применимых к «стандартным»
MIB-модулям. Цель настоящего меморандума — документировать
рекомендации, которым следуют при таких рецензированиях.
Обратите внимание, что рекомендации настоящего меморандума не
предназначены для изменения требований или запретов (в смысле «ДОЛЖЕН
(MUST)», «НЕ ДОЛЖЕН (MUST NOT)», «ДОЛЖЕН (SHALL)» или «НЕ ДОЛЖЕН
(SHALL NOT)», как определено в RFC 2119 [RFC2119]) существующих BCP
или интернет-стандартов, кроме случаев, когда эти требования или
запреты неоднозначны либо противоречивы. В исключительных случаях,
когда существуют неоднозначности или противоречия, настоящий
меморандум документирует текущее общепринятое толкование. В некоторых
случаях рекомендации настоящего меморандума действительно изменяют
рекомендации (в смысле «СЛЕДУЕТ (SHOULD)», «НЕ СЛЕДУЕТ (SHOULD NOT)»,
«РЕКОМЕНДУЕТСЯ (RECOMMENDED)» или «НЕ РЕКОМЕНДУЕТСЯ (NOT RECOMMENDED)»,
как определено в RFC 2119) существующих BCP или интернет-стандартов.
Это было сделано там, где практический опыт показал неоптимальность
опубликованных рекомендаций. Кроме того, настоящий меморандум содержит
рекомендации по выбору определённых вариантов SMIv2 (в смысле «МОЖЕТ
(MAY)» или «НЕОБЯЗАТЕЛЬНО (OPTIONAL)», как определено в RFC 2119) в
случаях, когда имеется консенсус относительно предпочтительного подхода.
Хотя некоторые рекомендации настоящего меморандума не применимы к
MIB-документам, не относящимся к пути стандартизации или не являющимся
документами IETF, авторам и рецензентам этих документов следует
рассмотреть возможность использования тех из них, которые применимы.
Рецензенты и авторы должны знать, что некоторые рекомендации настоящего
меморандума не применимы к MIB-модулям, переведённым в SMIv2 из SMIv1
(STD 16) [RFC1155] [RFC1212] [RFC1215].
2. Терминология
Ключевые слова «ДОЛЖЕН (MUST)», «НЕ ДОЛЖЕН (MUST NOT)», «ДОЛЖЕН
(REQUIRED)», «ДОЛЖЕН (SHALL)», «НЕ ДОЛЖЕН (SHALL NOT)», «СЛЕДУЕТ
(SHOULD)», «НЕ СЛЕДУЕТ (SHOULD NOT)», «РЕКОМЕНДУЕТСЯ (RECOMMENDED)»,
«НЕ РЕКОМЕНДУЕТСЯ (NOT RECOMMENDED)», «МОЖЕТ (MAY)» и «НЕОБЯЗАТЕЛЬНО
(OPTIONAL)», когда они используются в рекомендациях настоящего
меморандума, должны толковаться так, как описано в RFC 2119 [RFC2119].
Термины «MIB-модуль» и «информационный модуль» используются в
настоящем меморандуме взаимозаменяемо. В используемом здесь смысле оба
термина относятся к любому из трёх типов информационных модулей,
определённых в разделе 3 RFC 2578 [RFC2578].
Heard Лучшая современная практика [Страница 3]
RFC 4181 Руководство для MIB-документов Сентябрь 2005
Термин «стандартный», когда он приводится в кавычках, используется в
том же смысле, что и в документах SMIv2 [RFC2578] [RFC2579] [RFC2580].
В частности, он используется для обозначения требований, которые эти
документы предъявляют к «стандартным» модулям или «стандартным»
объектам.
3. Общие рекомендации по документированию
В общем случае к спецификациям IETF на пути стандартизации, содержащим
MIB-модули, предъявляются те же требования, что и к RFC IETF на пути
стандартизации (см. [RFC2223bis]), хотя имеются некоторые различия. В
частности, поскольку рассматриваемая версия будет Internet-Draft,
уведомления на титульной странице ДОЛЖНЫ (MUST) соответствовать
требованиям http://www.ietf.org/ietf/1id-guidelines.txt, а не
требованиям [RFC2223bis]. Кроме того, поскольку рассматриваемая
спецификация, как ожидается, будет представлена в IESG, она ДОЛЖНА
(MUST) соответствовать определённым требованиям, которые не обязательно
применимы к RFC; подробности см. в http://www.ietf.org/ID-Checklist.html.
В разделе 4 [RFC2223bis] перечислены разделы, которые могут
существовать в RFC. Разделы, начиная с аннотации, могут также
присутствовать в Internet-Draft; см. http://www.ietf.org/ID-Checklist.html.
«Основная часть меморандума» требуется всегда и в MIB-документе
ДОЛЖНА (MUST) содержать по меньшей мере следующее:
o раздел стандартного текста MIB
o повествовательные разделы
o раздел определений
o раздел «Соображения безопасности»
o раздел «Соображения IANA»
o раздел ссылок
Далее приведены рекомендации по разделам.
3.1. Раздел стандартного текста MIB
Этот раздел ДОЛЖЕН (MUST) содержать дословную копию последней
утверждённой стандартной формулировки Internet-Standard Management
Framework, доступной в сети по адресу
http://www.ops.ietf.org/mib-boilerplate.html.
Heard Лучшая современная практика [Страница 4]
RFC 4181 Руководство для MIB-документов Сентябрь 2005
3.2. Повествовательные разделы
Повествовательная часть ДОЛЖНА (MUST) включать обзорный раздел,
описывающий область и сферу применения MIB-модулей, определённых
спецификацией, и определяющий взаимосвязь (если таковая имеется) этих
MIB-модулей с другими стандартами, особенно со стандартами, содержащими
другие MIB-модули. Повествовательная часть СЛЕДУЕТ (SHOULD) включать
один или несколько разделов для краткого описания структуры MIB-модулей,
определённых спецификацией.
Если MIB-модули, определённые спецификацией, импортируют определения
из других MIB-модулей (кроме определённых в документах SMIv2
[RFC2578] [RFC2579] [RFC2580]) или всегда реализуются совместно с
другими MIB-модулями, то эти факты ДОЛЖНЫ (MUST) быть отмечены в
обзорном разделе, равно как и любые специальные толкования объектов в
других MIB-модулях. Например, так называемые MIB-модули, специфичные
для среды, всегда реализуются совместно с IF-MIB [RFC2863] и ДОЛЖНЫ
(REQUIRED) документировать, как используются определённые объекты в
IF-MIB. Кроме того, MIB-модули, специфичные для среды, которые полагаются
на ifStackTable [RFC2863] и ifInvStackTable [RFC2864] для поддержания
информации о конфигурации и мультиплексировании подуровней интерфейса,
ДОЛЖНЫ (MUST) содержать описание модели уровней.
3.3. Раздел определений
Этот раздел содержит MIB-модуль(и), определённые спецификацией. Эти
MIB-модули ДОЛЖНЫ (MUST) быть написаны на SMIv2 [RFC2578] [RFC2579]
[RFC2580]; SMIv1 [RFC1155] [RFC1212] [RFC1215] имеет статус «НЕ
СЛЕДУЕТ (NOT RECOMMENDED)» [RFC3410] и более не приемлем в MIB-модулях
IETF.
Рекомендации по использованию SMIv2 см. в разделе 4.
3.4. Раздел «Соображения безопасности»
Каждая спецификация, определяющая один или несколько MIB-модулей,
ДОЛЖНА (MUST) содержать раздел, рассматривающий соображения безопасности,
относящиеся к этим модулям. Этот раздел ДОЛЖЕН (MUST) быть составлен по
образцу последнего утверждённого шаблона (доступного по адресу
http://www.ops.ietf.org/mib-security.html). В частности, доступные для
записи MIB-объекты, злоупотребление которыми могло бы вызвать особенно
серьёзные нарушения, ДОЛЖНЫ (MUST) быть явно перечислены по именам, а
связанные с ними риски безопасности ДОЛЖНЫ (MUST) быть изложены; аналогично,
доступные для чтения MIB-объекты, содержащие особенно чувствительную
информацию или вызывающие существенные опасения в отношении
конфиденциальности, ДОЛЖНЫ (MUST) быть явно перечислены по именам, а
причины чувствительности/опасений в отношении конфиденциальности ДОЛЖНЫ
(MUST) быть объяснены. Если для определённой категории MIB-объектов
отсутствуют риски/уязвимости, этот факт ДОЛЖЕН (MUST) быть явно указан.
Отсутствие упоминания конкретной категории MIB-объектов не будет
приравнено к утверждению об отсутствии рисков/уязвимостей в этой категории;
Heard Лучшая современная практика [Страница 5]
RFC 4181 Руководство для MIB-документов Сентябрь 2005
напротив, оно будет расценено как упущение и приведёт к возвращению
документа автору для исправления. Помните, что цель состоит не в
бездумном копировании текста из шаблона, а в обдумывании и оценке
рисков/уязвимостей с последующим изложением/документированием результата
этой оценки.
3.5. Раздел «Соображения IANA»
Чтобы соответствовать политике IESG, изложенной в
http://www.ietf.org/ID-Checklist.html, каждый Internet-Draft,
представляемый IESG для публикации, ДОЛЖЕН (MUST) содержать раздел
«Соображения IANA». Требования к этому разделу различаются в зависимости
от того, какие действия требуются от IANA.
3.5.1. Документы, создающие новое пространство имён
Если Internet-Draft определяет новое пространство имён, которым должна
управлять IANA, то документ ДОЛЖЕН (MUST) включать раздел «Соображения
IANA», соответствующий рекомендациям, установленным в RFC 2434 [RFC2434],
в котором указано, как должно управляться это пространство имён.
Пространства имён, определяемые документами MIB, обычно состоят из диапазона значений некоторого типа (как правило, перечисляемого INTEGER), определяемого TEXTUAL-CONVENTION (TC), либо из набора административно определённых значений OBJECT IDENTIFIER (OID). В каждом случае определения размещаются в автономных модулях MIB, поддерживаемых IANA. Эти поддерживаемые IANA модули MIB отделены от модулей MIB, определённых в спецификациях на пути стандартизации, чтобы новые назначения можно было выполнять без повторной публикации RFC на пути стандартизации. Примеры поддерживаемых IANA модулей MIB включают IANAifType-MIB (http://www.iana.org/assignments/ianaiftype-mib), который определяет пространство имён, используемое IF-MIB [RFC2863], и IANA-RTPROTO-MIB (http://www.iana.org/assignments/ianaiprouteprotocol-mib), который определяет пространство имён, используемое IPMROUTE-STD-MIB [RFC2932].
Текущая практика для таких случаев состоит в том, чтобы включать подробный раздел IANA Considerations, соответствующий RFC 2434, в предложение DESCRIPTION вызова MODULE-IDENTITY в каждом поддерживаемом IANA модуле MIB, а в разделе IANA Considerations документа MIB, определяющего пространства имён, ссылаться на URL соответствующих модулей. Пример см. в RFC 2932 [RFC2932]. Это создаёт проблему «курицы и яйца» для документов MIB, ещё не опубликованных как RFC, поскольку соответствующие поддерживаемые IANA модули MIB ещё не будут существовать. Принятый выход из этой дилеммы состоит в том, чтобы включать первоначальное содержимое каждого поддерживаемого IANA модуля MIB в ненормативный раздел первоначального выпуска документа, определяющего пространство имён; пример см. в [RFC1573], который
Heard Лучшая современная практика [Страница 6]
RFC 4181 Руководство по документам MIB Сентябрь 2005
описывает первоначальную версию IANAifType-MIB. Этот материал обычно исключается из последующих обновлений документа, поскольку поддерживаемые IANA модули тогда доступны в сети (ср. [RFC2863]).
Рецензенты проектов документов MIB, к которым применимы эти соображения, ДОЛЖНЫ (MUST) проверить, что раздел IANA Considerations, предложенный для публикации в RFC, присутствует и содержит указатели на надлежащие поддерживаемые IANA модули MIB. Рецензенты Internet-Drafts, содержащих предлагаемое первоначальное содержимое поддерживаемых IANA модулей MIB, также ДОЛЖНЫ (MUST) проверить, что предложения DESCRIPTION вызовов MODULE-IDENTITY содержат раздел IANA Considerations, соответствующий руководству RFC 2434.
3.5.2. Документы, требующие назначений в существующих пространствах имён
Если Internet-Draft требует от IANA обновить существующий реестр до публикации в качестве RFC, то раздел IANA Considerations в проекте ДОЛЖЕН (MUST) документировать этот факт. Документы MIB, содержащие первоначальную версию модуля MIB, обычно требуют, чтобы IANA назначила значение OBJECT IDENTIFIER для значения MODULE-IDENTITY модуля MIB и, возможно, также выполнила другие назначения. Internet-Drafts, содержащие такие модули MIB, ДОЛЖНЫ (MUST) содержать раздел IANA Considerations, в котором указаны реестры, подлежащие обновлению, дескрипторы, которым назначаются значения OBJECT IDENTIFIER, и поддеревья, в которых должны распределяться значения. Текст СЛЕДУЕТ (SHOULD) составить так, чтобы после публикации он служил для документирования назначений OBJECT IDENTIFIER. Например, для Internet-Draft, содержащего единственный модуль MIB с дескриптором MODULE-IDENTITY powerEthernetMIB, которому должно быть назначено значение в поддереве 'mib-2', уместно было бы следующее:
Модуль MIB в этом документе использует следующие назначенные IANA
значения OBJECT IDENTIFIER, зарегистрированные в реестре SMI Numbers:
Дескриптор значение OBJECT IDENTIFIER
---------- ---------------------------
powerEthernetMIB { mib-2 XXX }
Примечание редактора (подлежит удалению до публикации): IANA
предлагается назначить значение для "XXX" в поддереве 'mib-2'
и зарегистрировать назначение в реестре SMI Numbers. После
выполнения назначения RFC Editor предлагается заменить
"XXX" (здесь и в модуле MIB) назначенным значением и удалить
это примечание.
Heard Лучшая современная практика [Страница 7]
RFC 4181 Руководство по документам MIB Сентябрь 2005
Обратите особое внимание: до официального назначения IANA проект документа ДОЛЖЕН (MUST) использовать заполнители (такие как указанное выше «XXX»), а не фактические номера. Пример того, как это делается в проекте модуля MIB, см. в разделе 4.5.
3.5.3. Документы без запросов к IANA
Если Internet-Draft не направляет IANA никаких запросов, то этот факт ДОЛЖЕН (MUST) быть задокументирован в разделе IANA Considerations. Когда Internet-Draft содержит обновление ранее опубликованного модуля MIB, он, как правило, не требует никаких действий со стороны IANA, но может наследовать из RFC, содержащего предыдущую версию модуля MIB, раздел IANA Considerations, документирующий существующие назначения. В таких случаях проект ДОЛЖЕН (MUST) содержать примечание (подлежащее удалению до публикации), прямо указывающее, что от IANA ничего не требуется. Например, проект, содержащий обновлённую версию POWER-ETHERNET-MIB [RFC3621], может включать раздел IANA Considerations следующего вида:
Модуль MIB в этом документе использует следующие назначенные IANA
значения OBJECT IDENTIFIER, зарегистрированные в реестре SMI Numbers:
Дескриптор значение OBJECT IDENTIFIER
---------- ---------------------------
powerEthernetMIB { mib-2 105 }
Примечание редактора (подлежит удалению до публикации): этот проект
не направляет IANA дополнительных запросов.
Если Internet-Draft не направляет IANA никаких запросов и не имеется существующих назначений, которые необходимо документировать, то подходящий текст для проекта мог бы быть приблизительно следующим:
Этот документ не требует действий IANA.
3.6. Разделы ссылок
Раздел 4.7f [RFC2223bis] устанавливает требования к разделам ссылок в RFC; http://www.ietf.org/ID-Checklist.html устанавливает те же требования для Internet-Drafts. В частности, ДОЛЖНЫ (MUST) существовать отдельные списки нормативных и информационных ссылок, каждый в отдельном разделе. Оформление СЛЕДУЕТ (SHOULD) оформлению недавно опубликованных RFC.
Стандартный шаблонный текст MIB, доступный по адресу http://www.ops.ietf.org/mib-boilerplate.html, включает списки нормативных и информационных ссылок, которые ДОЛЖНЫ (MUST) присутствовать во всех спецификациях IETF, содержащих модули MIB.
Heard Лучшая современная практика [Страница 8]
RFC 4181 Руководство по документам MIB Сентябрь 2005
Если элементы из других модулей MIB появляются в операторе IMPORTS раздела Definitions, то спецификации, содержащие эти модули MIB, ДОЛЖНЫ (MUST) быть включены в список нормативных ссылок. Когда элементы импортируются из поддерживаемого IANA модуля MIB, соответствующая нормативная ссылка ДОЛЖНА (SHALL) указывать на сетевую версию этого модуля MIB. Политика RFC Editor состоит в том, что все ссылки должны цитироваться в тексте; такие цитаты ДОЛЖНЫ (MUST) появляться в обзорном разделе, где необходимо упомянуть документы, содержащие импортированные определения (кроме уже упомянутых в шаблонном тексте MIB) (ср. раздел 3.2).
В общем случае каждая нормативная ссылка СЛЕДУЕТ (SHOULD) указывать на самую последнюю версию рассматриваемой спецификации.
3.7. Уведомления об авторском праве
Документы IETF MIB ДОЛЖНЫ (MUST) содержать уведомления об авторском праве и отказ от ответственности, указанные в разделах 5.4 и 5.5 RFC 3978 [RFC3978]. Авторы и рецензенты ДОЛЖНЫ (MUST) проверять, что в эти уведомления внесён правильный год. Кроме того, предложение DESCRIPTION вызова MODULE-IDENTITY каждого модуля MIB, который появится в опубликованном RFC, ДОЛЖНО (MUST) содержать указатель на уведомления об авторском праве в RFC. Шаблон, пригодный для включения в Internet-Draft и подходящий для модулей MIB, кроме тех, которые будут поддерживаться IANA, приведён ниже:
DESCRIPTION
" [ ... ]
Copyright (C) The Internet Society (date). This version
of this MIB module is part of RFC yyyy; see the RFC
itself for full legal notices."
-- RFC Ed.: replace yyyy with actual RFC number & remove this note
Шаблон, пригодный для модулей MIB, которые будут поддерживаться IANA, приведён ниже:
DESCRIPTION
" [ ... ]
Copyright (C) The Internet Society (date). The initial
version of this MIB module was published in RFC yyyy;
for full legal notices see the RFC itself. Supplementary
information may be available at:
http://www.ietf.org/copyrights/ianamib.html."
-- RFC Ed.: replace yyyy with actual RFC number & remove this note
Heard Лучшая современная практика [Страница 9]
RFC 4181 Руководство по документам MIB Сентябрь 2005
В каждом случае вместо слова "date" должен быть указан текущий год.
3.8. Раздел интеллектуальной собственности
Раздел 5 RFC 3979 [RFC3979] содержит уведомление о правах интеллектуальной собственности или иных правах, которое должно присутствовать во всех RFC IETF. Дословная копия этого уведомления СЛЕДУЕТ (SHOULD) присутствовать в каждом документе IETF MIB.
4. Руководство по использованию SMIv2
В общем случае модули MIB в спецификациях IETF на пути стандартизации ДОЛЖНЫ (MUST) соответствовать всем синтаксическим и семантическим требованиям SMIv2 [RFC2578] [RFC2579] [RFC2580], применимым к «стандартным» модулям MIB, и, за исключением указанных ниже случаев, СЛЕДУЕТ (SHOULD) соответствовать рекомендациям SMIv2. Руководство в этом разделе предназначено для дополнения документов SMIv2 следующими способами:
o документировать текущую общепринятую интерпретацию в случаях, когда
эти документы содержат неоднозначности или противоречия;
o обновлять рекомендации в этих документах, которые практический опыт
показал устаревшими или иным образом неоптимальными;
o предоставлять руководство по выбору вариантов SMIv2 в случаях, когда
существует консенсус относительно предпочтительного подхода.
4.1. Имена модулей
Раздел 3 RFC 2578 устанавливает правила для имён модулей. В частности, обратите внимание, что имена «стандартных» модулей ДОЛЖНЫ (MUST) быть уникальными, ДОЛЖНЫ (MUST) соответствовать синтаксическим правилам раздела 3 RFC 2578 и НЕ ДОЛЖНЫ (MUST NOT) изменяться при пересмотре модуля MIB (см. также раздел 10 RFC 2578).
СЛЕДУЕТ (RECOMMENDED), чтобы имена модулей были мнемоническими. Предлагаемые соглашения об именовании см. в приложении C.
4.2. Дескрипторы, имена TC и метки
Разделы 3.1, 7.1.1 и 7.1.4 RFC 2578, а также раздел 3 RFC 2579 рекомендуют, чтобы дескрипторы и имена, связанные с вызовами макросов, и метки, связанные с перечисляемыми значениями INTEGER и BITS, имели длину не более 32 символов, но требуют, чтобы их длина не превышала 64 символов.
Heard Лучшая современная практика [Страница 10]
RFC 4181 Руководство по документам MIB Сентябрь 2005
Ограничение дескрипторов, имён TC и меток 32 символами часто противоречит рекомендации, чтобы они были мнемоническими, и (для дескрипторов и имён TC) требованию, чтобы они были уникальными (см. раздел 3.1 RFC 2578 и раздел 3 RFC 2579). Консенсус текущего пула рецензентов MIB заключается в том, что рекомендацию SMIv2 ограничивать дескрипторы, имена TC и метки 32 символами СЛЕДУЕТ (SHOULD) отложить в пользу ясности и уникальности и что автоматизированным инструментам, таким как компиляторы MIB, НЕ СЛЕДУЕТ (SHOULD NOT) по умолчанию выдавать предупреждения о нарушении этой рекомендации.
Обратите внимание, что нарушения ограничения в 64 символа НЕ ДОЛЖНЫ (MUST NOT) игнорироваться; они ДОЛЖНЫ (MUST) рассматриваться как ошибки.
Предлагаемые соглашения об именовании дескрипторов и TC см. в приложении C.
4.3. Иерархия именования
Раздел 4 RFC 2578 описывает поддеревья идентификаторов объектов, поддерживаемые IANA, и устанавливает способы использования этих поддеревьев. В частности, поддерево mgmt { iso 3 6 1 2 } используется для идентификации «стандартных» объектов IETF, тогда как поддерево experimental { iso 3 6 1 3 } используется для идентификации объектов, находящихся в разработке IETF. Объекты ДОЛЖНЫ (REQUIRED) перемещаться из поддерева experimental в поддерево mgmt, когда модуль MIB входит на путь стандартизации IETF.
Опыт показал, что непрактично перемещать объекты из одного поддерева в другое, как только эти объекты получили широкомасштабное использование в эксплуатационной среде. Поэтому любой объект, предназначенный для развёртывания в эксплуатационной среде, НЕ ДОЛЖЕН (MUST NOT) регистрироваться в поддереве experimental независимо от статуса стандартизации этого объекта. Поддерево experimental следует использовать только для объектов, предназначенных для ограниченного экспериментального развёртывания. Такие объекты обычно определяются в Experimental RFC.
Примечание: термин «объект» в используемом здесь значении и в разделе 4 RFC 2578 следует толковать широко — как любую конструкцию, приводящую к регистрации OBJECT IDENTIFIER. Список таких конструкций установлен в разделе 3.6 RFC 2578.
4.4. Оператор IMPORTS
Раздел 3.2 RFC 2578 устанавливает, какие символы должны импортироваться, а также перечисляет некоторые предопределённые символы, которые не должны импортироваться.Общее требование состоит в том, что если используется внешний символ, отличный от предопределённого типа ASN.1 или конструкции BITS, то он ДОЛЖЕН (MUST) быть упомянут в операторе IMPORTS модуля. Слова «внешний объект» в первом абзаце этого раздела могут создавать
Heard Best Current Practice [Page 11]
RFC 4181 Guidelines for MIB Documents September 2005
впечатление, что такие символы ограничены теми, которые ссылаются на определения объектов, но это не так, как должны прояснить последующие абзацы.
Обратите внимание, что исключения из этого общего требования предоставлены разделами 5.4.3 и 6.5.2 RFC 2580 для дескрипторов объектов, фигурирующих в предложении OBJECT оператора MODULE-COMPLIANCE или в предложении VARIATION оператора AGENT-CAPABILITIES. Некоторые компиляторы MIB также предоставляют исключения для дескрипторов уведомлений, фигурирующих в предложении VARIATION, и для дескрипторов групп объектов и групп уведомлений, на которые ссылаются предложения MANDATORY-GROUPS, GROUP или INCLUDES, хотя RFC 2580 (по-видимому, вследствие упущения) не упоминает эти случаи. Исключения иногда рассматриваются как бесполезные, поскольку они делают правила IMPORTS более сложными, а межмодульные зависимости — менее очевидными, чем они были бы в противном случае. Поэтому внешние символы, на которые ссылаются операторы соответствия и операторы возможностей, МОГУТ (MAY) быть перечислены в операторе IMPORTS; если это сделано, это СЛЕДУЕТ (SHOULD) делать последовательно.
Наконец, хотя SMI этого не запрещает, считается плохим стилем импортировать неиспользуемые символы, и MIB-модули на пути стандартов НЕ ДОЛЖНЫ (SHOULD NOT) этого делать.
4.5. Вызов MODULE-IDENTITY
Раздел 3 RFC 2578 требует, чтобы все MIB-модули SMIv2 начинались ровно с одного вызова макроса MODULE-IDENTITY. Этот вызов ДОЛЖЕН (MUST) располагаться непосредственно после оператора IMPORTS.
В разделе 5 RFC 2578 описано, как используются различные предложения. Следующие дополнительные рекомендации применяются ко всем MIB-модулям, над которыми IETF осуществляет контроль изменений:
- Если модуль был разработан рабочей группой IETF, то предложение
ORGANIZATION ДОЛЖНО (MUST) указывать полное наименование рабочей
группы, а предложение CONTACT-INFO ДОЛЖНО (MUST) включать сведения
о списке рассылки рабочей группы. Предложение CONTACT-INFO также
СЛЕДУЕТ (SHOULD) снабжать указателем на веб-страницу рабочей группы.
- Предложение REVISION ДОЛЖНО (MUST) присутствовать для каждой
редакции MIB-модуля, а время UTC наиболее позднего предложения
REVISION ДОЛЖНО (MUST) совпадать со временем предложения
LAST-UPDATED. Предложение DESCRIPTION, связанное с каждой редакцией,
ДОЛЖНО (MUST) указывать, в каком RFC появилась эта редакция, и
СЛЕДУЕТ (SHOULD) предоставлять список всех существенных изменений.
При пересмотре MIB-модуля времена UTC во всех предложениях REVISION
СЛЕДУЕТ (SHOULD) обновлять с использованием четырёхзначного
обозначения года.
Heard Best Current Practice [Page 12]
RFC 4181 Guidelines for MIB Documents September 2005
- Значение, присваиваемое дескриптору MODULE-IDENTITY, ДОЛЖНО (MUST)
быть уникальным и (для MIB-модулей IETF на пути стандартов)
СЛЕДУЕТ (SHOULD) располагаться под поддеревом mgmt [RFC2578]. Чаще
всего это будет значение, назначенное IANA непосредственно под
mib-2 [RFC2578], хотя для MIB-модулей, специфичных для среды передачи
и расширяющих IF-MIB [RFC2863], принято использовать назначенное IANA
значение под transmission [RFC2578]. В прошлом некоторые рабочие
группы IETF выполняли собственные назначения из поддеревьев,
делегированных им IANA, но эта практика оказалась проблематичной и
НЕ СЛЕДУЕТ (NOT RECOMMENDED) её применять.
Пока MIB-модуль находится в разработке, номер RFC, в котором он в конечном итоге будет опубликован, обычно неизвестен и должен быть внесён RFC Editor до публикации. Подходящая форма предложения REVISION, применимого к разрабатываемой версии, могла бы выглядеть примерно следующим образом:
REVISION "200212132358Z" -- 13 декабря 2002 г.
DESCRIPTION "Initial version, published as RFC yyyy."
-- RFC Ed.: замените yyyy фактическим номером RFC и удалите это примечание
Обратите внимание, что после публикации RFC предложение REVISION присутствует только для опубликованных версий MIB-модуля, а не для промежуточных версий, существовавших только в виде Internet-Drafts. Таким образом, черновая версия MIB-модуля ДОЛЖНА (MUST) содержать только одно новое предложение REVISION, охватывающее все изменения после последней опубликованной версии (если таковая имеется).
Когда начальная версия MIB-модуля находится в разработке, значение, присваиваемое дескриптору MODULE-IDENTITY, будет неизвестно, если используется значение, назначаемое IANA, поскольку назначение производится непосредственно перед публикацией в качестве RFC. Принятая форма оператора MODULE-IDENTITY в черновых версиях такого модуля выглядит примерно следующим образом:
<descriptor> MODULE-IDENTITY
[ ... ]
::= { <subtree> XXX }
-- RFC Ed.: замените XXX номером, назначенным IANA, и удалите это примечание
где <descriptor> — любой дескриптор, выбранный для модуля, а <subtree> — поддерево, под которым должен быть зарегистрирован модуль (например, mib-2 или transmission). Обратите внимание, что XXX необходимо временно заменить числом, чтобы модуль мог скомпилироваться.
Heard Best Current Practice [Page 13]
RFC 4181 Guidelines for MIB Documents September 2005
Особо отметим: до официального назначения IANA черновой документ ДОЛЖЕН (MUST) использовать заполнитель (такой как «XXX» выше), а не фактический номер. Если в процессе разработки желательны пробные реализации, то у IANA может быть получено назначение под поддеревом 'experimental' (см. раздел 4.3).
4.6. Текстовые соглашения и определения объектов
4.6.1. Использование типов данных
4.6.1.1. INTEGER, Integer32, Gauge32 и Unsigned32
32-битные целочисленные типы данных INTEGER, Integer32, Gauge32 и Unsigned32 описаны в разделе 2 RFC 2578 и дополнительно разъяснены в разделах 7.1.1, 7.1.7 и 7.1.11 RFC 2578. Следующие рекомендации применяются при выборе одного из этих типов данных для определения объекта или текстового соглашения:
- Для перечислений с целочисленными значениями:
- INTEGER ДОЛЖЕН (REQUIRED) использоваться; Integer32, Unsigned32 и Gauge32
НЕ ДОЛЖНЫ (MUST NOT) использоваться.
Обратите внимание, что RFC 2578 рекомендует (но не требует), чтобы перечисления с целочисленными значениями начинались с 1 и нумеровались последовательно. Этой рекомендации СЛЕДУЕТ (SHOULD) придерживаться, если только нет обоснованной причины поступить иначе, например для соответствия значениям внешних данных или указания особых случаев, и любое такое использование для особого случая СЛЕДУЕТ (SHOULD) чётко документировать. Пример см. в TC InetAddressType [RFC4001].
Хотя SMI допускает, чтобы предложения DEFVAL для перечислений с целочисленными значениями задавали значение по умолчанию либо меткой, либо числовым значением, форма с меткой предпочтительна, поскольку все примеры в RFC 2578 имеют такую форму, а некоторые инструменты не принимают числовую форму.
- Если диапазон значений находится в пределах от -2147483648 до 2147483647 (включительно) и возможны отрицательные значения, то:
- Integer32 СЛЕДУЕТ (RECOMMENDED) использовать;
- INTEGER допустим;
- Unsigned32 и Gauge32 НЕ ДОЛЖНЫ (MUST NOT) использоваться.
- Если диапазон значений находится в пределах от 0 до 4294967295 (включительно), а значение моделируемой информации может увеличиться выше максимального значения или уменьшиться ниже минимального значения, то:
- Gauge32 СЛЕДУЕТ (RECOMMENDED) использовать;
- Unsigned32 допустим;
- INTEGER и Integer32 НЕ ДОЛЖНЫ (MUST NOT) использоваться, если
возможны значения больше 2147483647.
Heard Best Current Practice [Page 14]
RFC 4181 Guidelines for MIB Documents September 2005
- Если диапазон значений находится в пределах от 0 до 4294967295 (включительно), возможны значения больше 2147483647, а значение моделируемой информации не увеличивается выше максимального значения и не уменьшается ниже минимального значения, то:
- Unsigned32 СЛЕДУЕТ (RECOMMENDED) использовать;
- Gauge32 допустим;
- INTEGER и Integer32 НЕ ДОЛЖНЫ (MUST NOT) использоваться.
- Если диапазон значений находится в пределах от 0 до 2147483647 (включительно), а значение моделируемой информации не увеличивается выше максимального значения и не уменьшается ниже минимального значения, то:
- Unsigned32 СЛЕДУЕТ (RECOMMENDED) использовать;
- INTEGER, Integer32 и Gauge32 допустимы.
- Для объектов с целочисленными значениями, фигурирующих в предложении INDEX, или для TC с целочисленными значениями, которые будут использоваться в индексном столбце:
- Unsigned32 с диапазоном, исключающим ноль, СЛЕДУЕТ (RECOMMENDED)
использовать для большинства индексных объектов. Допустимо включать
ноль в диапазон, когда он семантически значим или используется как
значение индекса для уникальной строки с особыми свойствами. Такое
использование СЛЕДУЕТ (SHOULD) чётко документировать в предложении
DESCRIPTION.
- Integer32 или INTEGER с неотрицательным диапазоном допустимы.
Опять же, ноль СЛЕДУЕТ (SHOULD) исключать из диапазона, кроме
случаев, когда он семантически значим или используется как значение
индекса для уникальной строки с особыми свойствами, и в таких случаях
использование СЛЕДУЕТ (SHOULD) чётко документировать в предложении
DESCRIPTION.
- Использование Gauge32 допустимо для индексных объектов, обладающих
семантикой gauge.
Приведённые выше рекомендации объединяют как правила использования целочисленных типов данных, так и правила INDEX из раздела 7.7 RFC 2578 вплоть до и включая пункт (1), а также предпоследний абзац на странице 28.
Иногда внешним переменным будет необходимо представлять значения индексного объекта — например, ifIndex [RFC2863]. В таких случаях авторам модуля, содержащего этот объект, СЛЕДУЕТ (SHOULD) рассмотреть определение TC, таких как InterfaceIndex и/или InterfaceIndexOrZero [RFC2863].
Обратите внимание, что INTEGER является предопределённым типом ASN.1 и НЕ ДОЛЖЕН (MUST NOT) присутствовать в операторе IMPORTS модуля, тогда как Integer32, Gauge32 и Unsigned32 определены SNMPv2-SMI и ДОЛЖНЫ (MUST) импортироваться из этого модуля, если используются.
4.6.1.2. Counter32 и Counter64
Counter32 и Counter64 имеют специальную семантику, описанную соответственно в разделах 7.1.6 и 7.1.10 RFC 2578. Определения объектов ДОЛЖНЫ (MUST) (а текстовые соглашения СЛЕДУЕТ (SHOULD)) соблюдать эту семантику. Это означает следующее:
- Допустимо использовать Counter32/64 для счётчиков, которые могут/будут
сбрасываться при повторной инициализации подсистемы управления или при
возникновении других необычных/нерегулярных событий (например,
счётчики, поддерживаемые на линейной карте, могут сбрасываться при
сбросе линейной карты). Однако если возможно возникновение таких других
необычных/нерегулярных событий, предложение DESCRIPTION ДОЛЖНО (MUST)
указывать это и ДОЛЖНО (MUST) описывать эти другие необычные/нерегулярные
события с достаточной подробностью, чтобы приложение управления могло
определить, произошёл ли сброс с момента последнего опроса счётчика.
СЛЕДУЕТ (RECOMMENDED) предоставить индикатор разрыва непрерывности,
описанный в разделах 7.1.6 и 7.1.10 RFC 2578. Пример такого индикатора
разрыва непрерывности см. в объекте ifCounterDiscontinuityTime в IF-MIB
[RFC2863].
- НЕ допускается указывать в предложении DESCRIPTION Counter32/64, что
существует требование, по которому при разрыве непрерывности счётчик
ДОЛЖЕН (MUST) сбрасываться в ноль или в какое-либо другое конкретное
значение.
- НЕ допускается указывать в предложении DESCRIPTION Counter32/64, что
существует требование, по которому он ДОЛЖЕН (MUST) сбрасываться в
какое-либо конкретное время/при конкретном событии (например, в полночь).
- НЕ допускается, чтобы один менеджер запрашивал у агента сброс значений
счётчика(-ов) в ноль, и Counter32/64 — неподходящий синтаксис для
«счётчиков», которые регулярно сами сбрасываются в ноль. Для последних
лучше определить или использовать текстовые соглашения, такие как
приведённые в RFC 3593 [RFC3593] или RFC 3705 [RFC3705].
Heard Best Current Practice [Page 15]
RFC 4181 Guidelines for MIB Documents September 2005
Раздел 7.1.10 RFC 2578 устанавливает требование для «стандартных» MIB-модулей: тип Counter64 может использоваться только в том случае, если моделируемая информация переполнилась бы менее чем за один час при использовании вместо него типа Counter32. Теперь, когда SNMPv3 является стандартом Интернета, а SNMPv1 имеет исторический статус (сведения о статусе см. в http://www.rfc-editor.org/rfcxx00.html, а обоснование — в [RFC3410]), нет причин продолжать применять это ограничение. В дальнейшем «стандартные» MIB-модули МОГУТ (MAY) использовать тип Counter64, когда это имеет смысл, и ДОЛЖНЫ (MUST) использовать
Heard Best Current Practice [Page 16]
RFC 4181 Guidelines for MIB Documents September 2005
Counter64, если моделируемая информация переполнилась бы менее чем за один час при использовании вместо него типа Counter32. Также обратите внимание, что более не существует требования определять аналоги Counter32 для каждого объекта Counter64, хотя делать это всё ещё разрешается.
Также существуют тесно связанные текстовые соглашения ZeroBasedCounter32 и ZeroBasedCounter64, определённые в RMON2-MIB [RFC2021] и HCNUM-TC [RFC2856] соответственно.
Единственное различие между TC ZeroBasedCounter32/64 и Counter32/64 состоит в их начальном значении; в момент времени X, где X — их минимальное время до переполнения после их создания, поведение ZeroBasedCounter32/64 становится в точности таким же, как у Counter32/64. Следовательно, предыдущие абзацы/правила применяются не только к Counter32/64, но и к TC ZeroBasedCounter32/64.
4.6.1.3. CounterBasedGauge64К сожалению, SMIv2 не предоставляет 64-разрядных целочисленных базовых типов. Для восполнения этого упущения в HCNUM-TC [RFC2856] определено текстовое соглашение CounterBasedGauge64. Это TC использует Counter64 в качестве базового типа, но отбрасывает специальную семантику счётчика, что допускается общепринятым толкованием раздела 3.3 RFC 2579. Оно наследует все синтаксические ограничения этого типа, что означает, что его НЕ ДОЛЖНО (MUST NOT) быть возможно уточнить посредством подтипизации, а объекты, определённые с его использованием, НЕ ДОЛЖНЫ (MUST NOT) появляться в предложении INDEX, НЕ ДОЛЖНЫ (MUST NOT) иметь предложение DEFVAL и ДОЛЖНЫ (MUST) иметь MAX-ACCESS со значением read-only или accessible-for-notify.
Это TC СЛЕДУЕТ (SHOULD) использовать для определений объектов, которым требуется 64-разрядный беззнаковый тип данных с семантикой gauge. Если необходим 64-разрядный беззнаковый тип данных с иной семантикой, то ДОЛЖНО (MUST) использоваться другое TC, основанное на Counter64, поскольку одно TC не может уточнять другое (см. раздел 3.5 RFC 2579).
4.6.1.4. OCTET STRING
Тип OCTET STRING описан в разделе 7.1.2 RFC 2578. Он представляет произвольные двоичные или текстовые данные, длина которых составляет от 0 до 65535 октетов включительно. Объекты и TC, чей SYNTAX имеет этот тип, СЛЕДУЕТ (SHOULD) снабжать ограничением размера, когда фактические границы строже, чем ограничения, налагаемые SMI. Это особенно верно для индексных объектов. Однако обратите внимание, что ограничения размера НЕ СЛЕДУЕТ (SHOULD NOT) налагать произвольно, поскольку SMI не допускает их последующего изменения.
Heard Лучшая современная практика [Страница 17]
RFC 4181 Guidelines for MIB Documents Сентябрь 2005
Существует ряд стандартных TC, удовлетворяющих некоторым из наиболее распространённых требований к специализированным типам OCTET STRING. В частности, SNMPv2-TC [RFC2579] содержит TC DisplayString, PhysAddress, MacAddress и DateAndTime; SNMP-FRAMEWORK-MIB [RFC3411] содержит TC SnmpAdminString; а SYSAPPL-MIB [RFC2287] содержит TC Utf8String и LongUtf8String. Когда стандартное TC предоставляет требуемую семантику, его СЛЕДУЕТ (SHOULD) использовать в предложении SYNTAX объекта вместо OCTET STRING или эквивалентного TC, определённого локально.
Обратите внимание, что OCTET STRING — предопределённый тип ASN.1 и НЕ ДОЛЖЕН (MUST NOT) присутствовать в операторе IMPORTS модуля.
4.6.1.5. OBJECT IDENTIFIER
Тип OBJECT IDENTIFIER описан в разделе 7.1.3 RFC 2578. Его экземпляры представляют административно назначенные имена. Обратите внимание, что как SMI, так и протокол SNMP ограничивают экземпляры этого типа 128 подидентификаторами и требуют, чтобы каждый подидентификатор находился в диапазоне от 0 до 4294967295 включительно. Подтипизация не допускается.
Назначение значений OBJECT IDENTIFIER состоит в предоставлении авторитетной идентификации либо некоторого типа элемента, либо конкретного экземпляра некоторого типа элемента. Среди элементов, которые могут быть идентифицированы таким образом, — определения в модулях MIB, созданные посредством конструкций MODULE-IDENTITY, OBJECT-IDENTITY, OBJECT-TYPE, NOTIFICATION-TYPE, OBJECT-GROUP, NOTIFICATION-GROUP, MODULE-COMPLIANCE и AGENT-CAPABILITIES; а также посредством экземпляров объектов, определённых в модулях MIB, протоколах, языках, спецификациях, типах интерфейсов, аппаратном и программном обеспечении. Для некоторых таких применений существуют иные возможности, например OCTET STRING или перечислимые значения INTEGER. Тип OBJECT IDENTIFIER СЛЕДУЕТ (SHOULD) использовать вместо альтернатив, когда множество идентификационных значений должно быть независимо расширяемым без необходимости в реестре, обеспечивающем централизованную координацию.
Существует ряд стандартных TC, удовлетворяющих некоторым из наиболее распространённых требований к специализированным типам OBJECT IDENTIFIER. В частности, SNMPv2-TC [RFC2579] содержит TC AutonomousType, VariablePointer и RowPointer. Когда стандартное TC предоставляет требуемую семантику, его СЛЕДУЕТ (SHOULD) использовать в предложении SYNTAX объекта вместо OBJECT IDENTIFIER или эквивалентного TC, определённого локально.
Обратите внимание, что OBJECT IDENTIFIER — предопределённый тип ASN.1 и НЕ ДОЛЖЕН (MUST NOT) присутствовать в операторе IMPORTS модуля.
Heard Лучшая современная практика [Страница 18]
RFC 4181 Guidelines for MIB Documents Сентябрь 2005
4.6.1.6. Конструкция BITS
Конструкция BITS описана в разделе 7.1.4 RFC 2578. Она представляет перечисление именованных битов. Позиции битов в TC или определении объекта, чей SYNTAX имеет этот тип, ДОЛЖНЫ (MUST) начинаться с 0 и СЛЕДУЕТ (SHOULD) быть непрерывными.
Обратите внимание, что конструкция BITS определяется макросами, которые её используют, и поэтому НЕ ДОЛЖНА (MUST NOT) присутствовать в операторе IMPORTS модуля.
4.6.1.7. IpAddress
Тип IpAddress, описанный в разделе 7.1.5 RFC 2578, НЕ СЛЕДУЕТ (SHOULD NOT) использовать в новых модулях MIB. Вместо него СЛЕДУЕТ (SHOULD) использовать текстовые соглашения InetAddress/InetAddressType [RFC4001].
4.6.1.8. TimeTicks
Тип TimeTicks описан в разделе 7.1.8 RFC 2578. Он представляет время в сотых долях секунды между двумя эпохами, приведённое по модулю 2^32. Его НЕ ДОЛЖНО (MUST NOT) быть возможно уточнить посредством подтипизации, а предложение DESCRIPTION любого объекта или TC, чей SYNTAX имеет этот тип, ДОЛЖНО (MUST) идентифицировать опорные эпохи.
Тип TimeTicks НЕ СЛЕДУЕТ (SHOULD NOT) использовать непосредственно в определениях объектов, которые являются снимками sysUpTime [RFC3418]. TC TimeStamp [RFC2579] уже передаёт требуемую семантику, и вместо TimeTicks СЛЕДУЕТ (SHOULD) использовать его.
4.6.1.9. TruthValue
TC TruthValue определено в SNMPv2-TC [RFC2579]. Это перечислимый тип INTEGER, принимающий значения true(1) и false(2).
Это TC СЛЕДУЕТ (SHOULD) использовать в предложении SYNTAX определений объектов, которым требуется булев тип. Модули MIB НЕ СЛЕДУЕТ (SHOULD NOT) использовать перечислимые типы INTEGER или определять TC, дублирующие его семантику.
4.6.1.10. Другие типы данных
Существует ряд стандартных TC, удовлетворяющих некоторым из наиболее распространённых требований к специализированным типам данных. Некоторые были упомянуты выше, а приложение B содержит частичный список, включающий их, а также некоторые другие, несколько более специализированные. Версию этого списка в Интернете, обновляемую по мере разработки новых TC, можно найти по адресу http://www.ops.ietf.org/mib-common-tcs.html.
Heard Лучшая современная практика [Страница 19]
RFC 4181 Guidelines for MIB Documents Сентябрь 2005
Всякий раз, когда стандартное TC уже передаёт требуемую семантику, его СЛЕДУЕТ (SHOULD) использовать в определении объекта вместо соответствующего базового типа или TC, определённого локально. Это особенно верно для TC, определённых в SNMPv2-TC [RFC2579] и SNMP-FRAMEWORK-MIB [RFC3411], поскольку они являются стандартами Интернета, и поэтому продвижение по пути стандартизации модулей, ссылающихся на них, не будет задерживаться из-за таких ссылок.
Авторы модулей MIB должны знать, что перечислимые TC INTEGER или BITS в некоторых случаях могут быть расширены дополнительными перечислимыми значениями или дополнительными позициями битов. Когда импортированное TC, которое может быть расширено таким образом, используется для определения объекта, в который может выполняться запись или который служит индексом в таблице read-create, то множество значений или позиций битов, которое необходимо поддерживать, СЛЕДУЕТ (SHOULD) указать либо в предложении DESCRIPTION объекта, либо в предложении OBJECT в заявлении (заявлениях) о соответствии модуля MIB. Это можно сделать явным перечислением требуемых значений или позиций битов либо указанием, что реализация может поддерживать выбранное ею подмножество значений или позиций битов.
4.6.2. Предложения DESCRIPTION и REFERENCE
Трудно переоценить важность точного и недвусмысленного предложения DESCRIPTION для всех объектов и TC. Предложение DESCRIPTION содержит инструкции, которые реализаторы будут использовать для реализации объекта, и если они недостаточны или неоднозначны, то качество реализации пострадает. Вероятно, важнейшая отдельная задача рецензента MIB состоит в обеспечении того, чтобы предложения DESCRIPTION были достаточно ясными и недвусмысленными для создания взаимодействующих реализаций.
Очень распространённая проблема — увидеть определение объекта, например, 'stdMIBPoofpoofCounter', с предложением DESCRIPTION, которое лишь гласит «Число poofpoof», не указывая, что такое 'poofpoof'. В таких случаях НАСТОЯТЕЛЬНО СЛЕДУЕТ (RECOMMENDED) либо предоставить хотя бы минимальное объяснение, либо включить предложение REFERENCE, указывающее на определение 'poofpoof'.
Для объектов read-write (кроме столбцов в таблицах read-create, которые имеют чётко определённые свойства сохраняемости) СЛЕДУЕТ (RECOMMENDED), чтобы предложение DESCRIPTION указывало, что происходит со значением после перезагрузки агента. Среди возможностей: значение остаётся неизменным, возвращается к чётко определённому значению по умолчанию или результат зависит от реализации.
Heard Лучшая современная практика [Страница 20]
RFC 4181 Guidelines for MIB Documents Сентябрь 2005
4.6.3. Предложение DISPLAY-HINT
Предложение DISPLAY-HINT используется в TC для предоставления приложению управления необязывающей подсказки о том, как может отображаться значение экземпляра объекта, определённого с синтаксисом в TC. Его наличие необязательно.
Хотя приложения управления обычно по умолчанию используют десятичный формат ("d") для целочисленных TC, не являющихся перечислениями, и шестнадцатеричный формат ("1x:" или "1x " или "1x_") для TC строк октетов, когда предложение DISPLAY-HINT отсутствует, следует отметить, что SMIv2 фактически не задаёт никаких значений по умолчанию. Авторы MIB должны знать, что ясная подсказка предоставляется приложениям только при наличии предложения DISPLAY-HINT.
4.6.4. Определения концептуальных таблиц
Разделы 7.1.12 и 7.1.12.1 RFC 2578 задают правила определения концептуальных таблиц, а разделы 7.7, 7.8 и 7.8.1 RFC 2578 задают правила индексирования концептуальных таблиц. К таким определениям применяются следующие рекомендации:
- Для концептуальных строк:
- Если строка является расширением строки в некоторой другой таблице, то ДОЛЖНО (MUST) использоваться предложение AUGMENTS, если отношение является отношением «один к одному», и ДОЛЖНО (MUST) использоваться предложение INDEX, если отношение является разреженным. В последнем случае предложение INDEX СЛЕДУЕТ (SHOULD) сделать идентичным предложению исходной таблицы.
- Если строка является элементом таблицы расширения — то есть если нескольким экземплярам строк соответствует один экземпляр строки в некоторой другой таблице, — то ДОЛЖНО (MUST) использоваться предложение INDEX, а первыми упомянутыми элементами СЛЕДУЕТ (SHOULD) сделать индексы той другой таблицы, перечисленные в том же порядке.
- Если в предложении INDEX присутствуют объекты, внешние по отношению к строке, то предложение DESCRIPTION концептуальной строки ДОЛЖНО (MUST) задавать, как эти объекты используются при идентификации экземпляров её столбцовых объектов, и, в частности, ДОЛЖНО (MUST) задавать, для каких значений этих индексных объектов концептуальная строка может существовать.
- Использование ключевого слова IMPLIED НЕ СЛЕДУЕТ (NOT RECOMMENDED) для любого индексного объекта, который может появиться в предложении INDEX таблицы расширения. Поскольку это ключевое слово может быть связано только с последним объектом в предложении INDEX, оно не может быть связано с тем же индексным объектом в первичной таблице и таблице расширения. Это приведёт к различию порядка сортировки в первичной таблице и любых таблицах расширения. Как следствие, реализация не сможет повторно использовать код индексирования из первичной таблицы в таблицах расширения, а структуры данных, предназначенные для расширения, на деле, возможно, придётся дублировать. Разработчикам, испытывающим желание использовать IMPLIED, следует учитывать, что получающийся порядок сортировки редко соответствует ожиданиям пользователей, особенно для строк, включающих как прописные, так и строчные буквы, и он не учитывает язык или локаль пользователя.
Heard Лучшая современная практика [Страница 21]
RFC 4181 Guidelines for MIB Documents Сентябрь 2005
- Если поддерживается динамическое создание и/или удаление строк приложениями управления, то:
- СЛЕДУЕТ (SHOULD) иметься один столбцовый объект со значением SYNTAX RowStatus [RFC2579] и значением MAX-ACCESS read-create. Этот объект называется столбцом состояния концептуальной строки. Все остальные столбцовые объекты ДОЛЖНЫ (MUST) иметь значение MAX-ACCESS read-create, read-only, accessible-for-notify или not-accessible; значение MAX-ACCESS read-write не допускается.
- Либо ДОЛЖЕН (MUST) быть один столбцовый объект со значением SYNTAX StorageType [RFC2579] и значением MAX-ACCESS read-create, либо предложение DESCRIPTION объекта строки (элемента таблицы) ДОЛЖНО (MUST) задавать, что происходит с динамически созданными строками после перезапуска агента.
- Если сам агент также может создавать и/или удалять строки, то условия, при которых это может происходить, ДОЛЖНЫ (MUST) быть ясно документированы в предложении DESCRIPTION объекта строки.
- Для концептуальных строк, включающих столбец состояния:
- Предложение DESCRIPTION столбца состояния ДОЛЖНО (MUST) задавать, какие столбцовые объекты (если таковые имеются) должны быть установлены в допустимые значения до того, как строка может быть активирована. Если какие-либо объекты в каскадных таблицах должны быть заполнены связанными данными до того, как строка может быть активирована, то это также ДОЛЖНО (MUST) быть задано. - Предложение DESCRIPTION столбца состояния ДОЛЖНО (MUST) указывать,
возможно ли изменять другие столбцы в той же
концептуальной строке, когда значение состояния равно active(1).
Обратите внимание, что во многих случаях будет возможно изменять
некоторые доступные для записи столбцы, когда строка активна, но не
другие. В таких случаях предложение DESCRIPTION для каждого доступного
для записи столбца СЛЕДУЕТ (SHOULD) указывать, можно ли изменять этот
столбец, когда строка активна, а предложение DESCRIPTION для столбца
состояния СЛЕДУЕТ (SHOULD) указывать, что возможность изменения других
столбцов, когда значение состояния равно active(1), определена в
предложениях DESCRIPTION для этих столбцов (а не перечислять изменяемые
столбцы по отдельности).
Heard Best Current Practice [Страница 22]
RFC 4181 Guidelines for MIB Documents September 2005
- Для концептуальных строк, включающих столбец StorageType:
- Предложение DESCRIPTION столбца StorageType ДОЛЖНО (MUST) указывать,
какие столбчатые объекты read-write или read-create в строках
permanent(4) агент должен, как минимум, допускать к записи.
Обратите внимание, что RFC 2578, раздел 7.8, требует, чтобы время жизни
экземпляра концептуальной строки, которая AUGMENTS базовую строку, было тем
же, что и у соответствующего экземпляра базовой строки. Отсюда следует, что
в дополняющей строке нет необходимости в столбце RowStatus или StorageType,
если такой столбец уже присутствует в базовой строке.
Полные требования к TC RowStatus и StorageType приведены в RFC 2579, в
предложениях DESCRIPTION для этих TC.
4.6.5. Значения OID, назначенные объектам
В RFC 2578, разделе 7.10, определены правила назначения значений OBJECT
IDENTIFIER (OID) определениям OBJECT-TYPE. В частности:
- Концептуальная таблица ДОЛЖНА (MUST) иметь ровно один подчинённый объект,
которым является концептуальная строка. OID, назначенный концептуальной
строке, ДОЛЖЕН (MUST) быть получен добавлением субидентификатора "1" к
OID, назначенному концептуальной таблице.
- Концептуальная строка имеет столько подчинённых объектов, сколько в строке
столбцов; ДОЛЖЕН (MUST) быть как минимум один. OID, назначенный каждому
столбчатому объекту, ДОЛЖЕН (MUST) быть получен добавлением ненулевого
субидентификатора, уникального в пределах строки, к OID, назначенному
концептуальной строке.
- Столбчатый или скалярный объект НЕ ДОЛЖЕН (MUST NOT) иметь каких-либо
подчинённых объектов.
- Последний субидентификатор OID, назначенного любому объекту (будь то
таблица, строка, столбец или скаляр), НЕ ДОЛЖЕН (MUST NOT) быть равен
нулю. Обратите внимание, что субидентификаторы промежуточных узлов МОГУТ
(MAY) быть равны нулю.
- OID, назначенный определению объекта, НЕ ДОЛЖЕН (MUST NOT) также
назначаться другому определению, приводящему к регистрации OID. В RFC
2578, разделе 3.6, перечислены конструкции, создающие регистрации OID.
Хотя это специально не требуется SMI, принято (и настоятельно
СЛЕДУЕТ (RECOMMENDED)), чтобы определения объектов не регистрировались
ниже определений групп, утверждений соответствия, утверждений возможностей
или определений уведомлений. Также принято (и настоятельно
СЛЕДУЕТ (RECOMMENDED)), чтобы определения групп, утверждения
соответствия,
Heard Best Current Practice [Страница 23]
RFC 4181 Guidelines for MIB Documents September 2005
утверждения возможностей и определения уведомлений не регистрировались ниже
определений объектов. См. в Приложении D схему назначения OID, использовать
которую СЛЕДУЕТ (RECOMMENDED).
4.6.6. Ограничения длины OID и индексирование таблиц
Как определено в RFC 2578, разделе 3.5, все OID ограничены 128
субидентификаторами. Хотя это вряд ли вызовет проблемы при административных
назначениях, это накладывает некоторые ограничения на индексирование таблиц.
Это верно потому, что ограничение длины также применяется к OID экземпляров
объектов, а они состоят из конкатенации «базового» OID, назначенного в
определении объекта, и компонентов индекса. Когда таблица имеет несколько
индексов таких типов, как OCTET STRING или OBJECT IDENTIFIER, которые
разрешаются в несколько субидентификаторов, предел в 128 субидентификаторов
может быть быстро достигнут.
Несмотря на неудобство, предел в 128 субидентификаторов не является чем-то,
что можно игнорировать. Помимо того, что он устанавливается SMI, он также
устанавливается SNMP (см. последний абзац раздела 4.1 RFC 3416 [RFC3416]).
Отсюда следует, что любая таблица с достаточным числом компонентов
индексирования, чтобы нарушить этот предел, не может быть прочитана или
записана с использованием SNMP и поэтому непригодна к использованию.
Следовательно, при проектировании таблицы ДОЛЖЕН (MUST) учитываться предел в
128 субидентификаторов. СЛЕДУЕТ (RECOMMENDED), чтобы все документы MIB
явно указывали любые ограничения на длины компонентов индекса, которые
программное обеспечение управления должно соблюдать. Это может быть сделано
либо включением ограничений SIZE для компонентов индекса, либо указанием
применимых ограничений в предложении DESCRIPTION концептуальной строки или в
окружающей документации.
4.7. Определения уведомлений
В RFC 2578, разделе 8, определены правила для определений уведомлений.
В частности:
- Недоступные объекты НЕ ДОЛЖНЫ (MUST NOT) присутствовать в предложении
OBJECTS.
- Для каждого типа объекта, упомянутого в предложении OBJECTS, предложение
DESCRIPTION ДОЛЖНО (MUST) указывать, какой экземпляр объекта должен
присутствовать в передаваемом уведомлении, и ДОЛЖНО (MUST) указывать
передаваемую информацию/смысл.
- Значение OBJECT IDENTIFIER (OID), назначенное каждому типу уведомления,
ДОЛЖНО (MUST) иметь предпоследний субидентификатор, равный нулю, чтобы
было возможно преобразовать определение уведомления SMIv2 в определение
ловушки SMIv1 и обратно без потери информации (см. раздел 2.1.2
[RFC3584]) и чтобы цепочка многоязычных прокси могла преобразовать
ловушку SNMPv2 в ловушку SNMPv1 и обратно без потери информации (см.
раздел 3 [RFC3584]). Кроме того,
Heard Best Current Practice [Страница 24]
RFC 4181 Guidelines for MIB Documents September 2005
OID, назначенный определению уведомления, НЕ ДОЛЖЕН (MUST NOT) также
назначаться другому определению, приводящему к регистрации OID. В RFC
2578, разделе 3.6, перечислены конструкции, создающие регистрации OID.
Хотя это специально не требуется SMI, принято (и настоятельно
СЛЕДУЕТ (RECOMMENDED)), чтобы определения уведомлений не
регистрировались ниже определений групп, утверждений соответствия,
утверждений возможностей или определений объектов (последнее особенно
неразумно, поскольку может привести к тому, что экземпляр объекта и
определение уведомления будут совместно использовать один и тот же OID).
Также принято (и настоятельно СЛЕДУЕТ (RECOMMENDED)), чтобы OID,
назначенные типам уведомлений, были листовыми OID (то есть чтобы не было
регистраций OID, подчинённых определению уведомления). См. в Приложении D
схему назначения OID, использовать которую СЛЕДУЕТ (RECOMMENDED).
Во многих случаях уведомления будут запускаться внешними событиями, и иногда
эти внешние события смогут происходить с настолько высокой частотой, что
отправка уведомления для каждого случая перегрузит сеть. В таких случаях
ДОЛЖЕН (MUST) быть предусмотрен механизм ограничения частоты, с которой
уведомление может генерироваться. Обычный метод состоит в требовании, чтобы
генератор уведомлений использовал ограничение частоты — то есть в требовании,
чтобы он генерировал не более одного уведомления для каждого источника
события в любом заданном интервале времени длительностью T. Период
ограничения частоты T МОЖЕТ (MAY) быть настраиваемым, в таком случае он
указывается в объекте MIB, или он МОЖЕТ (MAY) быть фиксированным, в таком
случае он указывается в определении уведомления. Примеры метода
фиксированного интервала времени можно найти в SNMP-REPEATER-MIB [RFC2108] и
в ENTITY-MIB [RFC4133].
4.8. Утверждения соответствия
В RFC 2580, разделах 3, 4 и 5, определены правила для групп соответствия и
утверждений соответствия. В частности:
- Каждый объект со значением MAX-ACCESS, отличным от "not-accessible",
ДОЛЖЕН (MUST) содержаться по крайней мере в одной группе объектов.
- Каждое уведомление ДОЛЖНО (MUST) содержаться по крайней мере в одной
группе уведомлений.
- Для каждого «стандартного» модуля MIB ДОЛЖНО (MUST) быть определено по
крайней мере одно утверждение соответствия. Оно может находиться либо в
этом модуле MIB, либо в сопутствующем модуле MIB.
При написании утверждений соответствия есть несколько моментов, которые
легко упустить:
Heard Best Current Practice [Страница 25]
RFC 4181 Guidelines for MIB Documents September 2005
- Группа объектов или группа уведомлений, которая не упомянута ни в
предложении MANDATORY-GROUPS, ни в каком-либо предложении GROUP утверждения
MODULE-COMPLIANCE, является безусловно необязательной относительно этого
утверждения соответствия. Альтернативный способ указать, что группа
объектов или группа уведомлений необязательна, — упомянуть её в
предложении GROUP, предложение DESCRIPTION которого указывает, что группа
необязательна. Последний метод СЛЕДУЕТ (RECOMMENDED) применять (для
необязательных групп, относящихся к утверждению соответствия), чтобы было
ясно, что необязательный статус предусмотрен намеренно, а не является
результатом упущения.
- Если имеются какие-либо объекты со значением MAX-ACCESS read-write или
read-create, для которых нет предложения OBJECT, указывающего MIN-ACCESS
read-only, то реализации должны поддерживать доступ на запись к этим
объектам, чтобы соответствовать этому утверждению MODULE-COMPLIANCE. Этот
факт иногда застаёт авторов модулей MIB врасплох. Столкнувшись с такими
случаями, рецензентам СЛЕДУЕТ (SHOULD) проверить, что именно это авторы
намеревались указать, поскольку часто это не так.
- С другой стороны, авторам модулей MIB следует знать, что, хотя утверждение
соответствия только для чтения достаточно для поддержки совместимых
приложений мониторинга, оно недостаточно для поддержки совместимых
приложений конфигурирования. Метод, обычно используемый в модулях MIB,
предназначенных для поддержки и мониторинга, и конфигурирования, состоит
в предоставлении как утверждения соответствия только для чтения, так и
полного утверждения соответствия. Хороший пример приводится в
DIFFSERV-MIB [RFC3289]. Авторам СЛЕДУЕТ (SHOULD) рассмотреть использование
этого метода, когда он применим.
Иногда авторы модулей MIB захотят указать, что соответствующая реализация
должна поддерживать только подмножество значений, допускаемых предложением
SYNTAX объекта. Для доступных объектов это может быть сделано либо указанием
требуемых значений в предложении DESCRIPTION объекта, либо предоставлением
предложения OBJECT с уточнённым SYNTAX в утверждении соответствия. Последний
метод СЛЕДУЕТ (RECOMMENDED) применять в большинстве случаев и ДОЛЖЕН
(REQUIRED) применяться, если имеется несколько утверждений соответствия с
требуемыми разными подмножествами значений. DIFFSERV-MIB [RFC3289]
иллюстрирует этот момент. Утверждение diffServMIBFullCompliance содержит
следующее предложение OBJECT. (См. раздел 4.8.1, «Примечание относительно
этих примеров и RFC 2578».)
OBJECT diffServDataPathStatus
SYNTAX RowStatus { active(1) }
WRITE-SYNTAX RowStatus { createAndGo(4), destroy(6) }
DESCRIPTION
"Support for createAndWait and notInService is not required."
Heard Best Current Practice [Страница 26]
RFC 4181 Guidelines for MIB Documents September 2005
тогда как утверждение diffServMIBReadOnlyCompliance содержит следующее:
OBJECT diffServDataPathStatus
SYNTAX RowStatus { active(1) }
MIN-ACCESS read-only
DESCRIPTION
"Write access is not required, and active is the only status that
needs to be supported."
Нельзя сделать это для недоступных объектов индекса, поскольку они не могут
присутствовать в группах объектов и не могут упоминаться в предложениях
OBJECT. Однако существуют ситуации, в которых может быть желательно указать,
что реализация обязана поддерживать только подмножество возможных значений
некоторого индекса в таблице read-create. В таких случаях требования ДОЛЖНЫ
(MUST) быть указаны либо в предложении DESCRIPTION объекта индекса
(СЛЕДУЕТ (RECOMMENDED), если имеется только одно подмножество значений),
либо в предложении DESCRIPTION утверждения MODULE-COMPLIANCE (ДОЛЖНО
(REQUIRED) быть указано здесь, если подмножество значений уникально для
утверждения соответствия).Во многих случаях модуль MIB всегда реализуется совместно с одним или несколькими другими модулями MIB. Этот факт ДОЛЖЕН (REQUIRED) быть отмечен в сопроводительной документации (см. раздел 3.2 выше), а также СЛЕДУЕТ (SHOULD) отметить его в соответствующих утверждениях соответствия. В случаях, когда конкретное утверждение соответствия, например, в модуле MIB A требует полной реализации некоторого другого модуля MIB B, РЕКОМЕНДУЕМЫЙ (RECOMMENDED) подход состоит в том, чтобы включить утверждение об этом в клаузу DESCRIPTION утверждения (утверждений) соответствия в модуле MIB A. Однако также возможно, что модуль MIB A может иметь требования, отличающиеся от требований, выраженных каким-либо утверждением соответствия модуля B, — например, модуль A может не требовать ни одной из безусловно обязательных групп объектов из модуля B, но требовать обязательной реализации группы объектов из модуля B, которая является обязательной лишь при определённых условиях относительно утверждения (утверждений) соответствия в модуле B. В таких случаях РЕКОМЕНДУЕМЫЙ (RECOMMENDED) подход состоит в том, чтобы утверждение (утверждения) соответствия в модуле A формально задавало требования относительно модуля B посредством надлежащих клауз MODULE, MANDATORY-GROUPS, GROUP и OBJECT. Примером служат утверждения соответствия в DIFFSERV-MIB [RFC3289], в которых ifCounterDiscontinuityGroup из IF-MIB [RFC2863] указан как обязательная группа. Эта группа недостаточна для выполнения какого-либо утверждения соответствия IF-MIB и является условно обязательной в текущем утверждении соответствия IF-MIB ifCompliance3.
4.8.1. Примечание относительно этих примеров и RFC 2578
Существовали разногласия относительно того, разрешены ли уточнения синтаксиса, ограничивающие перечисления (раздел 9 RFC 2578), с TC, как показано в примерах выше, либо они разрешены только с базовыми типами INTEGER и BITS, как следует из строгого прочтения RFC 2578. Приблизительный консенсус редакторов документов SMIv2 и нынешнего сообщества рецензентов MIB состоит в том, что они должны быть разрешены с TC. Авторам модулей MIB следует учитывать, что некоторые компиляторы MIB придерживаются строгого прочтения RFC 2578 и требуют заменять TC его базовым типом (INTEGER или BITS), когда перечисления уточняются. Такое использование является законным и встречается в некоторых старых модулях MIB, таких как IF-MIB [RFC2863].
4.9. Редакции модулей MIB
Раздел 10 RFC 2578 задаёт общие правила, применяемые всякий раз при пересмотре модуля MIB. В частности:
- Вызов MODULE-IDENTITY ДОЛЖЕН (MUST) быть обновлён, чтобы включать сведения о редакции. В частности, значение клаузы LAST-UPDATED ДОЛЖНО (MUST) быть установлено равным времени редакции, ДОЛЖНА (MUST) быть добавлена клауза REVISION с тем же временем UTC и связанная с ней клауза DESCRIPTION, описывающая изменения, а вся устаревшая информация в существующих клаузах DESCRIPTION, ORGANIZATION и CONTACT-INFO ДОЛЖНА (MUST) быть заменена актуальной информацией. Дополнительные требования, применимые к модулям MIB, находящимся под контролем изменений IETF, см. в разделе 4.5 выше.
- С другой стороны, имя модуля НЕ ДОЛЖНО (MUST NOT) изменяться (кроме исправления типографических ошибок), существующие определения (даже устаревшие) НЕ ДОЛЖНЫ (MUST NOT) удаляться из модуля MIB, а дескрипторы и значения OBJECT IDENTIFIER, связанные с существующими определениями, НЕ ДОЛЖНЫ (MUST NOT) изменяться или назначаться повторно.
Важно отметить, что цель запрета некоторых видов изменений — обеспечить совместимость пересмотренного модуля MIB с развёрнутыми реализациями, основанными на предыдущих версиях модуля. У этого требования обратной совместимости есть два различных аспекта. Один — совместимость «по проводу» реализаций агента и менеджера, основанных на разных редакциях модуля MIB. Другой — совместимость «при компиляции» с модулями MIB, импортирующими определения из пересмотренного модуля MIB. Правила, запрещающие изменять или повторно назначать значения OBJECT IDENTIFIER, необходимы для обеспечения совместимости «по проводу»; правила против изменения имён модулей или дескрипторов либо удаления устаревших определений необходимы для обеспечения совместимости при компиляции.
Раздел 10.2 RFC 2578 задаёт правила, применимые к редакциям определений объектов. Следующие рекомендации исправляют некоторые ошибки в этих правилах и вносят некоторые уточнения:
- Пункт (1) разрешает изменять метки именованных чисел и именованных битов в клаузах SYNTAX типа перечислимого INTEGER или BITS. Это может нарушить совместимость при компиляции, поскольку эти метки могут использоваться клаузами DEFVAL в модулях, импортирующих определения затронутых объектов. Поэтому метки именованных чисел и именованных битов НЕ ДОЛЖНЫ (MUST NOT) изменяться при пересмотре модулей MIB IETF (кроме исправления типографических ошибок), и им НЕ СЛЕДУЕТ (SHOULD NOT) изменяться при пересмотре корпоративных модулей MIB.
- Хотя это специально не разрешено пунктами (1)–(8), обычно считается приемлемым добавлять ограничения диапазона к клаузе SYNTAX объекта с целочисленным значением при условии, что ограничения лишь делают явными некоторые ограничения значений, неявно содержащиеся в определении объекта. Наиболее распространённый пример — вспомогательный объект с SYNTAX INTEGER или Integer32 без ограничения диапазона. Поскольку вспомогательному объекту не разрешено принимать отрицательные значения, добавление ограничения диапазона (0..2147483647) никоим образом не может привести к какому-либо изменению «по проводу» и не вызовет проблем совместимости при компиляции с корректно написанным модулем MIB. Такое изменение СЛЕДУЕТ (SHOULD) рассматривать рецензенту как редакционное, а не как семантическое изменение. Аналогично, удаление ограничения диапазона или размера из определения объекта, когда это ограничение диапазона или размера обеспечивается базовым типом данных, СЛЕДУЕТ (SHOULD) рассматривать рецензенту как редакционное изменение.
Раздел 10.3 RFC 2578 задаёт правила, применимые к редакциям определений уведомлений. Уточнения или исправления не требуются.
Раздел 5 RFC 2579 задаёт правила, применимые к редакциям определений текстовых соглашений. Следующая рекомендация исправляет ошибку в этих правилах:
- Пункт (1) разрешает изменять метки именованных чисел и именованных битов в клаузах SYNTAX типа перечислимого INTEGER или BITS. Это может нарушить совместимость при компиляции, поскольку эти метки могут использоваться клаузами DEFVAL в модулях, импортирующих определения затронутых TC. Поэтому метки именованных чисел и именованных битов НЕ ДОЛЖНЫ (MUST NOT) изменяться при пересмотре модулей MIB IETF (кроме исправления типографических ошибок), и им НЕ СЛЕДУЕТ (SHOULD NOT) изменяться при пересмотре корпоративных модулей MIB.
Раздел 7.1 RFC 2580 задаёт правила, применимые к редакциям групп соответствия. Два пункт стоит повторить:
- Объекты и уведомления НЕ ДОЛЖНЫ (MUST NOT) добавляться в существующую группу объектов или группу уведомлений либо удаляться из неё. Это может вызвать сбой компиляции или, что хуже, незаметное изменение смысла утверждения соответствия либо утверждения возможностей, ссылающегося на эту группу.
- Статус группы соответствия не зависит от статуса её членов. Таким образом, текущая группа МОЖЕТ (MAY) ссылаться на устаревшие объекты или уведомления. В некоторых случаях это может быть желательным: например, набор широко развёрнутых объектов или уведомлений может быть признан устаревшим при их замене более актуальным набором определений, но содержащие их группы соответствия могут оставаться текущими, чтобы поощрять продолжение реализации устаревших объектов и уведомлений.
Раздел 7.2 RFC 2580 задаёт правила, применимые к редакциям утверждений соответствия. Следующие рекомендации исправляют упущение в этих правилах и подчёркивают один важный момент:
- RFC 2580 следовало бы (но он этого не делает) рекомендовать добавление в утверждение соответствия клаузы OBJECT, задающей поддержку исходного набора значений, когда перечислимый объект INTEGER или объект BITS, на который ссылается утверждение соответствия, получает добавленные перечисления или именованные биты, при условии, что такая клауза ещё отсутствует и что действующее значение MIN-ACCESS равно read-write или read-create. Это необходимо, чтобы избежать незаметного изменения смысла утверждения соответствия. Авторам и рецензентам модулей MIB СЛЕДУЕТ (SHOULD) следить за этим, чтобы такие клаузы OBJECT добавлялись, когда это необходимо. Обратите внимание, что это не всегда возможно сделать, поскольку затронутые утверждения соответствия могут находиться в модулях, отличных от того, который содержит пересмотренное определение (пересмотренные определения).
- Статус утверждения соответствия не зависит от статуса его членов. Таким образом, текущее утверждение соответствия МОЖЕТ (MAY) ссылаться на устаревшие группы объектов или группы уведомлений. В некоторых случаях это может быть желательным: например, набор широко развёрнутых групп объектов или уведомлений может быть признан устаревшим при их замене более актуальным набором определений, но утверждения соответствия, ссылающиеся на них, могут оставаться текущими, чтобы поощрять продолжение реализации устаревших групп.
Раздел 7.3 RFC 2580 задаёт правила, применимые к редакциям утверждений возможностей. Следующая рекомендация исправляет упущение в этих правилах:
- RFC 2580 следовало бы (но он этого не делает) рекомендовать добавление в утверждение возможностей клауз VARIATION, задающих поддержку исходного набора значений, когда перечислимым объектам INTEGER или объектам BITS, на которые ссылается утверждение возможностей, добавляются перечисления, при условии, что такие клаузы ещё отсутствуют. Это необходимо, чтобы избежать незаметного изменения смысла утверждения возможностей.
В некоторых исключительных ситуациях стоимость строгого соблюдения правил SMIv2, регулирующих редакции модулей MIB, может превышать выгоду. В таких случаях от правил можно отказаться, но, когда это делается, как изменение, так и его обоснование ДОЛЖНЫ (MUST) быть тщательно документированы. Один пример приведён в разделе 3.1.5 RFC 2863, где документируется семантическое изменение, внесённое в ifIndex при переходе от MIB-II [RFC1213] к IF-MIB [RFC2863], и даётся подробное обоснование этого изменения. Другой пример приведён в клаузе REVISION SONET-MIB [RFC2558], где документируется повышение MAX-ACCESS нескольких объектов до read-write при добавлении MIN-ACCESS read-only для совместимости с предыдущей версией [RFC1595].
Авторам и рецензентам может быть полезно использовать инструменты, способные перечислять различия между двумя редакциями модуля MIB. Дополнительную информацию см. по адресу http://www.ops.ietf.org/mib-review-tools.html.
5. Благодарности
Большая часть материала об использовании типов данных была основана на материалах, предоставленных Бертом Вейнненом при содействии Кейта Макклогри, Дэвида Т. Перкинса и Юргена Шёнвельдера. Значительная часть другого материала об использовании SMIv2 была взята из неопубликованного руководства для авторов и рецензентов MIB Юргена Шёнвельдера. Некоторые рекомендации в этих руководящих принципах основаны на материале из онлайн-списка исправлений SMIv2 по адресу http://www.ibr.cs.tu-bs.de/ietf/smi-errata/. Благодарности Франку Штраусу и Юргену Шёнвельдеру за ведение этого списка, а также участникам, предоставившим для него материал. Наконец, выражается благодарность следующим лицам, чьи комментарии к предыдущим версиям этой записки содержали много ценных предложений по дополнениям, уточнениям и исправлениям: Andy Bierman, Bob Braden, Michelle Cotton, David Harrington, Harrie Hazewinkel, Dinakaran Joseph, Michael Kirkham, Keith McCloghrie, David T. Perkins, Randy Presuhn, Dan Romascanu, Juergen Schoenwaelder, Frank Strauss, Dave Thaler и Bert Wijnen.
6. Соображения безопасности
Реализация и развёртывание модуля MIB в системе могут привести к рискам безопасности, которые иначе не существовали бы. Авторам и рецензентам документов, определяющих модули MIB, важно обеспечить полное соответствие этих документов руководящим принципам по адресу http://www.ops.ietf.org/mib-security.html, чтобы все такие риски были надлежащим образом раскрыты.
7. Соображения IANA
Этот документ затрагивает IANA постольку, поскольку описывает, что должно присутствовать в разделе «Соображения IANA» документа MIB, но не требует, чтобы IANA обновляла какой-либо существующий реестр или создавала какой-либо новый реестр.
Приложение A: Контрольный список проверки MIBЦель обзора MIB состоит в проверке модуля MIB как на техническую корректность, так и на соответствие требованиям IETF к документации. Следующий контрольный перечень может быть полезен при рассмотрении проекта документа:
1.) Шаблонный текст I-D — убедитесь, что проект содержит требуемый шаблонный текст Internet-Draft (см. http://www.ietf.org/ietf/1id-guidelines.txt), включая соответствующее положение, разрешающее публикацию в качестве RFC, и что шаблонный текст I-D не содержит ссылок или номеров разделов.
2.) Аннотация — убедитесь, что аннотация не содержит ссылок, не имеет номера раздела и что её содержание соответствует рекомендациям в http://www.ietf.org/ietf/1id-guidelines.txt.
3.) Шаблонный текст MIB — убедитесь, что проект содержит последнюю утверждённую формулировку о SNMP Network Management Framework с веб-сайта области OPS (http://www.ops.ietf.org/mib-boilerplate.html).
4.) Раздел «Соображения безопасности» — убедитесь, что проект использует последний утверждённый шаблон с веб-сайта области OPS (http://www.ops.ietf.org/mib-security.html) и что приведённые там рекомендации соблюдены.
5.) Раздел «Соображения IANA» — этот раздел должен всегда присутствовать. Если проект не требует действий со стороны IANA, убедитесь, что это явно отмечено. Если проект требует назначения значений OID, убедитесь, что раздел «Соображения IANA» содержит информацию, указанную в разделе 3.5 настоящих рекомендаций. Если проект содержит начальную версию модуля, сопровождаемого IANA, убедитесь, что вызов MODULE-IDENTITY содержит инструкции по сопровождению, соответствующие требованиям RFC 2434. В последнем случае раздел «Соображения IANA», который будет включён в RFC, ДОЛЖЕН (MUST) содержать указатель на фактический модуль, сопровождаемый IANA.
6.) Ссылки — убедитесь, что ссылки надлежащим образом разделены на нормативные и информационные, что RFC 2119 включён как нормативная ссылка, если в документе используется определённая в нём терминология, что присутствуют все ссылки, требуемые шаблонным текстом, что все модули MIB, содержащие импортируемые элементы, процитированы как нормативные ссылки и что все цитаты указывают на наиболее актуальные RFC, если только нет веской причины поступить иначе (например, допустимо включить информационную ссылку на предыдущую версию спецификации, чтобы помочь объяснить функцию, включённую для обратной совместимости).
Heard Лучшая современная практика [Страница 33]
RFC 4181 Рекомендации для документов MIB Сентябрь 2005
7.) Уведомления об авторских правах — убедитесь, что проект содержит сокращённое уведомление об авторских правах в клаузе DESCRIPTION каждого вызова MODULE-IDENTITY и что в конце документа он содержит полное уведомление об авторских правах и отказ от ответственности, указанные в разделах 5.4 и 5.5 RFC 3978. Убедитесь, что во всех датах авторских прав указан правильный год.
8.) Уведомление об IPR — если проект не содержит дословной копии уведомления об IPR, указанного в разделе 5 RFC 3979, рекомендуйте включить уведомление об IPR.
9.) Прочие вопросы — проверьте наличие любых вопросов, упомянутых в http://www.ietf.org/ID-Checklist.html, которые не охвачены в других местах.
10.) Техническое содержание — проверьте фактическое техническое содержание на соответствие рекомендациям этого документа. При проверке синтаксических ошибок рекомендуется использовать компилятор MIB; дополнительную информацию см. в http://www.ops.ietf.org/mib-review-tools.html. Однако проверка правильности синтаксиса — лишь часть работы. Не менее важно фактически прочитать документ MIB с точки зрения потенциального реализатора. Особенно важно проверить, что клаузы DESCRIPTION достаточно ясны и недвусмысленны, чтобы можно было создать совместимые реализации.
Приложение B: Часто используемые текстовые соглашения
Следующие TC определены в SNMPv2-TC [RFC2579]:
DisplayString OCTET STRING (SIZE (0..255))
PhysAddress OCTET STRING
MacAddress OCTET STRING (SIZE (6))
TruthValue enumerated INTEGER
TestAndIncr INTEGER (0..2147483647)
AutonomousType OBJECT IDENTIFIER
VariablePointer OBJECT IDENTIFIER
RowPointer OBJECT IDENTIFIER
RowStatus enumerated INTEGER
TimeStamp TimeTicks
TimeInterval INTEGER (0..2147483647)
DateAndTime OCTET STRING (SIZE (8 | 11))
StorageType enumerated INTEGER
TDomain OBJECT IDENTIFIER
TAddress OCTET STRING (SIZE (1..255))
Примечание 1. InstancePointer устарел и НЕ ДОЛЖЕН (MUST NOT) использоваться.
Примечание 2. DisplayString не поддерживает интернационализированный текст. Он
НЕ ДОЛЖЕН (MUST NOT) использоваться для объектов, которые должны содержать
Heard Лучшая современная практика [Страница 34]
RFC 4181 Рекомендации для документов MIB Сентябрь 2005
интернационализированный текст (что всегда имеет место, если
объект предназначен для использования людьми [RFC2277]). Разработчикам
СЛЕДУЕТ (SHOULD) рассмотреть использование SnmpAdminString, Utf8String или
LongUtf8String для таких объектов.
Примечание 3. TDomain и TAddress НЕ СЛЕДУЕТ (SHOULD NOT) использовать в новых модулях MIB.
Вместо них СЛЕДУЕТ (SHOULD) использовать TC TransportDomain, TransportAddressType и
TransportAddress (определённые в TRANSPORT-ADDRESS-MIB
[RFC3419]).
Следующий TC определён в SNMP-FRAMEWORK-MIB [RFC3411]:
SnmpAdminString OCTET STRING (SIZE (0..255))
Следующие TC определены в SYSAPPL-MIB [RFC2287]:
Utf8String OCTET STRING (SIZE (0..255))
LongUtf8String OCTET STRING (SIZE (0..1024))
Следующие TC определены в INET-ADDRESS-MIB [RFC4001]:
InetAddressType enumerated INTEGER
InetAddress OCTET STRING (SIZE (0..255))
InetAddressPrefixLength Unsigned32 (0..2040)
InetPortNumber Unsigned32 (0..65535))
InetAutonomousSystemNumber Unsigned32
InetScopeType enumerated INTEGER
InetZoneIndex Unsigned32
InetVersion enumerated INTEGER
Следующие TC определены в TRANSPORT-ADDRESS-MIB [RFC3419]:
TransportDomain OBJECT IDENTIFIER
TransportAddressType enumerated INTEGER
TransportAddress OCTET STRING (SIZE (0..255))
Следующий TC определён в RMON2-MIB [RFC2021]:
ZeroBasedCounter32 Gauge32
Следующие TC определены в HCNUM-TC [RFC2856]:
ZeroBasedCounter64 Counter64
CounterBasedGauge64 Counter64
Следующие TC определены в IF-MIB [RFC2863]:
InterfaceIndex Integer32 (1..2147483647)
Heard Лучшая современная практика [Страница 35]
RFC 4181 Рекомендации для документов MIB Сентябрь 2005
InterfaceIndexOrZero Integer32 (0..2147483647)
Следующие TC определены в ENTITY-MIB [RFC4133]:
PhysicalIndex Integer32 (1..2147483647)
PhysicalIndexOrZero Integer32 (0..2147483647)
Следующие TC определены в PerfHist-TC-MIB [RFC3593]:
PerfCurrentCount Gauge32
PerfIntervalCount Gauge32
PerfTotalCount Gauge32
Следующие TC определены в HC-PerfHist-TC-MIB [RFC3705]:
HCPerfValidIntervals Integer32 (0..96)
HCPerfInvalidIntervals Integer32 (0..96)
HCPerfTimeElapsed Integer32 (0..86399)
HCPerfIntervalThreshold Unsigned32 (0..900)
HCPerfCurrentCount Counter64
HCPerfIntervalCount Counter64
HCPerfTotalCount Counter64
Приложение C: Предлагаемые соглашения об именовании
Авторы и рецензенты модулей IETF MIB нередко находили следующие соглашения об именовании полезными в прошлом, и авторам новых модулей IETF MIB настоятельно рекомендуется рассмотреть их соблюдение.
- Имя модуля следует оформлять как XXX-MIB (либо XXX-TC-MIB для модуля, содержащего только TC), где XXX — уникальный префикс (обычно полностью прописными буквами с дефисами в качестве разделителей), не используемый ни одним существующим модулем. Например, модуль для управления оптическими интерфейсами [RFC3591] использует префикс OPT-IF и имеет имя модуля OPT-IF-MIB.
- Дескриптор, связанный с вызовом MODULE-IDENTITY, следует оформлять как xxxMIB, xxxMib или xxxMibModule, где xxx — вариант XXX в смешанном регистре, начинающийся со строчной буквы и без дефисов. Например, OPT-IF-MIB использует префикс optIf, а дескриптор, связанный с его вызовом MODULE-IDENTITY, — optIfMibModule.
- Другие дескрипторы в модуле MIB следует начинать с того же префикса xxx. OPT-IF-MIB использует префикс optIf для всех дескрипторов.
Heard Лучшая современная практика [Страница 36]
RFC 4181 Рекомендации для документов MIB Сентябрь 2005
- Имена TC, специфичных для модуля MIB, и имена типов SEQUENCE, используемых в определениях концептуальных таблиц, следует начинать с префикса Xxx, совпадающего с xxx, но с начальной буквой, заменённой на прописную. OPT-IF-MIB использует префикс OptIf в именах TC и типов SEQUENCE.
- Дескриптор, связанный с концептуальной таблицей, следует оформлять как xxxZzzTable; дескриптор, связанный с соответствующей концептуальной строкой, — как xxxZzzEntry; имя связанного типа SEQUENCE — как XxxZzzEntry; а дескрипторы, связанные с подчинёнными столбцовыми объектами, — как xxxZzzSomeotherName. Пример из OPT-IF-MIB — таблица OTMn. Дескриптор объекта таблицы — optIfOTMnTable, дескриптор объекта строки — optIfOTMnEntry, имя связанного типа SEQUENCE — OptIfOTMnEntry, а дескрипторы столбцовых объектов — optIfOTMnOrder, optIfOTMnReduced, optIfOTMnBitRates, optIfOTMnInterfaceType, optIfOTMnTcmMax и optIfOTMnOpticalReach.
- При использовании сокращений их следует использовать последовательно. Непоследовательного использования, такого как
xxxYyyDestAddr
xxxZzzDstAddr
следует избегать.
Приложение D: Предлагаемая структура OID
Как отмечено в разделе 5.6 RFC 2578, обычной практикой является использование значения вызова MODULE-IDENTITY в качестве поддерева, в котором определяются другие значения OBJECT IDENTIFIER, назначенные в модуле. Это, разумеется, оставляет открытым вопрос о том, как OID назначаются в этом поддереве. Одна схема назначения, получившая признание — и СЛЕДУЕТ (RECOMMENDED) использовать её, если нет конкретной причины её не использовать, — заключается в наличии трёх отдельных ветвей непосредственно под значением MODULE-IDENTITY, предназначенных соответственно для определений уведомлений, определений объектов и определений соответствия, а также в дополнительном разделении ветви соответствия на отдельные подветви для утверждений о соответствии и групп объектов/уведомлений. Эта структура показана ниже; соглашения об именовании соответствуют изложенным в приложении C. Числа в скобках — это субидентификаторы, назначенные ветвям.
Heard Лучшая современная практика [Страница 37]
RFC 4181 Рекомендации для документов MIB Сентябрь 2005
xxxMIB
|
+-- xxxNotifications(0)
+-- xxxObjects(1)
+-- xxxConformance(2)
|
+-- xxxCompliances(1)
+-- xxxGroups(2)
При использовании этой схемы значения определений уведомлений назначаются непосредственно под узлом xxxNotifications. Это гарантирует, что каждый OID, назначенный определению уведомления, имеет предпоследний субидентификатор, равный нулю, что ТРЕБУЕТСЯ (REQUIRED) разделом 4.7 выше. Другие подветви могут иметь дополнительную подструктуру, но фактически не требуется никакой подструктуры сверх указанной в разделе 4.6.5 выше.
Один из примеров модуля MIB, назначения OID в котором следуют этой схеме, — POWER-ETHERNET-MIB [RFC3621].
Нормативные ссылки
[RFC2578] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case,
J., Rose, M., and S. Waldbusser, "Structure of
Management Information Version 2 (SMIv2)", STD 58, RFC
2578, April 1999.
[RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case,
J., Rose, M., and S. Waldbusser, "Textual Conventions
for SMIv2", STD 58, RFC 2579, April 1999.
[RFC2580] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case,
J., Rose, M., and S. Waldbusser, "Conformance Statements
for SMIv2", STD 58, RFC 2580, April 1999.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirements Levels", BCP 14, RFC 2119, March 1997.
[RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group
MIB", RFC 2863, June 2000.
[RFC2864] McCloghrie, K. and G. Hanson, "The Inverted Stack Table
Extension to the Interfaces Group MIB", RFC 2864, June
2000.
[RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 2434,
October 1998.
Heard Лучшая современная практика [Страница 38]
RFC 4181 Рекомендации для документов MIB Сентябрь 2005
[RFC3978] Bradner, S., "IETF Rights in Contributions", BCP 78, RFC
3978, March 2005.
[RFC3979] Bradner, S., "Intellectual Property Rights in IETF
Technology", BCP 79, RFC 3979, March 2005.
[RFC4001] Daniele, M., Haberman, B., Routhier, S., and J.
Schoenwaelder, "Textual Conventions for Internet Network
Addresses", RFC 4001, February 2005.
[RFC3593] Tesink, K., "Textual Conventions for MIB Modules Using
Performance History Based on 15 Minute Intervals", RFC
3593, September 2003.
[RFC3705] Ray, B. and R. Abbi, "High Capacity Textual Conventions
for MIB Modules Using Performance History Based on 15
Minute Intervals", RFC 3705, February 2004.
[RFC2021] Waldbusser, S., "Remote Network Monitoring Management
Information Base Version 2 using SMIv2", RFC 2021,
January 1997.
[RFC2856] Bierman, A., McCloghrie, K., and R. Presuhn, "Textual
Conventions for Additional High Capacity Data Types",
RFC 2856, June 2000.
[RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An
Architecture for Describing Simple Network Management
Protocol (SNMP) Management Frameworks", STD 62, RFC
3411, December 2002.
[RFC2287] Krupczak, C. and J. Saperia, "Definitions of
System-Level Managed Objects for Applications", RFC
2287, February 1998.
[RFC3418] Presuhn, R., Case, J., McCloghrie, K., Rose, M., and S.
Waldbusser, "Management Information Base (MIB) for the
Simple Network Management Protocol (SNMP)", STD 62, RFC
3418, December 2002.
[RFC3416] Presuhn, R., Case, J., McCloghrie, K., Rose, M., and S.
Waldbusser, "Protocol Operations for the Simple Network
Management Protocol (SNMP)", STD 62, RFC 3416, December
2002.
[RFC4133] Bierman, A. and K. McCloghrie, "Entity MIB (Version 3)",
RFC 4133, August 2005.
Heard Лучшая современная практика [Страница 39]
RFC 4181 Guidelines for MIB Documents September 2005
[RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
Languages", BCP 18, RFC 2277, January 1998.
[RFC3419] Daniele, M. and J. Schoenwaelder, "Textual Conventions
for Transport Addresses", RFC 3419, December 2002.
Информативные ссылки
[RFC1155] Rose, M. and K. McCloghrie, "Structure and
Identification of Management Information for
TCP/IP-based Internets", STD 16, RFC 1155, May 1990.
[RFC1212] Rose, M. and K. McCloghrie, "Concise MIB Definitions",
STD 16, RFC 1212, March 1991.
[RFC1215] Rose, M., "A Convention for Defining Traps for use with
the SNMP", RFC 1215, March 1991.
[RFC2223bis] Reynolds, J. and R. Braden, "Instructions to Request for
Comments (RFC) Authors", Work in Progress, August 2004.
[RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart,
"Introduction and Applicability Statements for
Internet-Standard Management Framework", RFC 3410,
December 2002.
[RFC2932] McCloghrie, K., Farinacci, D., and D. Thaler, "IPv4
Multicast Routing MIB", RFC 2932, October 2000.
[RFC1573] McCloghrie, K. and F. Kastenholz, "Evolution of the
Interfaces Group of MIB-II", RFC 1573, January 1994.
[RFC3621] Berger, A. and D. Romascanu, "Power Ethernet MIB", RFC
3621, December 2003.
[RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen,
"Coexistence between Version 1, Version 2, and Version 3
of the Internet-standard Network Management Framework",
BCP 74, RFC 3584, August 2003.
[RFC2108] de Graaf, K., Romascanu, D., McMaster, D., and K.
McCloghrie, "Definitions of Managed Objects for IEEE
802.3 Repeater Devices using SMIv2", RFC 2108, February
1997.
[RFC3289] Baker, F., Chan, K., and A. Smith, "Management
Information Base for the Differentiated Services
Architecture", RFC 3289, May 2002.
Heard Лучшая современная практика [Страница 40]
RFC 4181 Guidelines for MIB Documents September 2005
[RFC1213] McCloghrie, K. and M. Rose, "Management Information Base
for Network Management of TCP/IP-based internets - MIB-
II", STD 17, RFC 1213, March 1991.
[RFC1595] Brown, T. and K. Tesink, "Definitions of Managed Objects
for the SONET/SDH Interface Type", RFC 1595, March 1994.
[RFC2558] Tesink, K., "Definitions of Managed Objects for the
SONET/SDH Interface Type", RFC 2558, March 1999.
[RFC3591] Lam, H-K., Stewart, M., and A. Huynh, "Definitions of
Managed Objects for the Optical Interface Type", RFC
3591, September 2003.
Адрес редактора
C. M. Heard
158 South Madison Ave. #207
Pasadena, CA 91101-2569
USA
Телефон: +1 626 795 5311
EMail: heard@pobox.com
Heard Лучшая современная практика [Страница 41]
RFC 4181 Guidelines for MIB Documents September 2005
Полное заявление об авторском праве
Copyright (C) The Internet Society (2005).
Этот документ подпадает под действие прав, лицензий и ограничений,
содержащихся в BCP 78, и, за исключением предусмотренного в нём,
авторы сохраняют все свои права.
Этот документ и содержащаяся в нём информация предоставляются на условиях
«КАК ЕСТЬ», И УЧАСТНИК, ОРГАНИЗАЦИЯ, КОТОРУЮ ОН/ОНА ПРЕДСТАВЛЯЕТ
ИЛИ КОТОРАЯ СПОНСИРУЕТ ЕГО/ЕЁ (ЕСЛИ ТАКОВАЯ ИМЕЕТСЯ), INTERNET SOCIETY
И INTERNET ENGINEERING TASK FORCE ОТКАЗЫВАЮТСЯ ОТ ВСЕХ ГАРАНТИЙ,
ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, ПОМИМО ПРОЧЕГО, ЛЮБУЮ ГАРАНТИЮ ТОГО,
ЧТО ИСПОЛЬЗОВАНИЕ СОДЕРЖАЩЕЙСЯ ЗДЕСЬ ИНФОРМАЦИИ НЕ НАРУШИТ КАКИХ-ЛИБО
ПРАВ, И ЛЮБЫЕ ПОДРАЗУМЕВАЕМЫЕ ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ ИЛИ
ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЁННОЙ ЦЕЛИ.
Интеллектуальная собственность
IETF не занимает позиции относительно действительности или объёма каких-либо
прав интеллектуальной собственности либо иных прав, которые могут заявляться
как относящиеся к реализации или использованию технологии, описанной в этом
документе, либо относительно того, может ли быть доступна какая-либо лицензия
по таким правам; также IETF не заявляет, что предпринимала какие-либо
независимые усилия для выявления любых таких прав. Информацию о процедурах,
относящихся к правам в документах RFC, можно найти в BCP 78 и BCP 79.
Копии раскрытий IPR, представленных в Секретариат IETF, и любые заверения
о лицензиях, которые будут предоставлены, либо результат попытки получить
общую лицензию или разрешение на использование таких имущественных прав
разработчиками или пользователями этой спецификации можно получить в
онлайновом репозитории IPR IETF по адресу
http://www.ietf.org/ipr.
IETF предлагает любой заинтересованной стороне довести до её сведения любые
авторские права, патенты или патентные заявки либо другие имущественные
права, которые могут охватывать технологию, которая может потребоваться для
реализации этого стандарта. Просим направлять эту информацию в IETF по адресу
ietf-
ipr@ietf.org.
Благодарность
Финансирование функции RFC Editor в настоящее время предоставляется
Internet Society.
Heard Лучшая современная практика [Страница 42]
Network Working Group C. Heard, Ed.
Request for Comments: 4181 September 2005
BCP: 111
Category: Best Current Practice
Guidelines for Authors and Reviewers of MIB Documents
Status of This Memo
This document specifies an Internet Best Current Practices for the
Internet Community, and requests discussion and suggestions for
improvements. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
This memo provides guidelines for authors and reviewers of IETF
standards-track specifications containing MIB modules. Applicable
portions may be used as a basis for reviews of other MIB documents.
Table of Contents
1. Introduction ....................................................3
2. Terminology .....................................................3
3. General Documentation Guidelines ................................4
3.1. MIB Boilerplate Section ....................................4
3.2. Narrative Sections .........................................5
3.3. Definitions Section ........................................5
3.4. Security Considerations Section ............................5
3.5. IANA Considerations Section ................................6
3.5.1. Documents that Create a New Name Space ..............6
3.5.2. Documents that Require Assignments in
Existing Namespace(s) ...............................7
3.5.3. Documents with No IANA Requests .....................8
3.6. References Sections ........................................8
3.7. Copyright Notices ..........................................9
3.8. Intellectual Property Section .............................10
4. SMIv2 Usage Guidelines .........................................10
4.1. Module Names ..............................................10
4.2. Descriptors, TC Names, and Labels .........................10
4.3. Naming Hierarchy ..........................................11
4.4. IMPORTS Statement .........................................11
4.5. MODULE-IDENTITY Invocation ................................12
4.6. Textual Conventions and Object Definitions ................14
Heard Best Current Practice [Page 1]
RFC 4181 Guidelines for MIB Documents September 2005
4.6.1. Usage of Data Types ................................14
4.6.1.1. INTEGER, Integer32, Gauge32, and
Unsigned32 ................................14
4.6.1.2. Counter32 and Counter64 ...................16
4.6.1.3. CounterBasedGauge64 .......................17
4.6.1.4. OCTET STRING ..............................17
4.6.1.5. OBJECT IDENTIFIER .........................18
4.6.1.6. The BITS Construct ........................19
4.6.1.7. IpAddress .................................19
4.6.1.8. TimeTicks .................................19
4.6.1.9. TruthValue ................................19
4.6.1.10. Other Data Types .........................19
4.6.2. DESCRIPTION and REFERENCE Clauses ..................20
4.6.3. DISPLAY-HINT Clause ................................21
4.6.4. Conceptual Table Definitions .......................21
4.6.5. OID Values Assigned to Objects .....................23
4.6.6. OID Length Limitations and Table Indexing ..........24
4.7. Notification Definitions ..................................24
4.8. Compliance Statements .....................................25
4.8.1. Note Regarding These Examples and RFC 2578 .........27
4.9. Revisions to MIB Modules ..................................28
5. Acknowledgments ................................................31
6. Security Considerations ........................................32
7. IANA Considerations ............................................32
Appendix A: MIB Review Checklist .................................33
Appendix B: Commonly Used Textual Conventions ....................34
Appendix C: Suggested Naming Conventions .........................36
Appendix D: Suggested OID Layout .................................37
Normative References ..............................................38
Informative References ............................................40
Heard Best Current Practice [Page 2]
RFC 4181 Guidelines for MIB Documents September 2005
1. Introduction
Some time ago, the IESG instituted a policy of requiring expert
review of IETF standards-track specifications containing MIB modules.
These reviews were established to ensure that such specifications
follow established IETF documentation practices and that the MIB
modules they contain meet certain generally accepted standards of
quality, including (but not limited to) compliance with all syntactic
and semantic requirements of SMIv2 (STD 58) [RFC2578] [RFC2579]
[RFC2580] that are applicable to "standard" MIB modules. The purpose
of this memo is to document the guidelines that are followed in such
reviews.
Please note that the guidelines in this memo are not intended to
alter requirements or prohibitions (in the sense of "MUST", "MUST
NOT", "SHALL", or "SHALL NOT" as defined in RFC 2119 [RFC2119]) of
existing BCPs or Internet Standards except where those requirements
or prohibitions are ambiguous or contradictory. In the exceptional
cases where ambiguities or contradictions exist, this memo documents
the current generally accepted interpretation. In certain instances,
the guidelines in this memo do alter recommendations (in the sense of
"SHOULD", "SHOULD NOT", "RECOMMENDED", or "NOT RECOMMENDED" as
defined in RFC 2119) of existing BCPs or Internet Standards. This
has been done where practical experience has shown that the published
recommendations are suboptimal. In addition, this memo provides
guidelines for the selection of certain SMIv2 options (in the sense
of "MAY" or "OPTIONAL" as defined in RFC 2119) in cases where there
is a consensus on a preferred approach.
Although some of the guidelines in this memo are not applicable to
non-standards track or non-IETF MIB documents, authors and reviewers
of those documents should consider using the ones that do apply.
Reviewers and authors need to be aware that some of the guidelines in
this memo do not apply to MIB modules that have been translated to
SMIv2 from SMIv1 (STD 16) [RFC1155] [RFC1212] [RFC1215].
2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL", when used in the guidelines in this memo, are to be
interpreted as described in RFC 2119 [RFC2119].
The terms "MIB module" and "information module" are used
interchangeably in this memo. As used here, both terms refer to any
of the three types of information modules defined in Section 3 of RFC
2578 [RFC2578].
Heard Best Current Practice [Page 3]
RFC 4181 Guidelines for MIB Documents September 2005
The term "standard", when it appears in quotes, is used in the same
sense as in the SMIv2 documents [RFC2578] [RFC2579] [RFC2580]. In
particular, it is used to refer to the requirements that those
documents levy on "standard" modules or "standard" objects.
3. General Documentation Guidelines
In general, IETF standards-track specifications containing MIB
modules are subject to the same requirements as IETF standards-track
RFCs (see [RFC2223bis]), although there are some differences. In
particular, since the version under review will be an Internet-Draft,
the notices on the front page MUST comply with the requirements of
http://www.ietf.org/ietf/1id-guidelines.txt and not with those of
[RFC2223bis]. In addition, since the specification under review is
expected to be submitted to the IESG, it MUST comply with certain
requirements that do not necessarily apply to RFCs; see
http://www.ietf.org/ID-Checklist.html for details.
Section 4 of [RFC2223bis] lists the sections that may exist in an
RFC. Sections from the abstract onward may also be present in an
Internet-Draft; see http://www.ietf.org/ID-Checklist.html. The "body
of memo" is always required, and in a MIB document MUST contain at
least the following:
o MIB boilerplate section
o Narrative sections
o Definitions section
o Security Considerations section
o IANA Considerations section
o References section
Section-by-section guidelines follow.
3.1. MIB Boilerplate Section
This section MUST contain a verbatim copy of the latest approved
Internet-Standard Management Framework boilerplate, which is
available on-line at http://www.ops.ietf.org/mib-boilerplate.html.
Heard Best Current Practice [Page 4]
RFC 4181 Guidelines for MIB Documents September 2005
3.2. Narrative Sections
The narrative part MUST include an overview section that describes
the scope and field of application of the MIB modules defined by the
specification and that specifies the relationship (if any) of these
MIB modules to other standards, particularly to standards containing
other MIB modules. The narrative part SHOULD include one or more
sections to briefly describe the structure of the MIB modules defined
in the specification.
If the MIB modules defined by the specification import definitions
from other MIB modules (except for those defined in the SMIv2
documents [RFC2578] [RFC2579] [RFC2580]) or are always implemented in
conjunction with other MIB modules, then those facts MUST be noted in
the overview section, as MUST any special interpretations of objects
in other MIB modules. For instance, so-called media-specific MIB
modules are always implemented in conjunction with the IF-MIB
[RFC2863] and are REQUIRED to document how certain objects in the
IF-MIB are used. In addition, media-specific MIB modules that rely
on the ifStackTable [RFC2863] and the ifInvStackTable [RFC2864] to
maintain information regarding configuration and multiplexing of
interface sublayers MUST contain a description of the layering model.
3.3. Definitions Section
This section contains the MIB module(s) defined by the specification.
These MIB modules MUST be written in SMIv2 [RFC2578] [RFC2579]
[RFC2580]; SMIv1 [RFC1155] [RFC1212] [RFC1215] has "Not Recommended"
status [RFC3410] and is no longer acceptable in IETF MIB modules.
See Section 4 for guidelines on SMIv2 usage.
3.4. Security Considerations Section
Each specification that defines one or more MIB modules MUST contain
a section that discusses security considerations relevant to those
modules. This section MUST be patterned after the latest approved
template (available at http://www.ops.ietf.org/mib-security.html).
In particular, writable MIB objects that could be especially
disruptive if abused MUST be explicitly listed by name and the
associated security risks MUST be spelled out; similarly, readable
MIB objects that contain especially sensitive information or that
raise significant privacy concerns MUST be explicitly listed by name
and the reasons for the sensitivity/privacy concerns MUST be
explained. If there are no risks/vulnerabilities for a specific
category of MIB objects, then that fact MUST be explicitly stated.
Failure to mention a particular category of MIB objects will not be
equated to a claim of no risks/vulnerabilities in that category;
Heard Best Current Practice [Page 5]
RFC 4181 Guidelines for MIB Documents September 2005
rather, it will be treated as an act of omission and will result in
the document being returned to the author for correction. Remember
that the objective is not to blindly copy text from the template, but
rather to think and evaluate the risks/vulnerabilities and then
state/document the result of this evaluation.
3.5. IANA Considerations Section
In order to comply with IESG policy as set forth in
http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is
submitted to the IESG for publication MUST contain an IANA
Considerations section. The requirements for this section vary
depending what actions are required of the IANA.
3.5.1. Documents that Create a New Name Space
If an Internet-Draft defines a new name space that is to be
administered by the IANA, then the document MUST include an IANA
Considerations section conforming to the guidelines set forth in RFC
2434 [RFC2434] that specifies how the name space is to be
administered.
Name spaces defined by MIB documents generally consist of the range
of values for some type (usually an enumerated INTEGER) defined by a
TEXTUAL-CONVENTION (TC) or of a set of administratively-defined
OBJECT IDENTIFIER (OID) values. In each case, the definitions are
housed in stand-alone MIB modules that are maintained by the IANA.
These IANA-maintained MIB modules are separate from the MIB modules
defined in standards-track specifications so that new assignments can
be made without having to republish a standards-track RFC. Examples
of IANA-maintained MIB modules include the IANAifType-MIB
(http://www.iana.org/assignments/ianaiftype-mib), which defines a
name space used by the IF-MIB [RFC2863], and the IANA-RTPROTO-MIB
(http://www.iana.org/assignments/ianaiprouteprotocol-mib), which
defines a name space used by the IPMROUTE-STD-MIB [RFC2932].
The current practice for such cases is to include a detailed IANA
Considerations section complying with RFC 2434 in the DESCRIPTION
clause of the MODULE-IDENTITY invocation in each IANA-maintained MIB
module and for the IANA Considerations section of the MIB document
that defines the name spaces to refer to the URLs for the relevant
modules. See RFC 2932 [RFC2932] for an example. This creates a
chicken-and-egg problem for MIB documents that have not yet been
published as RFCs because the relevant IANA-maintained MIB modules
will not yet exist. The accepted way out of this dilemma is to
include the initial content of each IANA-maintained MIB module in a
non-normative section of the initial issue of the document that
defines the name space; for an example, see [RFC1573], which
Heard Best Current Practice [Page 6]
RFC 4181 Guidelines for MIB Documents September 2005
documents the initial version of the IANAifType-MIB. That material
is usually omitted from subsequent updates to the document since the
IANA-maintained modules are then available on-line (cf. [RFC2863]).
Reviewers of draft MIB documents to which these considerations apply
MUST check that the IANA Considerations section proposed for
publication in the RFC is present and contains pointers to the
appropriate IANA-maintained MIB modules. Reviewers of Internet
Drafts that contain the proposed initial content of IANA-maintained
MIB modules MUST also verify that the DESCRIPTION clauses of the
MODULE-IDENTITY invocations contain an IANA Considerations section
compliant with the guidelines in RFC 2434.
3.5.2. Documents that Require Assignments in Existing Namespace(s)
If an Internet-Draft requires the IANA to update an existing registry
prior to publication as an RFC, then the IANA Considerations section
in the draft MUST document that fact. MIB documents that contain the
initial version of a MIB module will generally require that the IANA
assign an OBJECT IDENTIFIER value for the MIB module's MODULE-
IDENTITY value and possibly to make other assignments as well.
Internet-Drafts containing such MIB modules MUST contain an IANA
Considerations section that specifies the registries that are to be
updated, the descriptors to which OBJECT IDENTIFIER values are being
assigned, and the subtrees under which the values are to be
allocated. The text SHOULD be crafted so that after publication it
will serve to document the OBJECT IDENTIFIER assignments. For
example, something along the following lines would be appropriate for
an Internet-Draft containing a single MIB module with MODULE-IDENTITY
descriptor powerEthernetMIB that is to be assigned a value under the
'mib-2' subtree:
The MIB module in this document uses the following IANA-assigned
OBJECT IDENTIFIER values recorded in the SMI Numbers registry:
Descriptor OBJECT IDENTIFIER value
---------- -----------------------
powerEthernetMIB { mib-2 XXX }
Editor's Note (to be removed prior to publication): the IANA is
requested to assign a value for "XXX" under the 'mib-2' subtree
and to record the assignment in the SMI Numbers registry. When
the assignment has been made, the RFC Editor is asked to replace
"XXX" (here and in the MIB module) with the assigned value and to
remove this note.
Heard Best Current Practice [Page 7]
RFC 4181 Guidelines for MIB Documents September 2005
Note well: prior to official assignment by the IANA, a draft
document MUST use placeholders (such as "XXX" above) rather than
actual numbers. See Section 4.5 for an example of how this is done
in a draft MIB module.
3.5.3. Documents with No IANA Requests
If an Internet-Draft makes no requests of the IANA, then that fact
MUST be documented in the IANA Considerations section. When an
Internet-Draft contains an update of a previously published MIB
module, it typically will not require any action on the part of the
IANA, but it may inherit an IANA Considerations section documenting
existing assignments from the RFC that contains the previous version
of the MIB module. In such cases, the draft MUST contain a note (to
be removed prior to publication) explicitly indicating that nothing
is required from the IANA. For example, a draft that contains an
updated version of the POWER-ETHERNET-MIB [RFC3621] might include an
IANA Considerations section such as the following:
The MIB module in this document uses the following IANA-assigned
OBJECT IDENTIFIER values recorded in the SMI Numbers registry:
Descriptor OBJECT IDENTIFIER value
---------- -----------------------
powerEthernetMIB { mib-2 105 }
Editor's Note (to be removed prior to publication): this draft
makes no additional requests of the IANA.
If an Internet-Draft makes no requests of the IANA and there are no
existing assignments to be documented, then suitable text for the
draft would be something along the following lines:
No IANA actions are required by this document.
3.6. References Sections
Section 4.7f of [RFC2223bis] specifies the requirements for the
references sections in an RFC; http://www.ietf.org/ID-Checklist.html
imposes the same requirements on Internet-Drafts. In particular,
there MUST be separate lists of normative and informative references,
each in a separate section. The style SHOULD follow that of recently
published RFCs.
The standard MIB boilerplate available at
http://www.ops.ietf.org/mib-boilerplate.html includes lists of
normative and informative references that MUST appear in all IETF
Heard Best Current Practice [Page 8]
RFC 4181 Guidelines for MIB Documents September 2005
specifications that contain MIB modules. If items from other MIB
modules appear in an IMPORTS statement in the Definitions section,
then the specifications containing those MIB modules MUST be included
in the list of normative references. When items are imported from an
IANA-maintained MIB module, the corresponding normative reference
SHALL point to the on-line version of that MIB module. It is the
policy of the RFC Editor that all references must be cited in the
text; such citations MUST appear in the overview section where
documents containing imported definitions (other than those already
mentioned in the MIB boilerplate) are required to be mentioned (cf.
Section 3.2).
In general, each normative reference SHOULD point to the most recent
version of the specification in question.
3.7. Copyright Notices
IETF MIB documents MUST contain the copyright notices and disclaimer
specified in Sections 5.4 and 5.5 of RFC 3978 [RFC3978]. Authors and
reviewers MUST check to make sure that the correct year is inserted
into these notices. In addition, the DESCRIPTION clause of the
MODULE-IDENTITY invocation of each MIB module that will appear in the
published RFC MUST contain a pointer to the copyright notices in the
RFC. A template suitable for inclusion in an Internet-Draft,
appropriate for MIB modules other than those that are to be
maintained by the IANA, is as follows:
DESCRIPTION
" [ ... ]
Copyright (C) The Internet Society (date). This version
of this MIB module is part of RFC yyyy; see the RFC
itself for full legal notices."
-- RFC Ed.: replace yyyy with actual RFC number & remove this note
A template suitable for MIB modules that are to be maintained by the
IANA is as follows:
DESCRIPTION
" [ ... ]
Copyright (C) The Internet Society (date). The initial
version of this MIB module was published in RFC yyyy;
for full legal notices see the RFC itself. Supplementary
information may be available at:
http://www.ietf.org/copyrights/ianamib.html."
-- RFC Ed.: replace yyyy with actual RFC number & remove this note
Heard Best Current Practice [Page 9]
RFC 4181 Guidelines for MIB Documents September 2005
In each case, the current year is to be inserted in place of the word
"date".
3.8. Intellectual Property Section
Section 5 of RFC 3979 [RFC3979] contains a notice regarding
intellectual property rights or other rights that must appear in all
IETF RFCs. A verbatim copy of that notice SHOULD appear in every
IETF MIB document.
4. SMIv2 Usage Guidelines
In general, MIB modules in IETF standards-track specifications MUST
comply with all syntactic and semantic requirements of SMIv2
[RFC2578] [RFC2579] [RFC2580] that apply to "standard" MIB modules
and except as noted below SHOULD comply with SMIv2 recommendations.
The guidelines in this section are intended to supplement the SMIv2
documents in the following ways:
o to document the current generally accepted interpretation when
those documents contain ambiguities or contradictions;
o to update recommendations in those documents that have been shown
by practical experience to be out-of-date or otherwise suboptimal;
o to provide guidance in selection of SMIv2 options in cases where
there is a consensus on a preferred approach.
4.1. Module Names
RFC 2578 Section 3 specifies the rules for module names. Note in
particular that names of "standard" modules MUST be unique, MUST
follow the syntax rules in RFC 2578 Section 3, and MUST NOT be
changed when a MIB module is revised (see also RFC 2578 Section 10).
It is RECOMMENDED that module names be mnemonic. See Appendix C for
suggested naming conventions.
4.2. Descriptors, TC Names, and Labels
RFC 2578 Sections 3.1, 7.1.1, and 7.1.4 and RFC 2579 Section 3
recommend that descriptors and names associated with macro
invocations and labels associated with enumerated INTEGER and BITS
values be no longer than 32 characters, but require that they be no
longer than 64 characters.
Heard Best Current Practice [Page 10]
RFC 4181 Guidelines for MIB Documents September 2005
Restricting descriptors, TC names, and labels to 32 characters often
conflicts with the recommendation that they be mnemonic and (for
descriptors and TC names) with the requirement that they be unique
(see RFC 2578 Section 3.1 and RFC 2579 Section 3). The consensus of
the current pool of MIB reviewers is that the SMIv2 recommendation to
limit descriptors, TC names, and labels to 32 characters SHOULD be
set aside in favor of promoting clarity and uniqueness and that
automated tools such as MIB compilers SHOULD NOT by default generate
warnings for violating that recommendation.
Note that violations of the 64-character limit MUST NOT be ignored;
they MUST be treated as errors.
See Appendix C for suggested descriptor and TC naming conventions.
4.3. Naming Hierarchy
RFC 2578 Section 4 describes the object identifier subtrees that are
maintained by IANA and specifies the usages for those subtrees. In
particular, the mgmt subtree { iso 3 6 1 2 } is used to identify IETF
"standard" objects, while the experimental subtree { iso 3 6 1 3 } is
used to identify objects that are under development in the IETF. It
is REQUIRED that objects be moved from the experimental subtree to
the mgmt subtree when a MIB module enters the IETF standards track.
Experience has shown that it is impractical to move objects from one
subtree to another once those objects have seen large-scale use in an
operational environment. Hence any object that is targeted for
deployment in an operational environment MUST NOT be registered under
the experimental subtree, irrespective of the standardization status
of that object. The experimental subtree should be used only for
objects that are intended for limited experimental deployment. Such
objects typically are defined in Experimental RFCs.
Note: the term "object", as used here and in RFC 2578 Section 4, is
to be broadly interpreted as any construct that results in an OBJECT
IDENTIFIER registration. The list of such constructs is specified in
RFC 2578 Section 3.6.
4.4. IMPORTS Statement
RFC 2578 Section 3.2 specifies which symbols must be imported and
also lists certain predefined symbols that must not be imported.
The general requirement is that if an external symbol other than a
predefined ASN.1 type or the BITS construct is used, then it MUST be
mentioned in the module's IMPORTS statement. The words "external
object" in the first paragraph of that section may give the
Heard Best Current Practice [Page 11]
RFC 4181 Guidelines for MIB Documents September 2005
impression that such symbols are limited to those that refer to
object definitions, but that is not the case, as subsequent
paragraphs should make clear.
Note that exemptions to this general requirement are granted by RFC
2580 Sections 5.4.3 and 6.5.2 for descriptors of objects appearing in
the OBJECT clause of a MODULE-COMPLIANCE statement or in the
VARIATION clause of an AGENT-CAPABILITIES statement. Some MIB
compilers also grant exemptions to descriptors of notifications
appearing in a VARIATION clause and to descriptors of object groups
and notification groups referenced by a MANDATORY-GROUPS clause, a
GROUP clause, or an INCLUDES clause, although RFC 2580 (through
apparent oversight) does not mention those cases. The exemptions are
sometimes seen as unhelpful because they make IMPORTS rules more
complicated and inter-module dependencies less obvious than they
otherwise would be. External symbols referenced by compliance
statements and capabilities statements MAY therefore be listed in the
IMPORTS statement; if this is done, it SHOULD be done consistently.
Finally, even though it is not forbidden by the SMI, it is considered
poor style to import symbols that are not used, and standards-track
MIB modules SHOULD NOT do so.
4.5. MODULE-IDENTITY Invocation
RFC 2578 Section 3 requires that all SMIv2 MIB modules start with
exactly one invocation of the MODULE-IDENTITY macro. This invocation
MUST appear immediately after the IMPORTS statement.
RFC 2578 Section 5 describes how the various clauses are used. The
following additional guidelines apply to all MIB modules over which
the IETF has change control:
- If the module was developed by an IETF working group, then the
ORGANIZATION clause MUST provide the full name of the working
group, and the CONTACT-INFO clause MUST include working group
mailing list information. The CONTACT-INFO clause SHOULD also
provide a pointer to the working group's web page.
- A REVISION clause MUST be present for each revision of the MIB
module, and the UTC time of the most recent REVISION clause MUST
match that of the LAST-UPDATED clause. The DESCRIPTION clause
associated with each revision MUST state in which RFC that revision
appeared and SHOULD provide a list of all significant changes.
When a MIB module is revised, UTC times in all REVISION clauses
SHOULD be updated to use four-digit year notation.
Heard Best Current Practice [Page 12]
RFC 4181 Guidelines for MIB Documents September 2005
- The value assigned to the MODULE-IDENTITY descriptor MUST be unique
and (for IETF standards-track MIB modules) SHOULD reside under the
mgmt subtree [RFC2578]. Most often it will be an IANA-assigned
value directly under mib-2 [RFC2578], although for media-specific
MIB modules that extend the IF-MIB [RFC2863] it is customary to use
an IANA-assigned value under transmission [RFC2578]. In the past,
some IETF working groups have made their own assignments from
subtrees delegated to them by IANA, but that practice has proven
problematic and is NOT RECOMMENDED.
While a MIB module is under development, the RFC number in which it
will eventually be published is usually unknown and must be filled in
by the RFC Editor prior to publication. An appropriate form for the
REVISION clause applying to a version under development would be
something along the following lines:
REVISION "200212132358Z" -- December 13, 2002
DESCRIPTION "Initial version, published as RFC yyyy."
-- RFC Ed.: replace yyyy with actual RFC number & remove this note
Note that after RFC publication, a REVISION clause is present only
for published versions of a MIB module and not for interim versions
that existed only as Internet-Drafts. Thus, a draft version of a MIB
module MUST contain just one new REVISION clause that covers all
changes since the last published version (if any).
When the initial version of a MIB module is under development, the
value assigned to the MODULE-IDENTITY descriptor will be unknown if
an IANA-assigned value is used, because the assignment is made just
prior to publication as an RFC. The accepted form for the MODULE-
IDENTITY statement in draft versions of such a module is something
along the following lines:
<descriptor> MODULE-IDENTITY
[ ... ]
::= { <subtree> XXX }
-- RFC Ed.: replace XXX with IANA-assigned number & remove this note
where <descriptor> is whatever descriptor has been selected for the
module and <subtree> is the subtree under which the module is to be
registered (e.g., mib-2 or transmission). Note that XXX must be
temporarily replaced by a number in order for the module to compile.
Heard Best Current Practice [Page 13]
RFC 4181 Guidelines for MIB Documents September 2005
Note well: prior to official assignment by the IANA, a draft
document MUST use a placeholder (such as "XXX" above) rather than an
actual number. If trial implementations are desired during the
development process, then an assignment under the 'experimental'
subtree may be obtained from the IANA (cf. Section 4.3).
4.6. Textual Conventions and Object Definitions
4.6.1. Usage of Data Types
4.6.1.1. INTEGER, Integer32, Gauge32, and Unsigned32
The 32-bit integer data types INTEGER, Integer32, Gauge32, and
Unsigned32 are described in RFC 2578 Section 2 and further elaborated
in RFC 2578 Sections 7.1.1, 7.1.7, and 7.1.11. The following
guidelines apply when selecting one of these data types for an object
definition or a textual convention:
- For integer-valued enumerations:
- INTEGER is REQUIRED; - Integer32, Unsigned32, and Gauge32 MUST
NOT be used.
Note that RFC 2578 recommends (but does not require) that integer-
valued enumerations start at 1 and be numbered contiguously. This
recommendation SHOULD be followed unless there is a valid reason to
do otherwise, e.g., to match values of external data or to indicate
special cases, and any such special-case usage SHOULD be clearly
documented. For an example, see the InetAddressType TC [RFC4001].
Although the SMI allows DEFVAL clauses for integer-valued
enumerations to specify the default value either by label or by
numeric value, the label form is preferred since all the examples in
RFC 2578 are of that form and some tools do not accept the numeric
form.
- If the value range is between -2147483648..2147483647 (inclusive)
and negative values are possible, then:
- Integer32 is RECOMMENDED;
- INTEGER is acceptable;
- Unsigned32 and Gauge32 MUST NOT be used.
- If the value range is between 0..4294967295 (inclusive) and the
value of the information being modelled may increase above the
maximum value or decrease below the minimum value, then:
Heard Best Current Practice [Page 14]
RFC 4181 Guidelines for MIB Documents September 2005
- Gauge32 is RECOMMENDED;
- Unsigned32 is acceptable;
- INTEGER and Integer32 MUST NOT be used if
values greater than 2147483647 are possible.
- If the value range is between 0..4294967295 (inclusive), and values
greater than 2147483647 are possible, and the value of the
information being modelled does not increase above the maximum
value nor decrease below the minimum value, then:
- Unsigned32 is RECOMMENDED;
- Gauge32 is acceptable;
- INTEGER and Integer32 MUST NOT be used.
- If the value range is between 0..2147483647 (inclusive), and the
value of the information being modelled does not increase above the
maximum value nor decrease below the minimum value, then:
- Unsigned32 is RECOMMENDED;
- INTEGER, Integer32, and Gauge32 are acceptable.
- For integer-valued objects that appear in an INDEX clause or for
integer-valued TCs that are to be used in an index column:
- Unsigned32 with a range that excludes zero is RECOMMENDED for
most index objects. It is acceptable to include zero in the
range when it is semantically significant or when it is used as
the index value for a unique row with special properties. Such
usage SHOULD be clearly documented in the DESCRIPTION clause.
- Integer32 or INTEGER with a non-negative range is acceptable.
Again, zero SHOULD be excluded from the range except when it is
semantically significant or when it is used as the index value
for a unique row with special properties, and in such cases the
usage SHOULD be clearly documented in the DESCRIPTION clause.
- Use of Gauge32 is acceptable for index objects that have gauge
semantics.
The guidelines above combine both the usage rules for integer data
types and the INDEX rules in RFC 2578 Section 7.7 up to and including
bullet (1) plus the next-to-last paragraph on page 28.
Sometimes it will be necessary for external variables to represent
values of an index object -- e.g., ifIndex [RFC2863]. In such cases,
authors of the module containing that object SHOULD consider defining
TCs such as InterfaceIndex and/or InterfaceIndexOrZero [RFC2863].
Heard Best Current Practice [Page 15]
RFC 4181 Guidelines for MIB Documents September 2005
Note that INTEGER is a predefined ASN.1 type and MUST NOT be present
in a module's IMPORTS statement, whereas Integer32, Gauge32, and
Unsigned32 are defined by SNMPv2-SMI and MUST be imported from that
module if used.
4.6.1.2. Counter32 and Counter64
Counter32 and Counter64 have special semantics as described in RFC
2578 Sections 7.1.6 and 7.1.10, respectively. Object definitions
MUST (and textual conventions SHOULD) respect these semantics. That
means:
- It is OK to use Counter32/64 for counters that may/will be reset
when the management subsystem is re-initialized or when other
unusual/irregular events occur (e.g., counters maintained on a line
card may be reset when the line card is reset). However, if it is
possible for such other unusual/irregular events to occur, the
DESCRIPTION clause MUST state that this is so and MUST describe
those other unusual/irregular events in sufficient detail that it
is possible for a management application to determine whether a
reset has occurred since the last time the counter was polled. The
RECOMMENDED way to do this is to provide a discontinuity indicator
as described in RFC 2578 Sections 7.1.6 and 7.1.10. For an example
of such a discontinuity indicator, see the
ifCounterDiscontinuityTime object in the IF-MIB [RFC2863].
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement that on a discontinuity the counter
MUST reset to zero or to any other specific value.
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement that it MUST reset at any specific
time/event (e.g., midnight).
- It is NOT OK for one manager to request the agent to reset the
value(s) of counter(s) to zero, and Counter32/64 is the wrong
syntax for "counters" that regularly reset themselves to zero. For
the latter, it is better to define or use textual conventions such
as those in RFC 3593 [RFC3593] or RFC 3705 [RFC3705].
RFC 2578 Section 7.1.10 places a requirement on "standard" MIB
modules that the Counter64 type may be used only if the information
being modelled would wrap in less than one hour if the Counter32 type
was used instead. Now that SNMPv3 is an Internet Standard and SNMPv1
is Historic (see http://www.rfc-editor.org/rfcxx00.html for status
and [RFC3410] for rationale), there is no reason to continue
enforcing this restriction. Henceforth "standard" MIB modules MAY
use the Counter64 type when it makes sense to do so, and MUST use
Heard Best Current Practice [Page 16]
RFC 4181 Guidelines for MIB Documents September 2005
Counter64 if the information being modelled would wrap in less than
one hour if the Counter32 type was used instead. Note also that
there is no longer a requirement to define Counter32 counterparts for
each Counter64 object, although one is still allowed to do so.
There also exist closely-related textual conventions
ZeroBasedCounter32 and ZeroBasedCounter64 defined in RMON2-MIB
[RFC2021] and HCNUM-TC [RFC2856], respectively.
The only difference between ZeroBasedCounter32/64 TCs and
Counter32/64 is their starting value; at time=X, where X is their
minimum-wrap-time after they were created, the behavior of
ZeroBasedCounter32/64 becomes exactly the same as Counter32/64.
Thus, the preceding paragraphs/rules apply not only to Counter32/64,
but also to ZeroBasedCounter32/64 TCs.
4.6.1.3. CounterBasedGauge64
SMIv2 unfortunately does not provide 64-bit integer base types. In
order to make up for this omission, the CounterBasedGauge64 textual
convention is defined in HCNUM-TC [RFC2856]. This TC uses Counter64
as a base type, but discards the special counter semantics, which is
allowed under the generally accepted interpretation of RFC 2579
Section 3.3. It does inherit all the syntactic restrictions of that
type, which means that it MUST NOT be subtyped and that objects
defined with it MUST NOT appear in an INDEX clause, MUST NOT have a
DEFVAL clause, and MUST have a MAX-ACCESS of read-only or
accessible-for-notify.
This TC SHOULD be used for object definitions that require a 64-bit
unsigned data type with gauge semantics. If a 64-bit unsigned data
type with different semantics is needed, then a different TC based on
Counter64 MUST be used, since one TC cannot refine another (cf. RFC
2579 Section 3.5).
4.6.1.4. OCTET STRING
The OCTET STRING type is described in RFC 2578 Section 7.1.2. It
represents arbitrary binary or textual data whose length is between 0
and 65535 octets inclusive. Objects and TCs whose SYNTAX is of this
type SHOULD have a size constraint when the actual bounds are more
restrictive than the SMI-imposed limits. This is particularly true
for index objects. Note, however, that size constraints SHOULD NOT
be imposed arbitrarily, as the SMI does not permit them to be changed
afterward.
Heard Best Current Practice [Page 17]
RFC 4181 Guidelines for MIB Documents September 2005
There exist a number of standard TCs that cater to some of the more
common requirements for specialized OCTET STRING types. In
particular, SNMPv2-TC [RFC2579] contains the DisplayString,
PhysAddress, MacAddress, and DateAndTime TCs; the SNMP-FRAMEWORK-MIB
[RFC3411] contains the SnmpAdminString TC; and the SYSAPPL-MIB
[RFC2287] contains the Utf8String and LongUtf8String TCs. When a
standard TC provides the desired semantics, it SHOULD be used in an
object's SYNTAX clause instead of OCTET STRING or an equivalent
locally-defined TC.
Note that OCTET STRING is a predefined ASN.1 type and MUST NOT be
present in a module's IMPORTS statement.
4.6.1.5. OBJECT IDENTIFIER
The OBJECT IDENTIFIER type is described in RFC 2578 Section 7.1.3.
Its instances represent administratively assigned names. Note that
both the SMI and the SNMP protocol limit instances of this type to
128 sub-identifiers and require that each sub-identifier be within
the range 0 to 4294967295 inclusive. Subtyping is not allowed.
The purpose of OBJECT IDENTIFIER values is to provide authoritative
identification either for some type of item or for a specific
instance of some type of item. Among the items that can be
identified in this way are definitions in MIB modules created via the
MODULE-IDENTITY, OBJECT-IDENTITY, OBJECT-TYPE, NOTIFICATION-TYPE,
OBJECT-GROUP, NOTIFICATION-GROUP, MODULE-COMPLIANCE, and AGENT-
CAPABILITIES constructs; and via instances of objects defined in MIB
modules, protocols, languages, specifications, interface types,
hardware, and software. For some of these uses other possibilities
exist, e.g., OCTET STRING or enumerated INTEGER values. The OBJECT
IDENTIFIER type SHOULD be used instead of the alternatives when the
set of identification values needs to be independently extensible
without the need for a registry to provide centralized coordination.
There exist a number of standard TCs that cater to some of the more
common requirements for specialized OBJECT IDENTIFIER types. In
particular, SNMPv2-TC [RFC2579] contains the AutonomousType,
VariablePointer, and RowPointer TCs. When a standard TC provides the
desired semantics, it SHOULD be used in an object's SYNTAX clause
instead of OBJECT IDENTIFIER or an equivalent locally-defined TC.
Note that OBJECT IDENTIFIER is a predefined ASN.1 type and MUST NOT
be present in a module's IMPORTS statement.
Heard Best Current Practice [Page 18]
RFC 4181 Guidelines for MIB Documents September 2005
4.6.1.6. The BITS Construct
The BITS construct is described in RFC 2578 Section 7.1.4. It
represents an enumeration of named bits. The bit positions in a TC
or object definition whose SYNTAX is of this type MUST start at 0 and
SHOULD be contiguous.
Note that the BITS construct is defined by the macros that use it and
therefore MUST NOT be present in a module's IMPORTS statement.
4.6.1.7. IpAddress
The IpAddress type described in RFC 2578 Section 7.1.5 SHOULD NOT be
used in new MIB modules. The InetAddress/InetAddressType textual
conventions [RFC4001] SHOULD be used instead.
4.6.1.8. TimeTicks
The TimeTicks type is described in RFC 2578 Section 7.1.8. It
represents the time in hundredths of a second between two epochs,
reduced modulo 2^32. It MUST NOT be subtyped, and the DESCRIPTION
clause of any object or TC whose SYNTAX is of this type MUST identify
the reference epochs.
The TimeTicks type SHOULD NOT be used directly in definitions of
objects that are snapshots of sysUpTime [RFC3418]. The TimeStamp TC
[RFC2579] already conveys the desired semantics and SHOULD be used
instead.
4.6.1.9. TruthValue
The TruthValue TC is defined in SNMPv2-TC [RFC2579]. It is an
enumerated INTEGER type that assumes the values true(1) and false(2).
This TC SHOULD be used in the SYNTAX clause of object definitions
that require a Boolean type. MIB modules SHOULD NOT use enumerated
INTEGER types or define TCs that duplicate its semantics.
4.6.1.10. Other Data Types
There exist a number of standard TCs that cater to some of the more
common requirements for specialized data types. Some have been
mentioned above, and Appendix B contains a partial list that includes
those plus some others that are a bit more specialized. An on-line
version of that list, which is updated as new TCs are developed, can
be found at http://www.ops.ietf.org/mib-common-tcs.html.
Heard Best Current Practice [Page 19]
RFC 4181 Guidelines for MIB Documents September 2005
Whenever a standard TC already conveys the desired semantics, it
SHOULD be used in an object definition instead of the corresponding
base type or a locally-defined TC. This is especially true of the
TCs defined in SNMPv2-TC [RFC2579] and SNMP-FRAMEWORK-MIB [RFC3411]
because they are Internet Standards, and so modules that refer to
them will not suffer delay in advancement on the standards track on
account of such references.
MIB module authors need to be aware that enumerated INTEGER or BITS
TCs may in some cases be extended with additional enumerated values
or additional bit positions. When an imported TC that may be
extended in this way is used to define an object that may be written
or that serves as an index in a read-create table, then the set of
values or bit positions that needs to be supported SHOULD be
specified either in the object's DESCRIPTION clause or in an OBJECT
clause in the MIB module's compliance statement(s). This may be done
by explicitly listing the required values or bit positions, or it may
be done by stating that an implementation may support a subset of
values or bit positions of its choosing.
4.6.2. DESCRIPTION and REFERENCE Clauses
It is hard to overemphasize the importance of an accurate and
unambiguous DESCRIPTION clause for all objects and TCs. The
DESCRIPTION clause contains the instructions that implementors will
use to implement an object, and if they are inadequate or ambiguous,
then implementation quality will suffer. Probably the single most
important job of a MIB reviewer is to ensure that DESCRIPTION clauses
are sufficiently clear and unambiguous to allow interoperable
implementations to be created.
A very common problem is to see an object definition for, say,
'stdMIBPoofpoofCounter' with a DESCRIPTION clause that just says
"Number of poofpoofs" with no indication what a 'poofpoof' is. In
such cases, it is strongly RECOMMENDED that there either be at least
a minimal explanation or else a REFERENCE clause to point to the
definition of a 'poofpoof'.
For read-write objects (other than columns in read-create tables that
have well-defined persistence properties), it is RECOMMENDED that the
DESCRIPTION clause specify what happens to the value after an agent
reboot. Among the possibilities are that the value remains
unchanged, that it reverts to a well-defined default value, or that
the result is implementation-dependent.
Heard Best Current Practice [Page 20]
RFC 4181 Guidelines for MIB Documents September 2005
4.6.3. DISPLAY-HINT Clause
The DISPLAY-HINT clause is used in a TC to provide a nonbinding hint
to a management application as to how the value of an instance of an
object defined with the syntax in the TC might be displayed. Its
presence is optional.
Although management applications typically default to decimal format
("d") for integer TCs that are not enumerations and to a hexadecimal
format ("1x:" or "1x " or "1x_") for octet string TCs when the
DISPLAY-HINT clause is absent, it should be noted that SMIv2 does not
actually specify any defaults. MIB authors should be aware that a
clear hint is provided to applications only when the DISPLAY-HINT
clause is present.
4.6.4. Conceptual Table Definitions
RFC 2578 Sections 7.1.12 and 7.1.12.1 specify the rules for defining
conceptual tables, and RFC 2578 Sections 7.7, 7.8, and 7.8.1 specify
conceptual table indexing rules. The following guidelines apply to
such definitions:
- For conceptual rows:
- If the row is an extension of a row in some other table, then an
AUGMENTS clause MUST be used if the relationship is one-to-one,
and an INDEX clause MUST be used if the relationship is sparse.
In the latter case, the INDEX clause SHOULD be identical to that
of the original table.
- If the row is an element of an expansion table -- that is, if
multiple row instances correspond to a single row instance in
some other table -- then an INDEX clause MUST be used, and the
first-mentioned elements SHOULD be the indices of that other
table, listed in the same order.
- If objects external to the row are present in the INDEX clause,
then the conceptual row's DESCRIPTION clause MUST specify how
those objects are used in identifying instances of its columnar
objects, and in particular MUST specify for which values of those
index objects the conceptual row may exist.
- Use of the IMPLIED keyword is NOT RECOMMENDED for any index
object that may appear in the INDEX clause of an expansion table.
Since this keyword may be associated only with the last object in
an INDEX clause, it cannot be associated with the same index
object in a primary table and an expansion table. This will
cause the sort order to be different in the primary table and any
Heard Best Current Practice [Page 21]
RFC 4181 Guidelines for MIB Documents September 2005
expansion tables. As a consequence, an implementation will be
unable to reuse indexing code from the primary table in expansion
tables, and data structures meant to be extended might actually
have to be replicated. Designers who are tempted to use IMPLIED
should consider that the resulting sort order rarely meets user
expectations, particularly for strings that include both
uppercase and lowercase letters, and it does not take the user
language or locale into account.
- If dynamic row creation and/or deletion by management applications
is supported, then:
- There SHOULD be one columnar object with a SYNTAX value of
RowStatus [RFC2579] and a MAX-ACCESS value of read-create. This
object is called the status column for the conceptual row. All
other columnar objects MUST have a MAX-ACCESS value of read-
create, read-only, accessible-for-notify, or not-accessible; a
MAX-ACCESS value of read-write is not allowed.
- There either MUST be one columnar object with a SYNTAX value of
StorageType [RFC2579] and a MAX-ACCESS value of read-create, or
else the row object (table entry) DESCRIPTION clause MUST specify
what happens to dynamically-created rows after an agent restart.
- If the agent itself may also create and/or delete rows, then the
conditions under which this can occur MUST be clearly documented
in the row object DESCRIPTION clause.
- For conceptual rows that include a status column:
- The DESCRIPTION clause of the status column MUST specify which
columnar objects (if any) have to be set to valid values before
the row can be activated. If any objects in cascading tables
have to be populated with related data before the row can be
activated, then this MUST also be specified.
- The DESCRIPTION clause of the status column MUST specify whether
or not it is possible to modify other columns in the same
conceptual row when the status value is active(1). Note that in
many cases it will be possible to modify some writable columns
when the row is active but not others. In such cases, the
DESCRIPTION clause for each writable column SHOULD state whether
or not that column can be modified when the row is active, and
the DESCRIPTION clause for the status column SHOULD state that
modifiability of other columns when the status value is active(1)
is specified in the DESCRIPTION clauses for those columns (rather
than listing the modifiable columns individually).
Heard Best Current Practice [Page 22]
RFC 4181 Guidelines for MIB Documents September 2005
- For conceptual rows that include a StorageType column:
- The DESCRIPTION clause of the StorageType column MUST specify
which read-write or read-create columnar objects in permanent(4)
rows an agent must, at a minimum, allow to be writable.
Note that RFC 2578 Section 7.8 requires that the lifetime of an
instance of a conceptual row that AUGMENTS a base row must be the
same as the corresponding instance of the base row. It follows that
there is no need for a RowStatus or StorageType column in an
augmenting row if one is already present in the base row.
Complete requirements for the RowStatus and StorageType TCs can be
found in RFC 2579, in the DESCRIPTION clauses for those TCs.
4.6.5. OID Values Assigned to Objects
RFC 2578 Section 7.10 specifies the rules for assigning OBJECT
IDENTIFIER (OID) values to OBJECT-TYPE definitions. In particular:
- A conceptual table MUST have exactly one subordinate object, which
is a conceptual row. The OID assigned to the conceptual row MUST
be derived by appending a sub-identifier of "1" to the OID assigned
to the conceptual table.
- A conceptual row has as many subordinate objects as there are
columns in the row; there MUST be at least one. The OID assigned
to each columnar object MUST be derived by appending a non-zero
sub-identifier, unique within the row, to the OID assigned to the
conceptual row.
- A columnar or scalar object MUST NOT have any subordinate objects.
- The last sub-identifier of an OID assigned to any object (be it
table, row, column, or scalar) MUST NOT be equal to zero. Note
that sub-identifiers of intermediate nodes MAY be equal to zero.
- The OID assigned to an object definition MUST NOT also be assigned
to another definition that results in OID registration. RFC 2578
Section 3.6 lists the constructs that create OID registrations.
Although it is not specifically required by the SMI, it is customary
(and strongly RECOMMENDED) that object definitions not be registered
beneath group definitions, compliance statements, capabilities
statements, or notification definitions. It is also customary (and
strongly RECOMMENDED) that group definitions, compliance statements,
Heard Best Current Practice [Page 23]
RFC 4181 Guidelines for MIB Documents September 2005
capabilities statements, and notification definitions not be
registered beneath object definitions. See Appendix D for a
RECOMMENDED OID assignment scheme.
4.6.6. OID Length Limitations and Table Indexing
As specified in RFC 2578 Section 3.5, all OIDs are limited to 128
sub-identifiers. While this is not likely to cause problems with
administrative assignments, it does place some limitations on table
indexing. That is true because the length limitation also applies to
OIDs for object instances, and these consist of the concatenation of
the "base" OID assigned in the object definition plus the index
components. When a table has multiple indices of types such as OCTET
STRING or OBJECT IDENTIFIER that resolve to multiple sub-identifiers,
then the 128-sub-identifier limit can be quickly reached.
Despite its inconvenience, the 128-sub-identifier limit is not
something that can be ignored. In addition to being imposed by the
SMI, it is also imposed by the SNMP (see the last paragraph in
Section 4.1 of RFC 3416 [RFC3416]). It follows that any table with
enough indexing components to violate this limit cannot be read or
written using the SNMP and so is unusable. Hence table design MUST
take the 128-sub-identifier limit into account. It is RECOMMENDED
that all MIB documents make explicit any limitations on index
component lengths that management software must observe. This may be
done either by including SIZE constraints on the index components or
by specifying applicable constraints in the conceptual row
DESCRIPTION clause or in the surrounding documentation.
4.7. Notification Definitions
RFC 2578 Section 8 specifies the rules for notification definitions.
In particular:
- Inaccessible objects MUST NOT appear in the OBJECTS clause.
- For each object type mentioned in the OBJECTS clause, the
DESCRIPTION clause MUST specify which object instance is to be
present in the transmitted notification and MUST specify the
information/meaning conveyed.
- The OBJECT IDENTIFIER (OID) value assigned to each notification
type MUST have a next-to-last sub-identifier of zero, so that it is
possible to convert an SMIv2 notification definition into an SMIv1
trap definition and back again without information loss (see
[RFC3584] Section 2.1.2) and possible for a multilingual proxy
chain to translate an SNMPv2 trap into an SNMPv1 trap and back
again without information loss (see [RFC3584] Section 3). In
Heard Best Current Practice [Page 24]
RFC 4181 Guidelines for MIB Documents September 2005
addition, the OID assigned to a notification definition MUST NOT
also be assigned to another definition that results in OID
registration. RFC 2578 Section 3.6 lists the constructs that
create OID registrations.
Although it is not specifically required by the SMI, it is customary
(and strongly RECOMMENDED) that notification definitions not be
registered beneath group definitions, compliance statements,
capabilities statements, or object definitions (this last is
especially unwise, as it may result in an object instance and a
notification definition sharing the same OID). It is also customary
(and strongly RECOMMENDED) that the OIDs assigned to notification
types be leaf OIDs (i.e., that there be no OID registrations
subordinate to a notification definition). See Appendix D for a
RECOMMENDED OID assignment scheme.
In many cases, notifications will be triggered by external events,
and sometimes it will be possible for those external events to occur
at a sufficiently rapid rate that sending a notification for each
occurrence would overwhelm the network. In such cases, a mechanism
MUST be provided for limiting the rate at which the notification can
be generated. A common technique is to require that the notification
generator use throttling -- that is, to require that it generate no
more than one notification for each event source in any given time
interval of duration T. The throttling period T MAY be configurable,
in which case it is specified in a MIB object, or it MAY be fixed, in
which case it is specified in the notification definition. Examples
of the fixed time interval technique can be found in the SNMP-
REPEATER-MIB [RFC2108] and in the ENTITY-MIB [RFC4133].
4.8. Compliance Statements
RFC 2580 Sections 3, 4, and 5 specify the rules for conformance
groups and compliance statements. In particular:
- Every object with a MAX-ACCESS value other than "not-accessible"
MUST be contained in at least one object group.
- Every notification MUST be contained in at least one notification
group.
- There MUST be at least one compliance statement defined for each
"standard" MIB module. It may reside either within that MIB module
or within a companion MIB module.
In writing compliance statements, there are several points that are
easily overlooked:
Heard Best Current Practice [Page 25]
RFC 4181 Guidelines for MIB Documents September 2005
- An object group or notification group that is not mentioned either
in the MANDATORY-GROUPS clause or in any GROUP clause of a MODULE-
COMPLIANCE statement is unconditionally optional with respect to
that compliance statement. An alternate way to indicate that an
object group or notification group is optional is to mention it in
a GROUP clause whose DESCRIPTION clause states that the group is
optional. The latter method is RECOMMENDED (for optional groups
that are relevant to the compliance statement) in order to make it
clear that the optional status is intended rather than being the
result of an act of omission.
- If there are any objects with a MAX-ACCESS value of read-write or
read-create for which there is no OBJECT clause that specifies a
MIN-ACCESS of read-only, then implementations must support write
access to those objects in order to be compliant with that MODULE-
COMPLIANCE statement. This fact sometimes catches MIB module
authors by surprise. When confronted with such cases, reviewers
SHOULD verify that this is indeed what the authors intended, since
it often is not.
- On the other side of the coin, MIB module authors need to be aware
that while a read-only compliance statement is sufficient to
support interoperable monitoring applications, it is not sufficient
to support interoperable configuration applications. A technique
commonly used in MIB modules that are intended to support both
monitoring and configuration is to provide both a read-only
compliance statement and a full compliance statement. A good
example is provided by the DIFFSERV-MIB [RFC3289]. Authors SHOULD
consider using this technique when it is applicable.
Sometimes MIB module authors will want to specify that a compliant
implementation needs to support only a subset of the values allowed
by an object's SYNTAX clause. For accessible objects, this may be
done either by specifying the required values in an object's
DESCRIPTION clause or by providing an OBJECT clause with a refined
SYNTAX in a compliance statement. The latter method is RECOMMENDED
for most cases, and is REQUIRED if there are multiple compliance
statements with different value subsets required. The DIFFSERV-MIB
[RFC3289] illustrates this point. The diffServMIBFullCompliance
statement contains the following OBJECT clause. (See Section 4.8.1,
"Note Regarding These Examples and RFC 2578".)
OBJECT diffServDataPathStatus
SYNTAX RowStatus { active(1) }
WRITE-SYNTAX RowStatus { createAndGo(4), destroy(6) }
DESCRIPTION
"Support for createAndWait and notInService is not required."
Heard Best Current Practice [Page 26]
RFC 4181 Guidelines for MIB Documents September 2005
whereas the diffServMIBReadOnlyCompliance statement contains this:
OBJECT diffServDataPathStatus
SYNTAX RowStatus { active(1) }
MIN-ACCESS read-only
DESCRIPTION
"Write access is not required, and active is the only status that
needs to be supported."
One cannot do this for inaccessible index objects because they cannot
be present in object groups and cannot be mentioned in OBJECT
clauses. There are situations, however, in which one might wish to
indicate that an implementation is required to support only a subset
of the possible values of some index in a read-create table. In such
cases, the requirements MUST be specified either in the index
object's DESCRIPTION clause (RECOMMENDED if there is only one value
subset) or in the DESCRIPTION clause of a MODULE-COMPLIANCE statement
(REQUIRED if the value subset is unique to the compliance statement).
In many cases, a MIB module is always implemented in conjunction with
one or more other MIB modules. That fact is REQUIRED to be noted in
the surrounding documentation (see Section 3.2 above), and it SHOULD
also be noted in the relevant compliance statements. In cases where
a particular compliance statement in (say) MIB module A requires the
complete implementation of some other MIB module B, then the
RECOMMENDED approach is to include a statement to that effect in the
DESCRIPTION clause of the compliance statement(s) in MIB module A.
It is also possible, however, that MIB module A might have
requirements that are different from those that are expressed by any
compliance statement of module B -- for example, module A might not
require any of the unconditionally mandatory object groups from
module B but might require mandatory implementation of an object
group from module B that is only conditionally mandatory with respect
to the compliance statement(s) in module B. In such cases, the
RECOMMENDED approach is for the compliance statement(s) in module A
to formally specify requirements with respect to module B via
appropriate MODULE, MANDATORY-GROUPS, GROUP, and OBJECT clauses. An
example is provided by the compliance statements in the DIFFSERV-MIB
[RFC3289], which list the ifCounterDiscontinuityGroup from IF-MIB
[RFC2863] as a mandatory group. That group is not sufficient to
satisfy any IF-MIB compliance statement, and it is conditionally
mandatory in the IF-MIB's current compliance statement ifCompliance3.
4.8.1. Note Regarding These Examples and RFC 2578
There has been some dispute as to whether syntax refinements that
restrict enumerations (RFC 2578 Section 9) are permitted with TCs, as
shown in the examples above, or are allowed only with the base types
Heard Best Current Practice [Page 27]
RFC 4181 Guidelines for MIB Documents September 2005
INTEGER and BITS, as suggested by a strict reading of RFC 2578. The
rough consensus of the editors of the SMIv2 documents and the current
pool of MIB reviewers is that they should be allowed with TCs. MIB
module authors should be aware that some MIB compilers follow the
strict reading of RFC 2578 and require that the TC be replaced by its
base type (INTEGER or BITS) when enumerations are refined. That
usage is legal, and it can be found in some older MIB modules such as
the IF-MIB [RFC2863].
4.9. Revisions to MIB Modules
RFC 2578 Section 10 specifies general rules that apply any time a MIB
module is revised. Specifically:
- The MODULE-IDENTITY invocation MUST be updated to include
information about the revision. In particular, the LAST-UPDATED
clause value MUST be set to the revision time, a REVISION clause
with the same UTC time and an associated DESCRIPTION clause
describing the changes MUST be added, and any obsolete information
in the existing DESCRIPTION, ORGANIZATION, and CONTACT-INFO clauses
MUST be replaced with up-to-date information. See Section 4.5
above for additional requirements that apply to MIB modules that
are under IETF change control.
- On the other hand, the module name MUST NOT be changed (except to
correct typographical errors), existing definitions (even obsolete
ones) MUST NOT be removed from the MIB module, and descriptors and
OBJECT IDENTIFIER values associated with existing definitions MUST
NOT be changed or re-assigned.
It is important to note that the purpose in forbidding certain kinds
of changes is to ensure that a revised MIB module is compatible with
fielded implementations based on previous versions of the module.
There are two distinct aspects of this backward-compatibility
requirement. One is "over the wire" compatibility of agent and
manager implementations that are based on different revisions of the
MIB module. The other is "compilation" compatibility with MIB
modules that import definitions from the revised MIB module. The
rules forbidding changing or re-assigning OBJECT IDENTIFIER values
are necessary to ensure "over the wire" compatibility; the rules
against changing module names or descriptors or removing obsolete
definitions are necessary to ensure compilation compatibility.
RFC 2578 Section 10.2 specifies rules that apply to revisions of
object definitions. The following guidelines correct some errors in
these rules and provide some clarifications:
Heard Best Current Practice [Page 28]
RFC 4181 Guidelines for MIB Documents September 2005
- Bullet (1) allows the labels of named numbers and named bits in
SYNTAX clauses of type enumerated INTEGER or BITS to be changed.
This can break compilation compatibility, since those labels may be
used by DEFVAL clauses in modules that import the definitions of
the affected objects. Therefore, labels of named numbers and named
bits MUST NOT be changed when revising IETF MIB modules (except to
correct typographical errors), and they SHOULD NOT be changed when
revising enterprise MIB modules.
- Although not specifically permitted in bullets (1) through (8), it
is generally considered acceptable to add range constraints to the
SYNTAX clause of an integer-valued object, provided that the
constraints simply make explicit some value restrictions that were
implicit in the definition of the object. The most common example
is an auxiliary object with a SYNTAX of INTEGER or Integer32 with
no range constraint. Since an auxiliary object is not permitted to
assume negative values, adding the range constraint (0..2147483647)
cannot possibly result in any "over the wire" change, nor will it
cause any compilation compatibility problems with a correctly
written MIB module. Such a change SHOULD be treated by a reviewer
as an editorial change, not as a semantic change. Similarly,
removal of a range or size constraint from an object definition
when that range or size constraint is enforced by the underlying
data type SHOULD be treated by a reviewer as an editorial change.
RFC 2578 Section 10.3 specifies rules that apply to revisions of
notification definitions. No clarifications or corrections are
required.
RFC 2579 Section 5 specifies rules that apply to revisions of textual
convention definitions. The following guideline corrects an error in
these rules:
- Bullet (1) allows the labels of named numbers and named bits in
SYNTAX clauses of type enumerated INTEGER or BITS to be changed.
This can break compilation compatibility, since those labels may be
used by DEFVAL clauses in modules that import the definitions of
the affected TCs. Therefore, labels of named numbers and named
bits MUST NOT be changed when revising IETF MIB modules (except to
correct typographical errors), and they SHOULD NOT be changed when
revising enterprise MIB modules.
RFC 2580 Section 7.1 specifies rules that apply to revisions of
conformance groups. Two point are worth reiterating:
Heard Best Current Practice [Page 29]
RFC 4181 Guidelines for MIB Documents September 2005
- Objects and notifications MUST NOT be added to or removed from an
existing object group or notification group. Doing so could cause
a compilation failure or (worse) a silent change in the meaning of
a compliance statement or capabilities statement that refers to
that group.
- The status of a conformance group is independent of the status of
its members. Thus, a current group MAY refer to deprecated objects
or notifications. This may be desirable in certain cases, e.g., a
set of widely-deployed objects or notifications may be deprecated
when they are replaced by a more up-to-date set of definitions, but
the conformance groups that contain them may remain current in
order to encourage continued implementation of the deprecated
objects and notifications.
RFC 2580 Section 7.2 specifies rules that apply to revisions of
compliance statements. The following guidelines correct an omission
from these rules and emphasize one important point:
- RFC 2580 should (but does not) recommend that an OBJECT clause
specifying support for the original set of values be added to a
compliance statement when an enumerated INTEGER object or a BITS
object referenced by the compliance statement has enumerations or
named bits added, assuming that no such clause is already present
and that the effective MIN-ACCESS value is read-write or read-
create. This is necessary in order to avoid a silent change to the
meaning of the compliance statement. MIB module authors and
reviewers SHOULD watch for this to ensure that such OBJECT clauses
are added when needed. Note that this may not always be possible
to do, since affected compliance statements may reside in modules
other than the one that contains the revised definition(s).
- The status of a compliance statement is independent of the status
of its members. Thus, a current compliance statement MAY refer to
deprecated object groups or notification groups. This may be
desirable in certain cases, e.g., a set of widely-deployed object
or notification groups may be deprecated when they are replaced by
a more up-to-date set of definitions, but compliance statements
that refer to them may remain current in order to encourage
continued implementation of the deprecated groups.
RFC 2580 Section 7.3 specifies rules that apply to revisions of
capabilities statements. The following guideline corrects an
omission from these rules:
- RFC 2580 should (but does not) recommend that VARIATION clauses
specifying support for the original set of values be added to a
capabilities statement when enumerated INTEGER objects or BITS
Heard Best Current Practice [Page 30]
RFC 4181 Guidelines for MIB Documents September 2005
objects referenced by the capabilities statement have enumerations
added, assuming that no such clauses are already present. This is
necessary in order to avoid a silent change to the meaning of the
capabilities statement.
In certain exceptional situations, the cost of strictly following the
SMIv2 rules governing MIB module revisions may exceed the benefit.
In such cases, the rules can be waived, but when that is done both
the change and the justification for it MUST be thoroughly
documented. One example is provided by Section 3.1.5 of RFC 2863,
which documents the semantic change that was made to ifIndex in the
transition from MIB-II [RFC1213] to the IF-MIB [RFC2863] and provides
a detailed justification for that change. Another example is
provided by the REVISION clause of the SONET-MIB [RFC2558] that
documents raising the MAX-ACCESS of several objects to read-write
while adding MIN-ACCESS of read-only for compatibility with the
previous version [RFC1595].
Authors and reviewers may find it helpful to use tools that can list
the differences between two revisions of a MIB module. Please see
http://www.ops.ietf.org/mib-review-tools.html for more information.
5. Acknowledgments
Most of the material on usage of data types was based on input
provided by Bert Wijnen with assistance from Keith McCloghrie, David
T. Perkins, and Juergen Schoenwaelder. Much of the other material on
SMIv2 usage was taken from an unpublished guide for MIB authors and
reviewers by Juergen Schoenwaelder. Some of the recommendations in
these guidelines are based on material drawn from the on-line SMIv2
errata list at http://www.ibr.cs.tu-bs.de/ietf/smi-errata/. Thanks
to Frank Strauss and Juergen Schoenwaelder for maintaining that list
and to the contributors who supplied the material for that list.
Finally, thanks are due to the following individuals whose comments
on earlier versions of this memo contained many valuable suggestions
for additions, clarifications, and corrections: Andy Bierman, Bob
Braden, Michelle Cotton, David Harrington, Harrie Hazewinkel,
Dinakaran Joseph, Michael Kirkham, Keith McCloghrie, David T.
Perkins, Randy Presuhn, Dan Romascanu, Juergen Schoenwaelder, Frank
Strauss, Dave Thaler, and Bert Wijnen.
Heard Best Current Practice [Page 31]
RFC 4181 Guidelines for MIB Documents September 2005
6. Security Considerations
Implementation and deployment of a MIB module in a system may result
in security risks that would not otherwise exist. It is important
for authors and reviewers of documents that define MIB modules to
ensure that those documents fully comply with the guidelines in
http://www.ops.ietf.org/mib-security.html so that all such risks are
adequately disclosed.
7. IANA Considerations
This document affects the IANA to the extent that it describes what
is required to be present in the IANA Considerations section of a MIB
document, but it does not require that the IANA update any existing
registry or create any new registry.
Heard Best Current Practice [Page 32]
RFC 4181 Guidelines for MIB Documents September 2005
Appendix A: MIB Review Checklist
The purpose of a MIB review is to review the MIB module both for
technical correctness and for adherence to IETF documentation
requirements. The following checklist may be helpful when reviewing
a draft document:
1.) I-D Boilerplate -- verify that the draft contains the required
Internet-Draft boilerplate (see http://www.ietf.org/ietf/1id-
guidelines.txt), including the appropriate statement to permit
publication as an RFC, and that I-D boilerplate does not contain
references or section numbers.
2.) Abstract -- verify that the abstract does not contain references,
that it does not have a section number, and that its content follows
the guidelines in http://www.ietf.org/ietf/1id-guidelines.txt.
3.) MIB Boilerplate -- verify that the draft contains the latest
approved SNMP Network Management Framework boilerplate from the OPS
area web site (http://www.ops.ietf.org/mib-boilerplate.html).
4.) Security Considerations Section -- verify that the draft uses the
latest approved template from the OPS area web site
(http://www.ops.ietf.org/mib-security.html) and that the guidelines
therein have been followed.
5.) IANA Considerations Section -- this section must always be
present. If the draft requires no action from the IANA, ensure that
this is explicitly noted. If the draft requires OID values to be
assigned, ensure that the IANA Considerations section contains the
information specified in Section 3.5 of these guidelines. If the
draft contains the initial version of an IANA-maintained module,
verify that the MODULE-IDENTITY invocation contains maintenance
instructions that comply with the requirements in RFC 2434. In the
latter case, the IANA Considerations section that will appear in the
RFC MUST contain a pointer to the actual IANA-maintained module.
6.) References -- verify that the references are properly divided
between normative and informative references, that RFC 2119 is
included as a normative reference if the terminology defined therein
is used in the document, that all references required by the
boilerplate are present, that all MIB modules containing imported
items are cited as normative references, and that all citations point
to the most current RFCs unless there is a valid reason to do
otherwise (for example, it is OK to include an informative reference
to a previous version of a specification to help explain a feature
included for backward compatibility).
Heard Best Current Practice [Page 33]
RFC 4181 Guidelines for MIB Documents September 2005
7.) Copyright Notices -- verify that the draft contains an
abbreviated copyright notice in the DESCRIPTION clause of each
MODULE-IDENTITY invocation and that it contains the full copyright
notice and disclaimer specified in Sections 5.4 and 5.5 of RFC 3978
at the end of the document. Make sure that the correct year is used
in all copyright dates.
8.) IPR Notice -- if the draft does not contains a verbatim copy of
the IPR notice specified in Section 5 of RFC 3979, recommend that the
IPR notice be included.
9.) Other Issues -- check for any issues mentioned in
http://www.ietf.org/ID-Checklist.html that are not covered elsewhere.
10.) Technical Content -- review the actual technical content for
compliance with the guidelines in this document. The use of a MIB
compiler is recommended when checking for syntax errors; see
http://www.ops.ietf.org/mib-review-tools.html for more information.
Checking for correct syntax, however, is only part of the job. It is
just as important to actually read the MIB document from the point of
view of a potential implementor. It is particularly important to
check that DESCRIPTION clauses are sufficiently clear and unambiguous
to allow interoperable implementations to be created.
Appendix B: Commonly Used Textual Conventions
The following TCs are defined in SNMPv2-TC [RFC2579]:
DisplayString OCTET STRING (SIZE (0..255))
PhysAddress OCTET STRING
MacAddress OCTET STRING (SIZE (6))
TruthValue enumerated INTEGER
TestAndIncr INTEGER (0..2147483647)
AutonomousType OBJECT IDENTIFIER
VariablePointer OBJECT IDENTIFIER
RowPointer OBJECT IDENTIFIER
RowStatus enumerated INTEGER
TimeStamp TimeTicks
TimeInterval INTEGER (0..2147483647)
DateAndTime OCTET STRING (SIZE (8 | 11))
StorageType enumerated INTEGER
TDomain OBJECT IDENTIFIER
TAddress OCTET STRING (SIZE (1..255))
Note 1. InstancePointer is obsolete and MUST NOT be used.
Note 2. DisplayString does not support internationalized text. It
MUST NOT be used for objects that are required to hold
Heard Best Current Practice [Page 34]
RFC 4181 Guidelines for MIB Documents September 2005
internationalized text (which is always the case if the
object is intended for use by humans [RFC2277]). Designers
SHOULD consider using SnmpAdminString, Utf8String, or
LongUtf8String for such objects.
Note 3. TDomain and TAddress SHOULD NOT be used in new MIB modules.
The TransportDomain, TransportAddressType, and
TransportAddress TCs (defined in TRANSPORT-ADDRESS-MIB
[RFC3419]) SHOULD be used instead.
The following TC is defined in SNMP-FRAMEWORK-MIB [RFC3411]:
SnmpAdminString OCTET STRING (SIZE (0..255))
The following TCs are defined in SYSAPPL-MIB [RFC2287]:
Utf8String OCTET STRING (SIZE (0..255))
LongUtf8String OCTET STRING (SIZE (0..1024))
The following TCs are defined in INET-ADDRESS-MIB [RFC4001]:
InetAddressType enumerated INTEGER
InetAddress OCTET STRING (SIZE (0..255))
InetAddressPrefixLength Unsigned32 (0..2040)
InetPortNumber Unsigned32 (0..65535))
InetAutonomousSystemNumber Unsigned32
InetScopeType enumerated INTEGER
InetZoneIndex Unsigned32
InetVersion enumerated INTEGER
The following TCs are defined in TRANSPORT-ADDRESS-MIB [RFC3419]:
TransportDomain OBJECT IDENTIFIER
TransportAddressType enumerated INTEGER
TransportAddress OCTET STRING (SIZE (0..255))
The following TC is defined in RMON2-MIB [RFC2021]:
ZeroBasedCounter32 Gauge32
The following TCs are defined in HCNUM-TC [RFC2856]:
ZeroBasedCounter64 Counter64
CounterBasedGauge64 Counter64
The following TCs are defined in IF-MIB [RFC2863]:
InterfaceIndex Integer32 (1..2147483647)
Heard Best Current Practice [Page 35]
RFC 4181 Guidelines for MIB Documents September 2005
InterfaceIndexOrZero Integer32 (0..2147483647)
The following TCs are defined in ENTITY-MIB [RFC4133]:
PhysicalIndex Integer32 (1..2147483647)
PhysicalIndexOrZero Integer32 (0..2147483647)
The following TCs are defined in PerfHist-TC-MIB [RFC3593]:
PerfCurrentCount Gauge32
PerfIntervalCount Gauge32
PerfTotalCount Gauge32
The following TCs are defined in HC-PerfHist-TC-MIB [RFC3705]:
HCPerfValidIntervals Integer32 (0..96)
HCPerfInvalidIntervals Integer32 (0..96)
HCPerfTimeElapsed Integer32 (0..86399)
HCPerfIntervalThreshold Unsigned32 (0..900)
HCPerfCurrentCount Counter64
HCPerfIntervalCount Counter64
HCPerfTotalCount Counter64
Appendix C: Suggested Naming Conventions
Authors and reviewers of IETF MIB modules have often found the
following naming conventions to be helpful in the past, and authors
of new IETF MIB modules are urged to consider following them.
- The module name should be of the form XXX-MIB (or XXX-TC-MIB for a
module with TCs only), where XXX is a unique prefix (usually all
caps with hyphens for separators) that is not used by any existing
module. For example, the module for managing optical interfaces
[RFC3591] uses the prefix OPT-IF and has module name OPT-IF-MIB.
- The descriptor associated with the MODULE-IDENTITY invocation
should be of the form xxxMIB, xxxMib, or xxxMibModule, where xxx is
a mixed-case version of XXX starting with a lowercase letter and
without any hyphens. For example, the OPT-IF-MIB uses the prefix
optIf, and the descriptor associated with its MODULE-IDENTITY
invocation is optIfMibModule.
- Other descriptors within the MIB module should start with the same
prefix xxx. OPT-IF-MIB uses the prefix optIf for all descriptors.
Heard Best Current Practice [Page 36]
RFC 4181 Guidelines for MIB Documents September 2005
- Names of TCs that are specific to the MIB module and names of
SEQUENCE types that are used in conceptual table definitions should
start with a prefix Xxx that is the same as xxx but with the
initial letter changed to uppercase. OPT-IF-MIB uses the prefix
OptIf on the names of TCs and SEQUENCE types.
- The descriptor associated with a conceptual table should be of the
form xxxZzzTable; the descriptor associated with the corresponding
conceptual row should be of the form xxxZzzEntry; the name of the
associated SEQUENCE type should be of the form XxxZzzEntry; and the
descriptors associated with the subordinate columnar objects should
be of the form xxxZzzSomeotherName. An example from the OPT-IF-MIB
is the OTMn table. The descriptor of the table object is
optIfOTMnTable, the descriptor of the row object is optIfOTMnEntry,
the name of the associated SEQUENCE type is OptIfOTMnEntry, and the
descriptors of the columnar objects are optIfOTMnOrder,
optIfOTMnReduced, optIfOTMnBitRates, optIfOTMnInterfaceType,
optIfOTMnTcmMax, and optIfOTMnOpticalReach.
- When abbreviations are used, then they should be used consistently.
Inconsistent usage such as
xxxYyyDestAddr
xxxZzzDstAddr
should be avoided.
Appendix D: Suggested OID Layout
As noted in RFC 2578 Section 5.6, it is common practice to use the
value of the MODULE-IDENTITY invocation as a subtree under which
other OBJECT IDENTIFIER values assigned within the module are
defined. That, of course, leaves open the question of how OIDs are
assigned within that subtree. One assignment scheme that has gained
favor -- and that is RECOMMENDED unless there is a specific reason
not use it -- is to have three separate branches immediately below
the MODULE-IDENTITY value dedicated (respectively) to notification
definitions, object definitions, and conformance definitions, and to
further subdivide the conformance branch into separate sub-branches
for compliance statements and object/notification groups. This
structure is illustrated below, with naming conventions following
those outlined in Appendix C. The numbers in parentheses are the
sub-identifiers assigned to the branches.
Heard Best Current Practice [Page 37]
RFC 4181 Guidelines for MIB Documents September 2005
xxxMIB
|
+-- xxxNotifications(0)
+-- xxxObjects(1)
+-- xxxConformance(2)
|
+-- xxxCompliances(1)
+-- xxxGroups(2)
When using this scheme, notification definition values are assigned
immediately below the xxxNotifications node. This ensures that each
OID assigned to a notification definition has a next-to-last sub-
identifier of zero, which is REQUIRED by Section 4.7 above. The
other sub-branches may have additional sub-structure, but none beyond
that specified in Section 4.6.5 above is actually required.
One example of a MIB module whose OID assignments follow this scheme
is the POWER-ETHERNET-MIB [RFC3621].
Normative References
[RFC2578] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case,
J., Rose, M., and S. Waldbusser, "Structure of
Management Information Version 2 (SMIv2)", STD 58, RFC
2578, April 1999.
[RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case,
J., Rose, M., and S. Waldbusser, "Textual Conventions
for SMIv2", STD 58, RFC 2579, April 1999.
[RFC2580] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case,
J., Rose, M., and S. Waldbusser, "Conformance Statements
for SMIv2", STD 58, RFC 2580, April 1999.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirements Levels", BCP 14, RFC 2119, March 1997.
[RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group
MIB", RFC 2863, June 2000.
[RFC2864] McCloghrie, K. and G. Hanson, "The Inverted Stack Table
Extension to the Interfaces Group MIB", RFC 2864, June
2000.
[RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 2434,
October 1998.
Heard Best Current Practice [Page 38]
RFC 4181 Guidelines for MIB Documents September 2005
[RFC3978] Bradner, S., "IETF Rights in Contributions", BCP 78, RFC
3978, March 2005.
[RFC3979] Bradner, S., "Intellectual Property Rights in IETF
Technology", BCP 79, RFC 3979, March 2005.
[RFC4001] Daniele, M., Haberman, B., Routhier, S., and J.
Schoenwaelder, "Textual Conventions for Internet Network
Addresses", RFC 4001, February 2005.
[RFC3593] Tesink, K., "Textual Conventions for MIB Modules Using
Performance History Based on 15 Minute Intervals", RFC
3593, September 2003.
[RFC3705] Ray, B. and R. Abbi, "High Capacity Textual Conventions
for MIB Modules Using Performance History Based on 15
Minute Intervals", RFC 3705, February 2004.
[RFC2021] Waldbusser, S., "Remote Network Monitoring Management
Information Base Version 2 using SMIv2", RFC 2021,
January 1997.
[RFC2856] Bierman, A., McCloghrie, K., and R. Presuhn, "Textual
Conventions for Additional High Capacity Data Types",
RFC 2856, June 2000.
[RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An
Architecture for Describing Simple Network Management
Protocol (SNMP) Management Frameworks", STD 62, RFC
3411, December 2002.
[RFC2287] Krupczak, C. and J. Saperia, "Definitions of
System-Level Managed Objects for Applications", RFC
2287, February 1998.
[RFC3418] Presuhn, R., Case, J., McCloghrie, K., Rose, M., and S.
Waldbusser, "Management Information Base (MIB) for the
Simple Network Management Protocol (SNMP)", STD 62, RFC
3418, December 2002.
[RFC3416] Presuhn, R., Case, J., McCloghrie, K., Rose, M., and S.
Waldbusser, "Protocol Operations for the Simple Network
Management Protocol (SNMP)", STD 62, RFC 3416, December
2002.
[RFC4133] Bierman, A. and K. McCloghrie, "Entity MIB (Version 3)",
RFC 4133, August 2005.
Heard Best Current Practice [Page 39]
RFC 4181 Guidelines for MIB Documents September 2005
[RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
Languages", BCP 18, RFC 2277, January 1998.
[RFC3419] Daniele, M. and J. Schoenwaelder, "Textual Conventions
for Transport Addresses", RFC 3419, December 2002.
Informative References
[RFC1155] Rose, M. and K. McCloghrie, "Structure and
Identification of Management Information for
TCP/IP-based Internets", STD 16, RFC 1155, May 1990.
[RFC1212] Rose, M. and K. McCloghrie, "Concise MIB Definitions",
STD 16, RFC 1212, March 1991.
[RFC1215] Rose, M., "A Convention for Defining Traps for use with
the SNMP", RFC 1215, March 1991.
[RFC2223bis] Reynolds, J. and R. Braden, "Instructions to Request for
Comments (RFC) Authors", Work in Progress, August 2004.
[RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart,
"Introduction and Applicability Statements for
Internet-Standard Management Framework", RFC 3410,
December 2002.
[RFC2932] McCloghrie, K., Farinacci, D., and D. Thaler, "IPv4
Multicast Routing MIB", RFC 2932, October 2000.
[RFC1573] McCloghrie, K. and F. Kastenholz, "Evolution of the
Interfaces Group of MIB-II", RFC 1573, January 1994.
[RFC3621] Berger, A. and D. Romascanu, "Power Ethernet MIB", RFC
3621, December 2003.
[RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen,
"Coexistence between Version 1, Version 2, and Version 3
of the Internet-standard Network Management Framework",
BCP 74, RFC 3584, August 2003.
[RFC2108] de Graaf, K., Romascanu, D., McMaster, D., and K.
McCloghrie, "Definitions of Managed Objects for IEEE
802.3 Repeater Devices using SMIv2", RFC 2108, February
1997.
[RFC3289] Baker, F., Chan, K., and A. Smith, "Management
Information Base for the Differentiated Services
Architecture", RFC 3289, May 2002.
Heard Best Current Practice [Page 40]
RFC 4181 Guidelines for MIB Documents September 2005
[RFC1213] McCloghrie, K. and M. Rose, "Management Information Base
for Network Management of TCP/IP-based internets - MIB-
II", STD 17, RFC 1213, March 1991.
[RFC1595] Brown, T. and K. Tesink, "Definitions of Managed Objects
for the SONET/SDH Interface Type", RFC 1595, March 1994.
[RFC2558] Tesink, K., "Definitions of Managed Objects for the
SONET/SDH Interface Type", RFC 2558, March 1999.
[RFC3591] Lam, H-K., Stewart, M., and A. Huynh, "Definitions of
Managed Objects for the Optical Interface Type", RFC
3591, September 2003.
Editor's Address
C. M. Heard
158 South Madison Ave. #207
Pasadena, CA 91101-2569
USA
Phone: +1 626 795 5311
EMail: heard@pobox.com
Heard Best Current Practice [Page 41]
RFC 4181 Guidelines for MIB Documents September 2005
Full Copyright Statement
Copyright (C) The Internet Society (2005).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at ietf-
ipr@ietf.org.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Heard Best Current Practice [Page 42]