IP Register API for UIS services

This is an interim API, pending the IP Register database moving off Jackdaw. It is provided for a small number of UIS systems, originally just for use by the Managed Web Service. The MWS has a hostname approval workflow which is backed by this API.

API endpoints

The API is accessed via ssh:

ssh -i <key> mwsuser@ssh.jackdaw.cam.ac.uk <endpoint> [database] <cmd>

The account on Jackdaw is called mwsuser for historical reasons.

The <key> is described under 'authentication' below.

The <endpoint> can be:

• ipreg_api - the normal live endpoint
• ipreg_api_test - for staging new versions of the ipreg_api script

The optional [database] determines which instance of the database is to be manipulated, using either Jackdaw terminology or the short MWS aliases:

• jackdaw or live
• jdawtest or test
• jdawdev or dev

If the [database] is omitted, the defaults are:

• ipreg_api jackdaw
• ipreg_api_test jdawtest

Authentication

API clients are UIS services, identified by the <key> they use to invoke the API. This determines which set of target domains belong to that service, for use in CNAME targets.

Contact ip-register@uis.cam.ac.uk to ask for a key to be enrolled.

The first three keys below allow subdomains of both private.cam.ac.uk and cam.ac.uk.

• TM: *.tm.uis.(private).cam.ac.uk
• MWS: *.mws3.csx.(private).cam.ac.uk
• OpenStack: *.vss.cloud.(private).cam.ac.uk
• IAAS: *.iass.cloud.(private).cam.ac.uk
• Drupal (new style):
  • deptNN-dev.drupal.uis.cam.ac.uk
  • deptNN-live.drupal.uis.cam.ac.uk
  • uasNN-dev.drupal.uis.cam.ac.uk
  • uasNN-live.drupal.uis.cam.ac.uk

• Drupal (old style):
  • primary.admin.cam.ac.uk
  • redirect.admin.cam.ac.uk
  • aegir.admin.cam.ac.uk
  • eng.uat.admin.cam.ac.uk
  • uas-web.admin.cam.ac.uk
  • uas-web-dev.admin.cam.ac.uk

The Drupal service is moving from the old ACN Traffic Manager setup to the new UIS one. In the new style the Drupal CNAME targets are themselves CNAMEs that point at *.tm.uis.cam.ac.uk. This double indirection keeps the Drupal control interface separate from the details of the Traffic Manager configuration.

Common to all commands

• the return code from the script is 0 for success and non-zero for error (the meaning of the codes are documented for each command)

• stderr is empty on success and contains a potentially multi-line human-readable explanation of the error

• stdout is a JSON dictionary containing at least the following keys

  • status: copy of the return code
  • message: copy of the message sent to stderr

Return information about a host name

Command: get nameinfo <hostname>

Returns information about a hostname. The hostname need not currently exist but the domain in which it would be created must.

Additional keys:

• hostname: copy of hostname from request
• delegated: for hostname in .cam.ac.uk sub-domains, one of
  • 'Y': name is in a delegated sub-domain
  • 'N': name is in a non-delegated sub-domain

• domain: IPregister subdomain contaning hostname
• mzone: IPregister management zone for domain
• exists: list of zero or more
  • 'V': hostname exists and is a vbox
  • 'A': hostname exists and is an aname
  • 'B': hostname exists and is a box
  • 'M': hostname exists and is a mail domain
  • 'C': hostname exists and is a cname

• emails: list of zero or more
  • role email addresses of the authorities for the domain

• crsids: list of zero or more
  • CRSids of domain managers

Return codes:

• 1 - Invocation error
• 2 - Database unavailable
• 3 - No valid domain for hostname
• 4 - Internal error (shouldn't happen)
• 99 - Database error (probably constraint violation)
• 100 - Other error

Get CNAME

Command: get cname <hostname>

Return the target of a cname. It is an error to request information about an non-existent cname.

Additional keys:

• hostname: copy of the hostname from the request
• target: name to which the cname points

Return codes:

• 1 - Invocation error
• 6 - No cname record for hostname found
• 99 - Database error (probably constraint violation)
• 100 - Other error

Create/update CNAME

Command: put cname <hostname> <target>

Create or updates a cname record aliasing hostname to target. It is not possible to select only creating or only updating. It is an error if:

• hostname isn't part of an existing domain
• hostname is in a delegated sub-domain
• hostname exists as something other than a CNAME
• target doesn't exist
• target isn't in a permitted target domain

Additional keys:

• hostname: copy of the hostname from the request
• target: copy of the target from the request
• domain: IPregister subdomain contaning hostname
• action: 'I' if a new record is inserted, 'U' if an existing one is updated, empty if no action was required

Return codes:

• 1 - Invocation error
• 2 - Database unavailable
• 3 - No valid domain for hostname
• 5 - Target not in a permitted domain
• 7 - Hostname in a delagated domain
• 8 - Unknown user
• 99 - Database error (probably constraint violation)
• 100 - Other error

Delete CNAME

Command: delete cname <hostname>

Delete a cname. It is not an error if hostname doesn't exist, or exists and isn't a cname. It is an error if an existing target isn't in a permitted domain

Additional keys:

• hostname: copy of the hostname from the request
• target: copy of the cname target (if any) before deletion
• changed: "Y" if something is actually deleted, "N" if ther was no matching record, blank on error

Return codes:

• 1 - Invocation error
• 2 - Database unavailable
• 5 - Target not in a permitted domain
• 8 - Unknown user
• 99 - Database error (probably constraint violation)
• 100 - Other error

Get SSHFP records

Command: get sshfp <hostname>

Return a list of zero of more SSHFP records for hostname. It is not an error if hostname doesn't exist and this can't be destinguished from hostname existing but having no SSHFP records.

Additional keys:

• hostname: copy of the hostname from the request
• fingerprints: list of zero or more fingerprint records
  • algorithm: numeric algorithm code
  • fptype: numeric fingerprint type
  • fingerprint: the relavent fingerprint

Return codes:

• 1 - Invocation error
• 2 - Database unavailable
• 99 - Database error (probably constraint violation)
• 100 - Other error

Create/update SSHFP record

Command: put sshfp <hostname> <algorithm> <fptype> <fingerprint>

Create or update a single SSHFP record for hostname with given algorithm and fingerprint type. It is not possible to select only creating or only updating. It is an error if hostname isn't in a permitted domain.

Additional keys:

• hostname: copy of the origin from the request
• algorithm: copy of algorithm from the request
• fptype: copy of fptype from the request
• fingerprint: copy of fingerprint from the request
• action: 'I' if a new record is inserted, 'U' if an existing one is updated, empty if no action was required

Return codes:

• 1 - Invocation error
• 2 - Database unavailable
• 5 - Target not in a permitted domain
• 8 - Unknown user
• 99 - Database error (probably constraint violation)
• 100 - Other error

Delete SSHFP record

Command: delete sshfp <hostname> <algorithm> <fptype>

Delete a single SSHFP record. It is not an error if the SSHFP record selected doesn not exist. It is an error if hostname isn't in a permitted domain.

Additional keys:

• hostname: copy of the origin from the request
• algorithm: copy of algorithm from the request
• fptype: copy of fptype from the request
• changed: "Y" if something is actually deleted, "N" if theer was no matching record, blank on error

Return codes:

• 1 - Invocation error
• 2 - Database unavailable
• 5 - Target not in a permitted domain
• 8 - Unknown user
• 99 - Database error (probably constraint violation)
• 100 - Other error