Purpose and scope
The list_ops form provides a means of transferring data in machine
readable form, possibly in bulk, to or from the IP address database.
As with single_ops, it only copes with simple (but overwhelmingly
common) cases, systems that is with only one address and no aliases.
It was noted that many institutions maintain their own private databases of IP address registrations, typically as spreadsheets, and make requests, often in bulk, to ip-register in the form of extracts from such spreadsheets. These spreadsheets themselves are often derived in part from other databases. Furthermore, full lists of institutional registrations are often requested and presumably undergo some semi-automated reconciliation with local databases. At all events, it is clear that manual (re-)keying for almost every undergraduate every Autumn would be an impossibly cumbersome interface for college COs. This form attempts to meet this particular problem.
That said, it has become apparent that there is serious risk of
misunderstanding here. This form provides a means of bulk submission
of requests, exactly the same operational requests that could have
been made individually with single_ops. It does not provide imperative
upload of data to be forced into the database. Request types moreover
cannot be mixed within a batch. A batch is either a set of registration
requests, or a set of modification requests, or a set of rescindment
requests. (Bulk rescinding and re-registration of a whole college's
worth of data, much of it unchanged, may be possible, but is decidedly
not what is expected and will often run into the sands of non-simple
cases.)
Registration data is transferred between the browser machine and the database machine in tabular form, one registration per line. The columns are identified by the first line, which is special, containing column (attribute) identifiers rather than registration data. Columns are separated by TAB. (Yes, for the time being that precludes the use of TAB as a data character.) The columns can be in any order, and the columns that are present depend on the operation requested. A sample file might look like the following, except that for this example I have replaced TAB with | -
name|lan|equipment|location|owner|end_user|sysadmin bursar.botolph.cam.ac.uk|MAIN|Pentium PC|Bursar's Office|College|bursar|CO master.botolph.cam.ac.uk|MAIN|Hexium PC|Master's Lodge|College|Master|CO
The list_xxx buttons cause the complete list of matching registrations
to be downloaded to the browser, which should prompt you for where to
file the results. The line terminator to be used in downloads can be
selected from a pop-up menu.
For uploads to the database, the data should be supplied in a file on the machine running the browser. Insert the name of that file into the obvious field in the form and press the button appropriate to the action required. For the above example "register" might be appropriate. Lines in uploaded files are terminated by any uninterrupted sequence of CR or LF characters. Thus in particular CR, LF, CRLF and LFCR will all terminate lines. This rule does mean that you can't get empty lines into the system this way, but then you don't want to.
Warning: In general there is no simple easy way to reverse a bulk update. Take care!
The action buttons, register, rename, modify and rescind all have much
the same semantics as in single_ops. The selected action is applied to
all rows in the supplied file, and the file must contain columns
appropriate to the action. The general gist is as with single_ops,
except that the operation is applied non-interactively to a list. Each
line of the list is dealt with as a separate database transaction,
though result text is displayed consecutively for each item. You should
check the result text carefully, even if it's a thousand lines long.
If you can't take huge batches of result text, don't submit huge
batches of requests.
For register you must supply host names, but you can allow the system to choose an address if you wish, as in the example above, and the address thus chosen will be constrained by the mzone, lan, and subnet fields in the form. Alternatively, if you are determined to rule the roost, you can supply an address column. Equipment, location, owner and sysadmin are obligatory; end_user, remarks etc are optional.
For modify and rescind the equipment must be identified by either an address column or a name column. For modify, other columns specify new attribute values. For rescind, no other column is allowed.
For rename, only old_name and new_name columns are allowed.
Note: for compatibility reasons with legacy client
software, the list_ops page does not support downloading or updating
the MAC address field. This can be done using the
xlist_ops
page using the v4_address object type.