The xlist_ops form

Purpose and scope

The xlist_ops form, like list_ops, provides a means of transferring data in machine readable form, possibly in bulk, to or from the IP address database. Unlike list_ops, it provides for actions on database entries that are not simple registrations of a box with a single IPv4 address.

More specifically, it allows for actions on any of the following object types:

  • Boxes - ordinary equipment registrations, but possibly having multiple IP addresses (either IPv4 or IPv6).
  • Vboxes - virtual entitiy registrations, hosted on boxes (or other vboxes), and possibly having multiple IP addresses (either IPv4 or IPv6).
  • Cnames - DNS alias registrations.
  • Anames - registrations of duplicate address records (either IPv4 or IPv6). For ordinary COs, only display/list actions on these are available.

The type of entity being operated on should be selected from the pull-down list at the top of the form.

The input and output files, as for list_ops, are in TAB-separated format, with the first line providing the names for the columns. The record separator can be selected between CR, LF, or CR+LF for downloads, while any of those are accepted for uploads.

List operations (downloads)

The possible ways to select entities to download are somewhat more restricted than in list_ops. Selecting by IP address is not appropiate when an entity can have multiple such addresses. Therefore, selection is always based on the name of the entitiy. It can by either by domain part of the name, or by mzone. In the latter case, all domains which are part of the mzone are included.

All the ordinary attributes of the various types of entity appear as columns in the downloaded files. In addition:

  • For boxes, vboxes and anames there is an additional column "addresses" containing a comma-separated list of IP addresses in the usual presentation formats (either IPv4 or IPv6).
  • For vboxes only there is an additional column "boxes" containing a comma-separated list of the names of the entities (usually boxes, but possibly other vboxes) on which the vbox is hosted.

There are no such additional columns for cnames. Note that using comma-separated lists works because neither the presentation format of IP addresses nor legal DNS names can contain commas.

Upload operations

These require a file to be uploaded, with columns named as described below for the individual operations. The operation associated with each line is obeyed in turn, and committed in the database (if successful) or rolled back (if not). A partial operation is never performed. Success or failure reports are output at the bottom of the web page.

Register operations

This operation registers new entities in the database. The uploaded file must contain a column "name" and an appropriate domain part is chosen from it. The other columns should be:

  • The required attributes of the particular entity type;
    • For boxes: equipment, location, owner, sysadmin.
    • For vboxes: purpose
    • For cnames: target_name, purpose
    • For anames: purpose
  • Optionally, any or all of optional attributes of the particular entity type:
    • For boxes: end_user, remarks, review_date
    • For vboxes: sysadmin, end_user, remarks, review_date
    • For cnames: remarks, review_date
    • For anames: remarks, review_date
  • In addition, as required columns :
    • For boxes, vboxes and anames: a column "addresses" containing a comma-separated list of the IP addresses to be assigned to the entity (see below for more details).
    • For vboxes only: a column "boxes" containing a comma-separated list of the names of boxes (or vboxes) on which this vbox is hosted.

The last-mentioned columns are mandatory, but the corresponding values may be empty. The line of thought here is that boxes, vboxes and anames may have no IP addresses, and a vbox may be registered without information about where it is hosted, but that such should not be created simply by accident.

The IP addresses specified in the "addresses" column can be any of:

  • An explicit IPv4 address (as 131.111.11.47).
  • An explicit IPv6 address (as 2001:630:212:100:214:4fff:fed2:5e0 or 2001:630:212:8::d:fff0).
  • Except in the case of anames, selection of any available IPv4 address from an mzone (as BOTOLPH) or a specific mzone+lan (as BOTOLPH/FELLOWS).

Rename operations

This operation renames entities in the database, which must be of the right type. The uploaded file should consist of exactly two columns, named "oldname" and "newname". An appropriate domain part is chosen from the new name, which might or might not be the same as the old domain. Each rename operation works exactly like that in the corresponding boxops, vboxops, cnameops or anameops page.

Modify operations

This operation modifies existing entities in the database, which must be of the right type. The only mandatory column in the uploaded file is "name". In addition there may be columns:

  • Any of the required or optional attributes of the particular entity type - see above under "register operations" for lists. Attributes for which no column is present are not modified.
  • In addition, for boxes, vboxes or anames:
    • An optional column "add_addresses" containing a comma-separated list of IP addresses to be newly assigned to the entity.
    • An optional column "remove_addresses" containing a comma-separated list of IP addresses to be rescinded from the entity.
  • In addition, for vboxes only:
    • An optional column "add_boxes" containing a comma-seperated list of the names to be added to the list of (v)boxes on which this vbox is hosted.
    • An optional column "remove_boxes" containing a comma-seperated list of the names to be removed from the list of (v)boxes on which this vbox is hosted.

The IP addresses can be specified in the same way as for the register operation, except that for obvious reasons the mzone and mzone/lan form can be used only in "add_addresses" (and not for anames).

Rescind operations

This operation removes existing entities from the database, which must be of the right type. The uploaded file should consist of just one column, named "name".

The rescind operations, unlike those on the individual boxops, vboxops, cnameops or anameops pages, do not require dependant entities to be removed first. All IP addresses assigned to boxes, vboxes or anames are rescinded as well, as are any (v)box associations for vboxes.