The xlist_ops form

• Go to xlist_ops

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.
• v4_addresses - modifications of IPv4 addresses to set MAC addresses (for DHCP) and/or DHCP groups.

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

Note that registering a device with a MAC address will require two separate uploads: one using the 'box' type to create the box with the necessary IP address(es), then using 'v4_address' to assign the MAC address(es) against those addresses.

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.
• For v4_addresses the list consists of only the address, MAC address (as a string of 12 hexadecimal digits without separating character) and DHCP group.

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. For boxes, vboxes, anames and cnames, 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).

v4_addresses cannot be registered - this must be done via the appropriate box or vbox object they're assigned to.

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 old_name and new_name. 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 box_ops, vbox_ops, cname_ops or aname_ops page.

v4_addresses cannot be renamed.

Modify operations

This operation modifies existing entities in the database, which must be of the right type. For boxes, vboxes, cnames and anames, 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. Note that an addresses column cannot be used to replace all existing addresses: they must be individually removed with a remove_addresses column and the new addresses supplied with add_addresses.

• 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).

For v4addresses the "address" field is mandatory. The following fields can be optionally supplied: mac and dhcpgroup. Note that the MAC address must be specified as a string of 12 hexadecimal digits without any separators (colon, hyphen, dot, etc.). The letters can be in upper or lower case.

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 box_ops, vbox_ops, cname_ops or aname_ops 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.

v4_addresses cannot be rescinded - this must be done through the box or vbox they belong to. Removing IP address from a 'box' will remove the MAC addresses associated with them, however.