Add to documentation: new subsection to "Making changes to IRR objects"

[dhutchin-ctl]

Below are some notes that might be added as a sub-section to “Making changes to IRR objects” in the documentation. There are two places where I added a double ‘?’ as a point that needs more input. And of particular note is how continuation lines disable some of the processing.

Notes on change submission are processed

There are three ways of submitting objects to IRR:

• Via email
• Via http to /v1/submit and object_text
• Via http to /v1/submit and attributes

Each submission is validated. The rules for validation are extensive:

• All “strong references”, as indicated in an object’s template (whois …. ‘-t <object_class>’) must exist
• All members of route-sets must be of the form of an ipv4 prefix
• All mp-members of route-sets must be of the form an ipv6 prefix
• (others??)

Internally (in the database) the IRR object data is kept in two different formats, one is “object_text” which is the straight text form (same as returned by whois queries,etc), the other is as parsed data stored in a JSON string in “parsed_data”.

When creating or modifying an object by submitting the new data via email or via http to /v1/submit specifying “object_text”, the submitted data is stored as-is in the “object_text” column of the object database with the following exceptions:

• Any “members” or “mp-members” lines (those lines starting with the word “members”) will have their form normalized so that the prefixes on a line are each separated by a comma and one space. However, if the attribute has a continuation line specified in the input, extra spaces are not removed from the representation in the object_text column.
• (are there any others??)

Example:
Submitted via http:///v1/submit

{"objects":[
    {"object_text":"route-set:      RS-ABC1\ndescr:          abcde, 1234\ndescr:          1a2b3c,  a1b2, c3\nmembers:        1.2.3.0/24,1.2.4.0/24\nmembers:        1.2.5.0/24,  1.2.6.0/24\nmembers:        1.2.7.0/24,   1.2.8.0/24,  1.2.9.0/24\nmp-members: dead:beaf::/124,  beaf:dead::/124\n deef:beaf::/124\nadmin-c:        SAMSMITH-LEVEL3\ntech-c:         SAMSMITH-LEVEL3\nmnt-by:         DIP-MNT\nremarks:        first of line1, 2nd of line1\nremarks:        first of line2,  2nd of line2\nremarks:        line3 first part,  line3 2nd part\nchanged:        [email protected] 20220524\nchanged: [email protected] 20220525\nsource:         LEVEL3"}
 ],
 "passwords": ["xyz"]
}

Or, submitted via email

route-set:      RS-ABC1
descr:          abcde, 1234
descr:          1a2b3c,  a1b2, c3
members:        1.2.3.0/24,1.2.4.0/24
members:        1.2.5.0/24,  1.2.6.0/24
members:        1.2.7.0/24,  1.2.8.0/24,  1.2.9.0/24
mp-members:     dead:beaf::/124,  beaf:dead::/124
                deef:beaf::/124
admin-c:        SAMSMITH-LEVEL3
tech-c:         SAMSMITH-LEVEL3
mnt-by:         DIP-MNT
remarks:        first of line1, 2nd of line1
remarks:        first of line2,  2nd of line2
remarks:        line3 first part,  line3 2nd part
changed:        [email protected] 20220524
changed:        [email protected] 20220525
source:         LEVEL3
password:       xyz

The object_text column becomes:

route-set:      RS-ABC1
descr:          abcde, 1234
descr:          1a2b3c,  a1b2, c3
members:        1.2.3.0/24,1.2.4.0/24
members:        1.2.5.0/24,1.2.6.0/24
members:        1.2.7.0/24,1.2.8.0/24,1.2.9.0/24
mp-members:     dead:beaf::/124,  beaf:dead::/124
                deef:beaf::/124
admin-c:        SAMSMITH-LEVEL3
tech-c:         SAMSMITH-LEVEL3
mnt-by:         DIP-MNT
remarks:        first of line1, 2nd of line1
remarks:        first of line2,  2nd of line2
remarks:        line3 first part,  line3 2nd part
changed:        [email protected] 20220524
changed:        [email protected] 20220525
source:         LEVEL3

and the parsed_data column as JSON is:

{"descr": ["abcde, 1234", "1a2b3c, a1b2, c3"], "mnt-by": ["DIP-MNT"], "source": "LEVEL3", "tech-c": ["SAMSMITH-LEVEL3"], "admin-c": ["SAMSMITH-LEVEL3"], "changed": ["[email protected] 20220524", "[email protected] 20220525"], members": ["1.2.3.0/24", "1.2.4.0/24", "1.2.5.0/24", "1.2.6.0/24", "1.2.7.0/24", "1.2.8.0/24", "1.2.9.0/24"], "remarks": ["first of line1, 2nd of line1", "first of line2, 2nd of line2", "line3 first part, line3 2nd part"], "route-set": "RS-ABC1", "mp-members": ["dead:beaf::/124", "beaf:dead::/124", "deef:beaf::/124"]}

Notice the extra spaces stored in the object_text for mp-members because there is a continuation line and that those spaces are removed in the parsed_data. For consistency’s sake, it might be a good idea to never use continuations lines.

When creating or modifying an object via http to /v1/submit with attributes, each attribute’s value can be either a string or an array of strings. The “value” of each attribute/value pair is used to create a new line in the object_text column’s string and either a new attribute/value pair in the parsed_data JSON’s hash (for attributes that take a single value), or a new array element for attributes that take multiple values. The new line, or the new array element is the value of the submitted attribute/value pair if the value is a string, and the concatenation of the all elements with a comma if the value is an array.

Example:
Submitted via http:///v1/submit

{"objects":[
    {"attributes": [
        {"name":"route-set",  "value":"RS-ABC2"},
        {"name":"descr",      "value":"abcde, 1234"},
        {"name":"descr",      "value":["1a2b3c,  a1b2, c3"]},
        {"name":"descr",      "value":["3", "element", "array", "merged"]},
        {"name":"members",    "value":"1.2.3.0/24,1.2.4.0/24"},
        {"name":"members",    "value":["1.2.5.0/24","1.2.6.0/24"]},
        {"name":"members",    "value":["1.2.7.0/24,  1.2.8.0/24","1.2.9.0/24"]},
        {"name":"mp-members", "value":["dead:beaf::/124","beaf:dead::/124"]},
        {"name":"mp-members", "value":["deef:beaf::/124"]},
        {"name":"admin-c",    "value":"SAMSMITH-LEVEL3"},
        {"name":"tech-c",     "value":"SAMSMITH-LEVEL3"},
        {"name":"mnt-by",     "value":"DIP-MNT"},
        {"name":"remarks",    "value":"  first of line1, 2nd of line1"},
        {"name":"remarks",    "value":"        first of line2,  2nd of line2"},
        {"name":"remarks",    "value":" line3 first part,  line3 2nd part"},
        {"name":"changed",    "value":"[email protected] 20220524"},
        {"name":"changed",    "value":"[email protected] 20220525"},
        {"name":"source",     "value":"LEVEL3"}
    ]}
 ],
 "passwords": ["xyz"]
}

Produces a parsed_data column of:

{"descr": ["abcde, 1234", "1a2b3c, a1b2, c3", "3, element, array, merged"], "mnt-by": ["DIP-MNT"], "source": "LEVEL3", "tech-c": ["SAMSMITH-LEVEL3"], "admin-c": ["SAMSMITH-LEVEL3"], "changed": ["[email protected] 20220524", "[email protected] 20220525"] members": ["1.2.3.0/24", "1.2.4.0/24", "1.2.5.0/24", "1.2.6.0/24", "1.2.7.0/24", "1.2.8.0/24", "1.2.9.0/24"], "remarks": ["first of line1, 2nd of line1", "first of line2, 2nd of line2", "line3 first part, line3 2nd part"], "route-set": "RS-ABC2", "mp-members": ["dead:beaf::/124", "beaf:dead::/124", "deef:beaf::/124"]}

Notice how the third “descr” attribute has the specified array of three element merged into a single string.