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':

[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 have implicit $ORIGIN =

$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 --mx-rec="5"
This effectively creates record: MX 5
(All names without trailing dot have been expanded with $ORIGIN = zone name.)

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

> This creates two MX records for
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 --mx-rec="5"
> ipa: ERROR: invalid 'name': empty DNS label
This is a bug in IPA CLI. Please open an IPA ticket.

This command should create record like this: MX 5

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 @ --mx-rec="5 mx"

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

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:
> MX record: 5, 10
> How would I use ipa dnsrecord-mod to change the preference for
> from 10 to 6?
ipa dnsrecord-mod @ --mx-rec="10" --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 -

The best JSON API documentation I have found is at 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.
["", ""]

a struct in xml is a json dict:

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

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

Example JSON for deleting a record:
    "method": "dnsrecord_del",
    "id": 0,
    "params": [
        ["", ""],
        {"mxrecord", ["10"],
          "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.

Freeipa-users mailing list

Reply via email to