Protocol Registration Procedures

How to Write an IANA Considerations Section

When writing an Internet-Draft, authors are required to include a section called “IANA Considerations.” This section should consist of (and, if possible, be limited to) a set of instructions for the IANA.

Whether you want to create a registry, register a parameter, or modify an existing object, our primary concern is that the request in the IANA Considerations section be clear, complete, and valid.

RFC 8126 is the authoritative document on this topic, but this page is meant to function as a quick reference that can provide additional practical guidance.

If you're not sure whether you need to create a registry or register any parameters, please reach out to your Working Group or Area Director (if you're writing an IETF-stream document) for advice. If you're writing an independent-stream document, please contact the Independent Stream Editor or experts in your area.

Glossary

  • Early Allocation: IANA normally takes its actions when a document is approved for publication. There are times, though, when early allocation of a value is important for the development of a technology. Whether the early allocation is temporary or permanent depends on the registry’s registration procedure. RFC 7120 describes temporary early allocations.

  • Registry category: A category at in our Protocol Parameter Matrix, like the “Border Gateway Protocol (BGP) Parameters” category that includes the Capability Codes registry. Categories occasionally comprise more than one registry page. In the future, registries may be filed in more than one category.

  • Registry page: A web page or file that contains registries and sub-registries.

  • Registration template: A registration request form provided in an RFC or submitted to us in accordance with an RFC.

  • Registry vs. sub-registry: Sub-registries are associated with specific registrations. A registry called “Error Codes,” for example, might be followed by a sub-registry called “Subcodes for Error Code 1.”

  • Reserved: Not available for assignment. Reserved values can be made available through redefinition in an RFC.

  • Unassigned: Available for assignment.

Typical Questions and Helpful Answers

Creating a New Registry Through an Internet-Draft

What If There Are No Registry Actions?

Is there a genuine need for a publicly-maintained registry outside of the RFC? Could an existing registry be used instead?

If you don’t need to register/create/modify anything maintained by IANA, your IANA Considerations section should confirm that fact by saying something like “This document does not require any registry actions.” While you can instruct the RFC Editor to remove it after approval, but we strongly recommend keeping it, so as to assure future readers that no registrations were missed.

How Do I Create a New Registry?

If you need to create a registry, the IANA Considerations section must provide its name, registration procedure(s), field names, range of available numeric values (where appropriate), and initial contents (if any). Below are some examples of common registry formats and a list of questions to answer before you write your section.

Are There Good Examples of How to Create a New Registry?

Yes! Most registries consist of one, two, or three fields/columns, although a few include as many as 12. Some registries also include links to text files. Here are some examples:

What Should I Call the New Registry?

When you think about naming the new registry, be as precise as you can be. Don’t use a generic name like “Codepoints for Foobar.” Instead, provide the precise name of the registry. It will appear online and in search engines, so it’s important that the name is descriptive and not an approximation.

Also, consider whether related registries use a standard naming format (hyphens, capitalization, abbreviations, references to a value). Are there registries that are in place for the same protocol that existing implementers are familiar with?

Where Should My New Registry be Located?

There are two good choices for the location of a new registry: first, within an existing category (or “registry page”) on the IANA Matrix, or in a new category created by the IANA Considerations section of your draft. It’s helpful to implementers and protocol designers to have registries for similar purposes grouped together. However, completely new protocols are good candidates for brand-new registry pages that will collect the parameters and registries for the new protocol.

How Should I Choose the Registration Procedure for the New Registry?

One thing to think about is how hard (or how easy) it should be to make changes and additions to the new registry. Setting the registration procedure determines how difficult the review process is before changes are made to the registry.

The most common registration procedures are defined in RFC 8126. Examples of widely used registration procedures are:

  • First Come First Served
  • Expert Review
  • Specification Required (this procedure includes Expert Review)
  • RFC Required
  • IETF Review
  • IESG Approval

What Happens if Different Value Ranges Call for Different Registration Procedures?

No problem! In your document, just precisely describe each range and the registration procedure that applies. A good example of this is in the BGP Layer 2 TLV Types registry, which gives protocol designers the ability to allocate TLV Types from three separate ranges.

Remember that if you have different value ranges in your registry, you must account for all the values in the registry. For example, if your registry is for an 8-bit value, make sure that the value ranges cover all of the values from 0 to 255.

Should I Give Experts Guidance for Expert Review?

If you choose Expert Review or Specification Required as the registration procedure for your new registry, it can be helpful to provide guidance to the “expert.” The idea is to provide the expert with guidance on naming, allocation and other issues related to the protocol registry. Sometimes Internet-Draft authors include the guidance directly in the draft. Other times, a Working Group will decide to collect guidance for a group of protocols together (for instance, see the PWE3 working group in RFC 4446).

It’s good practice to give expert guidance because it not only helps the expert, but it also helps the protocol designer understand the circumstances under which they can request a new registration in your new registry.

What Should I Use as the Names for Fields in the Registry?

The simplest registries have only a single value and a reference to where the value was defined. Complex registries have multiple fields and even subregistries. In each case, each field for the registry should have names that are brief and descriptive. Fields that are specific to a particular protocol may (but are not required to) include the protocol in the field name.

What About Using Registration Templates?

Some registries use a registration template for additions or changes to values in a registry. The value of a template is that, when sharing with a mailing list or designated expert, the information provided by a template insures that it is consistent, has considered all the requirements of the registry and clearly complies with the registration requirements of the new registry.

Sometimes, a registry will have a template that contains more information than will actually appear in the registry. Using a template in this way allows for the registrant to communicate contextual information about the registration. This might help communicate the purpose or intent of the registration beyond the actual information being recorded in the registry.

Several registries are set up so that a user of the registry can see the template by clicking on the appropriate link in the registry. In this way, a protocol designer or application builder can see the full template, and all the information provided by the registrant, that is associated with the registration (e.g. Media Types).

What If I Want to Have Numerical Values in my New Registry?

For numeric assignments, you should specify whether the values are to be recorded in decimal, hexadecimal or some other format. It is always helpful to indicate for the format and range of values. When a number is being used, it is important to specify how all the values are to be used, including “zero” and the maximum value of the range. The maximum available value for the registry is determined by the range (for instance, an 8-bit value has a range of 0-255 and a maximum value of 255).

It is important to take care with the minimum and maximum values in a numerical registry. For instance, if value 0 (zero) won't be assigned by your document, should it be listed as “Unassigned” (available), listed as “Reserved” (unavailable), or left out of the registry?

What If I Want to Have Strings in my New Registry?

Strings are very common in registries and are expected to be ASCII, and it should be clearly specified whether case matters, and whether, for example, strings should be shown in the registry in uppercase or lowercase. It is important to consider whether or not the registry should be alphabetized on its initial creation and have all subsequent entries placed in alphabetical order.

Strings that represent protocol parameters may rarely, if ever need to contain non-ASCII characters. But if they do, instructions should make it very clear that they are allowed and that the non-ASCII characters should be represented as Unicode characters using the "(U+XXXX)" convention. If you are thinking of creating a registry with non-ASCII characters, consider the guidance given in RFC 8126 and RFC 7564.

What About Reserving Other Ranges of Values in the New Registry?

It’s possible and common to reserve ranges of values in a registry. RFC 8126 provides guidance on this, and examples of common names are "Private Use" and "Experimental Use."

What About Special Registry Features?

If the registry procedure isn't Expert Review or Specification Required, you may wish to provide guidance about any special formatting or text requirements. If there are special features or conventions in the registry, it is very helpful to describe the requirements clearly and consider whether a note at the top of the registry would be appropriate. That note will help guide future protocol designers when they attempt to register new values in the registry.

In the recent past, it's been suggested to us that authors might consider requiring naming schemes that can be used in the C programming language: underscores, letters, and digits only, with no spaces or other characters.

Authors could also consider whether it would be appropriate to include a "Status" column, and if so, where in the registry it should appear (e.g. after "Value," before "Reference," etc.).

Lists Versus Tables

In your document, please use lists or tables to present the contents of registries that contain multiple values or when requesting multiple values in an existing registry. For an example of an IANA Considerations section that uses tables, see RFC 6940. For an example that uses lists, see RFC 5804. Alternatively, see the suggested boilerplate below.

Adding Registrations in an Existing Registry Through an Internet-Draft

How Do I Request a New Registration in an Existing Registry?

  • Provide the text you want to see in the registry, including preferred case (upper or lower) and punctuation (if any).
  • Make sure you haven't missed a new field, like the "Mux Category" column that was recently added to existing registries at http://www.iana.org/assignments/sdp-parameters.
  • New values to be registered in an existing registry should be described as "TBD1," "TBD2," etc. Desired values can be described as "suggested value X," but authors should be aware that IANA does not keep a list of suggested values and cannot guarantee that those values will be assigned. If a specific value is desired, authors may wish to investigate early allocation.

Can I Request Registrations Outside the IANA Considerations Section?

If the IANA Considerations section says "See Section X for new registrations," that section should present the registrations in a clearly-marked list or table.

How Should I Communicate the URL for an Existing Registry?

If you include the URL for an existing registry, please use the “short version” that doesn’t include a file extension or extra path information. i.e. Use http://www.iana.org/assignments/iax-parameters not http://www.iana.org/assignments/iax-parameters/iax-parameters.xhtml. Long term stability of specific file-formats is not guaranteed and will evolve over time.

How Do I Request Specific Values?

Documents can suggest specific values for new registrations, but we can’t promise that those values will still be available by the time the document is approved. There is an early allocation process available, but there is no reservation system.

If you need a specific value, and the registration procedure in question is First Come First Served or Expert Review, you can request permanent registration at any time by using the relevant application form or by sending an email to iana@iana.org. (Experts may, however, suggest putting off approval until later in the process.)

Can I Get an Early Allocation Before My Document Becomes an RFC?

If the registry is maintained via the Standards Action, IETF Review, RFC Required, or Specification Required procedure, the document may be eligible to receive an early allocation, as defined in RFC 7120. Early allocations of this type are marked “TEMPORARY” in the registry and are subject to expiration if the document is not approved within a certain period, although renewals are possible. Early allocation requests should be submitted to us by the Working Group chair or sponsoring AD, as described in Section 3.

Some experts may choose to permit permanent early registration in Specification Required registries, as with Expert Review requests.

Changing the Structure of an Existing Registry

  • Adding a column to an existing registry typically requires a document.
  • Documents that do so typically either a) provide data necessary to populate that column for pre-existing registrations or b) indicate that the field can be left blank for those registrations.
  • We'll list the document as an additional reference for the registry. The document can instruct us to list it as an additional reference for the registrations it modifies as well, but we don't require this.

How do I Modify Existing Registrations?

  • Provide the name of the registry and the name of the registration as they appear online.
  • Should we replace the current reference or list your document as an additional reference?
  • If you’re writing a bis document, please note whether we should replace all references to the previous document in the registries. If there are any exceptions, note them here.
  • Some bis documents reproduce the IANA Considerations section from the previous document. If you do this, please include an introductory sub-section that notes whether you’re adding any additional actions or asking us to leave any of the original references intact.
  • If you’re asking us to keep a reference to an obsolete document, consider whether the registration should be listed as deprecated/obsoleted as well.

A Brief Guide to IANA’s Internet-Draft Workflow

Timing

  • Last Call: Unless we’re asked for an early review (note: send early review requests to iana@iana.org), we first become aware of an IETF-stream I-D during its IETF Last Call. We send our review to the document’s draft-string-all@ietf.org alias and the IESG and set an “IANA review state” in the Datatracker. We don’t review technical content. We're checking that the instructions are clear and can be completed as written.

  • Expert Review: If we find that the document needs an Expert Review or Specification Required registration, we ask the IESG-designated expert(s) for that registry to review and approve.

  • Evaluation: During the IESG Evaluation period, we resend any outstanding questions to the authors/chairs/ADs and notify the IESG of any remaining concerns (e.g. the actions are unclear or incomplete, the expert hasn't approved yet, the registry doesn’t allow registrations by this type of document).

  • Approval: The IESG notifies us that they’ve approved the document. We perform the actions and ask the authors to review and confirm.

  • Reference Update: The RFC Editor notifies us that they’ve assigned an RFC number. We update the registries to replace occurrences of the document’s old draft string with references to its new RFC number.

We review and complete registry actions for Independent- and IRTF-stream documents in coordination with the ISE Editor and the IRTF.

IANA Review States

  • IANA OK – Actions Needed: We understand the actions and don’t have any questions.
  • IANA OK – No Actions Needed: We understand that the document doesn’t require any actions.
  • IANA Not OK: Either we have questions/concerns, or we’re waiting for an expert review. If the latter, we’ll change the state to “IANA OK – Actions Needed” upon expert approval.
  • Version Changed - Review Needed: The IANA review state is automatically changed to “Version Changed - Review Needed” when the document is updated. We aren’t notified when this happens. Unless we’re contacted by someone associated with it, we see the document only at IETF Last Call, IESG Evaluation, and IESG approval.

Other IANA Questions

Q: Can IANA tell me what I need to register, or how many columns should appear in the registry?

A: We can’t advise you on which registration procedures you should apply, whether any ranges or values should be listed as “Reserved,” or any other technical issues.

Q: I want to create a mailing list for an Expert Review registry. What does the IANA Service Operator need to know?

A: Should a mailing list review have a specific duration? Should the mailing list be public, or open to experts only? How can this procedure avoid requiring IANA to monitor a mailing list? For examples, see Section 17 of RFC 8447 and Section 10.1 of RFC 7519.

Mailing lists are usually hosted by the IETF. The document can request a name for the mailing list.

Q: What if my new registry is going to attract an unusual number of registrations?

A: Please contact us as soon as you can. This may require consultation with the IESG as well as additional work on our end to ensure that we have the appropriate resources in place.

For context, a registry that consistently generates 10 or more registrations per month would be an unusually popular registry, and may merit its own section in our monthly performance report.

Q: How are experts designated? Should I name one in the document?

A: If you choose “Expert Review” or “Specification Required,” the expert will be designated by the IESG (with assistance from the relevant AD). The expert(s) should not be named in the document.

Q: I’m creating an Expert Review (or First Come First Served) registry. If someone registers a codepoint, who will be able to modify that registration in the future?

If your registry is populated via the Expert Review or First Come First Served method, we'll also include a column called "Change Controller" (usually the name of an organization), which can be useful in processing future modification requests. (Unless otherwise specified, the Change Controller for registrations made by IETF-stream RFCs is the IESG.)

Q: How do I guarantee that another registry will automatically be updated when my registry is updated?

A: If it’s necessary to create a “lockstep” registry that replicates data from another registry as new registrations are made there, please tell us to include a note for the top of each registry. For an example, see the note at the top of the ifType Definitions registry:

For every ifType registration, the corresponding transmission number value should be registered or marked "Reserved." In addition, the IANAifType-MIB and iana-if-type YANG modules should be updated in accordance with RFC2863 and RFC7224, respectively.

Examples of IANA Considerations Sections in RFCs

RFCs that create registries:

An RFC that creates registries and a registration:

An RFC that creates and modifies registrations:

An RFC that modifies registries:

Boilerplate

For New Registries

Every piece of text that should appear on the registry page should also appear in the IANA Considerations section.

For IANA's purposes, if the authors don't believe the section requires any other information, the IANA Considerations could consist of a facsimile of the new registry and a short preface that provides registry maintenance instructions.

Some of the examples below cover scenarios that may not be relevant to your registry. Field names are listed as "Value," "Description," and "Reference," but the first two can be replaced and augmented as appropriate.

Example 1:
    This document is creating a registry called NAME under the new heading CATEGORY. The registration
    procedure is PROCEDURE, as defined in [RFC 8126](http://www.iana.org/go/rfc8126).
    The maximum value is VALUE. These are the initial registrations:

       Value: 0
       Description:
       Reference:

       Value: 1
       Description:
       Reference:
Example 2 (including sample entries):
    This document is creating one registry under the heading "CATEGORY 1" and one registry and
    subregistry under the heading "CATEGORY 2."

    >Section X.1
    This document is creating the following registry:

    >Registry Name: NAME
    Registry Category: CATEGORY
    Registration Procedures: PROCEDURE 1 for values 1-127, PROCEDURE 2 for values 128-240

    >The following note should be included at the top of the registry: "[TEXT HERE]"

    >Value: 0
    Description: Reserved
    Reference: this document

    >Value: 1
    Description: Example
    Reference: this document

    >Value: 2-240
    Description: Unassigned

    >Value: 241-255
    Description: Reserved for Private Use
    Reference: this document
Example 3:

Another introduction for an IANA Considerations section that creates a registry:

This document is creating a registry for NAME. This registry requires that future applicants
fill out the registration template included in SECTION X. The registration procedure is
PROCEDURE. Guidance for experts is provided in SECTION Y. Entries should be listed in the
registry in alphabetical order. The fields are "Name," "Length," and "Reference."

New Registrations

Example 1:
    This document has added the following entries to the SUB-REGISTRY of REGISTRY name at
    https://www.iana.org/assignments/example:

        Value: TBD1
        Description: DESCRIPTION
        Length: VALUE
        Reference: this document

        Value: TBD2
        Description: DESCRIPTION
        Length: VALUE
        Reference: this document
Example 2:
    This document has registered REGISTRY NAME TBD1, "NAME OF REGISTRATION." Its FIELD
    NAME is VALUE OF FIELD NAME.
Example 3:
    This document has added the following entries to the REGISTRY NAME at
    http://www.iana.org/assignments/example:

        Value: TBD1 (suggested value: 13)
        Name: NAME
        Description: DESCRIPTION
        Reference: this document

        Value: TBD2 (suggested value: 14)
        Name: NAME
        Description: DESCRIPTION
        Reference: this document

Modifying Registrations

Example 1:
    All references to RFC YYYY in the REGISTRY NAME registry have been replaced with references
    to this document, except for the reference associated with REGISTRY NAME value XX, “REGISTRATION
    NAME 1.” In addition, REGISTRY NAME value YY, “REGISTRATION NAME 2,” has been deprecated.
Example 2:
    This document is listed as an additional reference for the REGISTRY NAME registration “NAME.”
Example 3:
    The following change has been made in the REGISTRY NAME registry:

    OLD:
        Value: XX
        Description: NAME
        Reference: RFC YYYY

    NEW:    
        Value: XX
        Description: NAME
        Reference: this document
Document last revised 2020-01-03.