ARIN IRR User Guide

Before You Begin

If you have never submitted an object to the ARIN Internet Routing Registry (IRR), see the Quick Start Guide to the ARIN IRR. After your maintainer (mntner) object is created and approved, you can submit additional objects using templates available from the ARIN website.

Overview

ARIN’s IRR is a searchable database of routing policy information for networks in the ARIN region. Information is submitted to the IRR using email templates. These templates are used to create, edit, and delete routing objects in the IRR. These objects in the IRR contain routing information in a specific format.

After submitting an object, you can make modifications by sending an email with the template that includes the changed information. The automated system reads the email and processes the changes.

The main types of objects in the ARIN IRR are:

• mntnr: Defines a group or entity that creates, updates, and maintains information in the IRR for their routes. (For example, an ISP can be a maintainer.)
• route: A route object contains routing information for IPv4 address space resources.
• route6: A route6 object contains routing information for IPv6 address space resources.
• as-set: Defines a group of ASNs that are peers in the routing network.

Understanding IRR Authentication

Authentication for IRR is contained in the mntner object. When submitting additional objects to the IRR, the name of the mntner object that contains that authentication is included in the mnt-by: and mbrs-by-ref: fields inside the object. All new objects must have at least one mnt-by: attribute. Several mntner objects can be referenced by a mnt-by: attribute in a single object.

Authentication methods (which are configured in the mntner object) are described in the following sections.

MD5-PW

With MD5-PW authentication, you create an MD5-PW encrypted passphrase using a generator. ARIN provides a public MD5-PW passphrase creator to allow you to generate a passphrase. You enter a clear-text password into the generator, which returns a 128-bit hash. For example, the clear-text password secure123 returns the following hash:

$1$yarRKhzO$e4117GJV4jq1I2m4WgRSV

You include this hash in the mntner object. When additional objects submitted to the database, the clear-text password is entered, and is authenticated against that hash contained in the mntner object.

For the previously-mentioned example, the mntner object would contain the MD5-PW hash in the auth: line, as shown in the following example:

mntner: MNT-YOURORGID  
descr: Example, Inc.  
admin-c: EXAMPLE123-ARIN  
tech-c: EXAMPLE456-ARIN  
upd-to: hostmaster@example.net
mnt-nfy: hostmaster@example.net
auth: MD5-PW $1$ucVwrzQH$zyamFnmJ3XsWEnrKn2eQS/
mnt-by: MNT-YOURORGID  
referral-by: MNT-YOURORGID
changed: hostmaster@example.net 20080129  
source: ARIN

Objects that use this mntner to authenticate would include the clear-text password in the password: line, as shown in the following example:

route: 192.136.136.0/24
password: secure123
descr: American Registry for Internet Numbers
PO Box 232290
Centreville, VA 20120
US
origin: AS10745
mnt-by: MNT-ARIN
changed: hostmaster@arin.net 20080130
source: ARIN

The password line must be in the body of the email message, and must be below the first line in an object template. Note that if there is more than one object in the email, the password is only required on the first one.

PGP-KEY

PGP-KEY authentication requires additional configuration with the support of ARIN staff. If you need to use PGP-KEY, submit an Ask ARIN Help Desk ticket in ARIN Online.

MAIL-FROM

This is the weakest form of authentication and is not recommended. MAIL-FROM security compares the from: email address of an email request to the from: address listed in the mntner template. ARIN does not support the use of regular expressions in email addresses (e.g., .\*@example.com). The two from: addresses must match exactly for the template processor to accept the email request. For example, the addresses John Example <jexample@example.net> and JExample@example.net would not match.

Transitioning from MAIL-FROM to MD5-PW

ARIN recommends using MD5-PW for authentication. To transition an existing mntner object from MAIL-FROM to MD5-PW authentication:

1. Visit ftp://ftp.arin.net/pub/rr/arin.db and search (Ctrl+F or CMD+F) for your mntner object.
2. Copy this object into a text editor.
3. Remove all output line(s) with auth: in them.
4. Go to the ARIN MD5-PW passphrase creator.
   1. Enter a password. Make sure you keep this clear-text password as you will need it when sending future requests to the ARIN IRR.
   2. Submit the password to get the MD5-PW passphrase. Keep this passphrase for your records, as you may need it when interacting with the ARIN IRR in the future.

5. Add the following line to your mntner object template in the text editor:
   auth: MD5-PW <MD5-PW password>
   For example: auth: MD5-PW $1$ucVwrzQH$zyamFnmJ3XsWEnrKn2eQS/

6. In ARIN Online, use Ask ARIN to create a Help Desk ticket and choose the WHOIS/Routing Registry topic. Use “RSD mntner help” as the subject and paste the updated mntner template in plain text in the Question field. ARIN will manually process your request to update your mntner object and respond via email.

Submitting Information to the ARIN IRR

To submit information to the IRR, enter the object into a plain-text email and submit it to rr@arin.net.

Grouping Multiple Objects in an Email Submission

You can include multiple objects in an email when submitting information to the IRR. The IRR server processes the objects in the order they are listed, so be sure to list any dependent objects after the objects they reference or depend upon. The server also checks each object to ensure that it is syntactically correct and passes all required authorization checks, and that you are not deleting an object that is referenced by other objects in the database. If one of these steps fails, the object and its operation will fail as a whole.

There are no restrictions on the number of objects in an IRR update message, but there is a file size limit, so optimize the number of messages you send and the number of objects per message based on your business practices. Keep the following notes in mind:

• Every email update message will result in one acknowledgment email message returned.
• Each object in an update message may generate several notification email messages.
• If you update 1000 objects by sending 1000 emails, each containing one object, this will cause a large number of emails to be returned, so be sure your mail system can handle this volume, and that you do not trigger spam filters by originating many messages from one source.
• Acknowledgment and notification messages are not sent until all the objects in an update message have been processed.

Using Email Subject Line Keywords

You can use keywords in the subject line of the emails containing your templates. These can be used for your own reference or to contain specific keywords to configure how your objects are processed and how your response email will look. If you include both keywords and non-keywords in your subject line, place all of your keywords after keywords: or they will be ignored.

There are four keywords recognized by ARIN’s IRR, and they are not case sensitive.

• NEW: Use “new” if you want the IRR to treat all templates as new objects. If an object already exists, the IRR will include an error message in its acknowledgment of your email.
• HELP or HOWTO: Use help or howto to cause the IRR to ignore the body of your email and return information about how to query and update the database within its acknowledgment of your email.
• DIFF: Use diff to highlight changes between old and new objects for any modification templates. In the IRR’s response message, each object that has been modified will include a section specifying the changes made, followed by the old version of the full object, and the new version of the full object. The diff keyword is particularly useful when import: and export: attributes are changed in large aut-num objects. In acknowledgment and notification messages, three dashes (---) followed by a new line (\n) signifies the start of a section in the message relating to one specific object.

Creating and Updating Objects

For a full list of objects that can be submitted, see IRR Templates.

Updating a mntner Object

To update a mntner:

1. In ARIN Online, create an Ask ARIN Help Desk Ticket and choose the WHOIS/Routing Registry topic.
2. In the subject line, enter Update mntner.
3. Copy and paste the text from your original mntner template into the Question field of the ticket or attach it as a text file.
   1. Include your original MD5-PW in the auth: field.
   2. Delete any optional fields you aren’t using from the template.
   3. Make the changes you want to the fields of the mntnerthat you copied.
4. Submit the ticket.

Creating a route Object

A route object specifies the IPv4 address prefix of an interdomain route and the ASN of the autonomous system from which the route originates. To create a route object, copy and paste the route template into a plain text email. The route object must contain the following fields:

• route: The CIDR prefix of the route to be originated. Together with the origin: attribute, constitutes a primary key of the route object.
• password: Enter the clear-text password that you used when creating the MD5-PW hash for your mntner object.
• descr: A short description of the organization and location where this object is used. The description can have multiple lines. It should contain the full postal address as it exists in the ARIN registration.
• origin: The AS number from which the route will originate.
• mnt-by: The ID of the mntner object you created in your initial steps for preparing to submit information to the IRR.
• changed: Specifies who submitted the update, and when the object was updated. The format of the date is YYYYMMDD. Dates in the future are not allowed. If the date is not specified, the database software will add the date when the update was actually processed. There must be at least one changed: attribute; if there are more, they must be in ascending date order. This attribute is for the user’s own reference. Nothing can be reliably determined by anyone other than the user about the object or its change history by looking at the changed: attributes. For example: changed: user@example.com 20080130
• source: The routing registry name. For the ARIN IRR, use source: ARIN.

See the template page for a full description of the route object fields and a route object example.

Creating a route6 Object

A route6 object specifies the IPv6 address prefix of an interdomain route and the ASN of the autonomous system from which the route originates. To create a route6 object, copy and paste the route6 template into a plain text email. The route6 object must contain the following fields:

• route6: The IPv6 address prefix of the route to be originated. Together with the origin: attribute, constitutes a primary key of the route6 object.
• password: Enter the clear-text password that you used when creating the MD5-PW hash for your mntner object.
• descr: A short description of the organization and location where this object is used. The description can have multiple lines. It should contain the full postal address as it exists in the ARIN registration.
• origin: The AS number from which the route will originate.
• mnt-by: The ID of the mntner object you created in your initial steps for preparing to submit information to the IRR.
• changed: Specifies who submitted the update, and when the object was updated. The format of the date is YYYYMMDD. Dates in the future are not allowed. If the date is not specified, the database software will add the date when the update was actually processed. There must be at least one changed: attribute; if there are more, they must be in ascending date order. This attribute is for the user’s own reference. Nothing can be reliably determined by anyone other than the user about the object or its change history by looking at the “changed:” attributes. For example: changed: user@example.com 20080130
• source: The routing registry name. For the ARIN IRR, use source: ARIN.

See the template page for a full description of the route6 object fields and a route6 object example.

Creating an as-set Object

An as-set defines a set of autonomous systems in the network through which traffic is routed. To create an as-set object, copy and paste the as-set template into a plain-text email.

The as-set object must contain the following fields:

• object name: A name you give to a group of ASNs. It is an RPSL name that starts with “as-”.
• descr: A short description of the organization and location where this object is used. The description can have multiple lines. It should contain the full postal address as it exists in the ARIN registration.
• tech-c: An ARIN POC handle for a technical contact. This is someone to be contacted for technical problems such as misconfiguration. For example: tech-c: SJ4-ARIN
• admin-c: An ARIN POC handle for an administrative contact. For example: admin-c: JS1001-ARIN
• mnt-by: The ID of the mntner object you created in your initial steps for preparing to submit information to the IRR.
• changed: Specifies who submitted the update, and when the object was updated. The format of the date is YYYYMMDD. Dates in the future are not allowed. If the date is not specified, the database software will add the date when the update was actually processed. There must be at least one changed: attribute; if there are more, they must be in ascending date order. This attribute is for the user’s own reference. Nothing can be reliably determined by anyone other than the user about the object or its change history by looking at the “changed:” attributes. For example: changed: user@example.com 20080130
• source: The routing registry name. For the ARIN IRR, use source: ARIN.

See the template page for a full description of the as-set object fields and an as-set object example.

Modifying Objects

This section includes general instructions for creating and updating IRR objects. For a full list of objects that can be submitted, see IRR Templates.

To modify objects:

1. Copy and paste the text from the object template into a new plain text email message. Note: Object templates retrieved via an IRR query are not identical enough to use when deleting an object. If you want an exact object copy, query using the -B query flag. You must then remove any extraneous text from the object template (such as remarks).
2. Be sure and include a line for the password with the clear-text password that you used when creating the MD5-PW hash for your mntner object.
3. Delete any optional fields you aren’t using from the template. You can include multiple templates in a single email, but they must be separated by at least one blank line. Blank lines cannot be included in the body of the template, though.
4. Send the email to rr@arin.net as a plain text email. If you submit an object and one already exists, the IRR assumes that you are modifying the current object and processes it. If your new object doesn’t have any changes (white space does not count), the IRR returns an error.

Deleting Objects

To delete an object from ARIN’s IRR:

1. Copy and paste the text from the current object into a new plain text email message. Note: Object templates retrieved via an IRR query are not identical enough to use when deleting an object. If you want an exact object copy, query using the -B query flag. You must then remove any extraneous text from the object template (such as remarks).
2. Be sure and include a line for the password with the clear-text password that you used when creating the MD5-PW hash for your mntner object.
3. Add a line consisting of delete: <comment> to the object template. Do not make any other changes to the template, other than white space characters, or the delete will fail. The delete operation will also fail if the object to be deleted is referenced from any other object in the database. Syntactically correct objects can still be deleted from the database (i.e. objects predating a syntax change). You can include who deleted the object and when (for example, delete: bob@example.com 20140101) for tracking purposes in autoprocessor logs.

Understanding Acknowledgments and Notifications

After all objects in an email are processed, an acknowledgment message is returned to the sender, using the contents of the Reply-to: or From: field. This is known as an acknowledgment. Acknowledgments are split into two sections.

The first section shows where the update was sent from. This may be a copy of the update email header. This section also includes a summary of the update results, explaining how many objects were recognized by the database software, how many operations were successful, and how many failed. The subject line of the acknowledgment states “SUCCESS” or “FAILED.” If the update message contains no objects or any one of the operations fails, the acknowledgment reports “FAILED.” Otherwise, it reports “SUCCESS.” Following this status is the original subject line.

The next section is the “DETAILED EXPLANATION.” This is split into three parts:

• A list of all objects that failed to process, including error, info, and warning messages
• A list of operations that were successful, which may include info and warning messages
• A list of paragraphs from your message that were not recognized as objects

Each part is separated in the acknowledgment by a line containing several ~ characters. Within each part, the objects and paragraphs are listed in the order they were processed. The line before each object contains three - characters. This allows for easy parsing by script.

Notifications

The format of a notification message is similar to the acknowledgment message. The first section explains why you are being sent this notification. The next section has the email header details showing where the update came from. The final section shows the changes that were contained in the update message, if it was successful. If it failed for authorization reasons, it shows the object for which a change was attempted, but not the actual change details.

A notification message is only sent to a single email address. It will contain all the notification details of objects from an update message that relate to that email address. If the same details need to be sent to two different email addresses, then two separate emails will be generated by the database software. This ensures that when an update contains many objects covered by overlapping notification email addresses, only the appropriate details are sent to each email address.

Notifications are caused by one of the following attributes:

• notify: Contacts the specified email address to report that the object has been successfully created, modified, or deleted. You may include multiple notify: attributes. All email addresses specified by a notify: attribute will be contacted, unless the object fails.
• mnt-nfy: Contacts the specified email address to report that a maintained object has been successfully created, modified, or deleted. This attribute is optional, and can be included only in mntner objects.
• upd-to: Contacts the specified email address to report when a maintained object creation, modification, or deletion has failed. You can include multiple upd-to: attributes. All email addresses specified by a upd-to: attribute will be contacted if the object fails. This attribute is mandatory, and can be included only in mntner objects.

Troubleshooting IRR Submissions

If you receive an error in response to an object submission, verify the following:

• The object does not already exist in the database. If you submit a template for an object that is already in the database, the system assumes that you are changing the object and the template must contain changes (or you will receive an error).
• The template contains changes (adding white space does not count). If there are no changes, the IRR will return a “no operation” error.

If you receive an error when submitting a mntner:

• Verify that your email contains one or more RPSL templates
• Be aware that with some email clients, the program adds encoding to the email header that cannot be read by the IRR processor. You can try an alternative email program to send your maintainer.

If you forget your mntner clear-text password or MD5-PW password:

1. Regenerate your MD5-PW password with the ARIN MD5-PW passphrase creator.
2. In ARIN Online, create an Ask ARIN Help Desk Ticket and choose the WHOIS/Routing Registry topic.
3. In the subject line, enter RSD mntner Help.
4. Copy and paste the text from your original mntner template into the Question field of the ticket.
   1. Delete any optional fields you aren’t using from the template.
   2. Make the changes you want to the fields of the mntner that you copied.
5. Submit the ticket. ARIN will then manually process your request to update your mntner object and respond via email.

Supported Features

ARIN’s IRR supports the following features.

MIME

MIME support means you can cryptographically sign an update message using email agents that attach the signature in a separate MIME part, not in the body of the message. Text encryption, however, is not allowed, as all update messages must be sent in plain text.

MIME support also allows the definition of scopes of authorization within the message (for example, parts where different passwords apply) and nested signing of messages. This may be necessary under some conditions when updating objects whose authorization must be derived from more than one party.

It is strongly recommended to keep MIME encapsulation simple. Complex MIME structures are more likely to generate errors.

The following rules apply when submitting updates using MIME encapsulation:

• The software will recognize the following headers and take the appropriate actions:
  • multipart/signed
  • multipart/alternative
  • multipart/mixed
  • multipart/unknown
  • application/pgp-signature
  • text/plain
• All other content-types are treated as text/plain.

Each MIME part is treated as a separate message, except where a signature part is closely coupled with a text part (in which case the two parts are treated together as a message). Authorization information is valid only within a single message part.

PGP

The database supports PGP-signed messages, so long as MIME encapsulation users ensure that a signed portion of an update message is submitted using multipart/signed composite type. In this case, the first body part contains the update message (which may also be a MIME encapsulated message), and the second body contains a signature. For a PGP signature, it is encapsulated with application/pgp-signature MIME discrete type. If one of the signatures fails in a nested signed portion, the whole portion is rejected. Instructions for using PGP can be found at http://www.ripe.net/data-tools/support/security/pgp.