[Freeipa-users] IPA DNS command line tools and JSON interface

[Rich Megginson]

tl;dr - A lot of detail about working with the IPA DNS command line 
interfaces and JSON interfaces.

I'm working on integrating IPA with OpenStack Designate (DNSaaS), using 
the /ipa/json interface.  I've had some Q&A with the IPA DNS developer 
(Thanks Petr Spacek!) that I thought would be useful to share.

1) How to specify hosts and domains with the ipa dnsrecord-* commands

IPA uses standard conventions used in DNS 'master files':
http://tools.ietf.org/html/rfc1035#section-5

[Quote, *emphasis* was added.]
<domain-name>s make up a large share of the data in the master file.
The labels in the domain name are expressed as character strings and
separated by dots.  Quoting conventions allow arbitrary characters to be
stored in domain names.  *Domain names that end in a dot are called
absolute, and are taken as complete.  Domain names which do not end in a
dot are called relative; the actual domain name is the concatenation of
the relative part with an origin specified in a $ORIGIN*, $INCLUDE, or as
an argument to the master file loading routine.  A relative name is an
error when no origin is available.

<character-string> is expressed in one or two ways: as a contiguous set
of characters without interior spaces, or as a string beginning with a "
and ending with a ".  Inside a " delimited string any character can
occur, except for a " itself, which must be quoted using \ (back slash).

Because these files are text files several special encodings are
necessary to allow arbitrary data to be loaded.  In particular:

                 of the root.

@               A free standing @ is used to denote the current origin.
[End of quotation.]

Please note that this convention applies to *all* names including names 
inside record data (the 'right side').

IPA provides implicit $ORIGIN = name of the zone. It is not possible to 
change this origin explicitly because $ORIGIN value is derived from 
object structure in LDAP.

I.e. all records inside zone example.com. have implicit $ORIGIN = 
example.com.

$ORIGIN *for zone names* is always root domain (.) so it doesn't make 
any difference if you append the trailing dot to zone name or not.

 > However, if I do something like this:
 >
 > $ ipa dnsrecord-add testdomain.com. testdomain.com --mx-rec="5 
mx.testdomain.com."
This effectively creates record:
testdomain.com.testdomain.com. MX 5 mx.testdomain.com.
(All names without trailing dot have been expanded with $ORIGIN = zone 
name.)

 > $ ipa dnsrecord-add testdomain.com. testdomain.com --mx-rec="5 
mx.testdomain.com"
And this:
testdomain.com.testdomain.com. MX 5 mx.testdomain.com.testdomain.com.

 > This creates two MX records for testdomain.com
Because you have specified two distinct records. The $ORIGIN (= zone 
name) was appended automatically to all names without trailing dot.

 > NOTE that this does not work:
 > $ ipa dnsrecord-add testdomain.com. testdomain.com. --mx-rec="5 
mx.testdomain.com"
 > ipa: ERROR: invalid 'name': empty DNS label
This is a bug in IPA CLI. Please open an IPA ticket.

https://fedorahosted.org/freeipa/ticket/4232

This command should create record like this:
testdomain.com. MX 5 mx.testdomain.com.testdomain.com.

I think that this is not what you expect (see the value on on the right 
side).

You should either use relative names
$ ipa dnsrecord-add testdomain.com. @ --mx-rec="5 mx"

or use FQDN with trailing dot:
$ ipa dnsrecord-add testdomain.com. @ --mx-rec="5 mx.testdomain.com."

Character @ is a special trick from RFC to specify "origin", i.e. in 
context of IPA the zone name.

2) How to modify DNS records
 > Let's say I have
 > Record name: testdomain.com.
 > MX record: 5 mx1.testdomain.com., 10 mx2.testdomain.com.
 >
 > How would I use ipa dnsrecord-mod to change the preference for
 > mx2.testdomain.com. from 10 to 6?
ipa dnsrecord-mod testdomain.com. @ --mx-rec="10 mx2.testdomain.com." 
--mx-pref="6"

In case with multiple records of the same type you have to specify which 
record should be modified.

3) The JSON interface - 
http://adam.younglogic.com/2010/07/talking-to-freeipa-json-web-api-via-curl/

The best JSON API documentation I have found is at 
https://git.fedorahosted.org/cgit/freeipa.git/tree/install/ui/test/data. 
The array argument part of "params" isn't documented, but the dict part is.

The ipa command line tools use RPC, but they use XML.  If you run ipa 
-vv dnsrecord-add ... you can see the XML sent and received. There is a 
bit of work converting from XML to JSON.  e.g.
<array><data><value><string>testdomain.com.</string></value><value><string>testdomain.com</string></value></data></array>
is
["testdomain.com.", "testdomain.com."]

a struct in xml is a json dict:
<struct><member><name>method</name><value><string>dnsrecord_add</string></value></member></struct>
is
{"method":"dnsrecord_add"}

Example JSON for adding a record:
{
     "method": "dnsrecord_add",
     "id": 0,
     "params": [
         ["testdomain.com.", "testdomain.com."],
         {"mxrecord", ["10 mx1.testdomain.com", "20 mx2.testdomain.com."],
           "version", "2.65"}
     ]
}

Example JSON for modifying a record:
{
     "method": "dnsrecord_mod",
     "id": 0,
     "params": [
         ["testdomain.com.", "testdomain.com."],
         {"mxrecord", ["10 mx1.testdomain.com."],
           "mx_part_preference": 5,
           "version", "2.65"}
     ]
}

Example JSON for deleting a record:
{
     "method": "dnsrecord_del",
     "id": 0,
     "params": [
         ["testdomain.com.", "testdomain.com."],
         {"mxrecord", ["10 mx1.testdomain.com."],
           "version", "2.65"}
     ]
}

The JSON response dict contains a key called "errors".  If the value for 
this key is None, the command succeeded, otherwise, the value will 
contain detailed error information about one or more errors encountered.