[Freeipa-devel] [PATCH] [WIP] 182 Create per-type DNS API based on options

Wed Jan 11 20:16:18 UTC 2012

Martin Kosek wrote:
> On Wed, 2011-12-21 at 16:46 +0100, Martin Kosek wrote:
>> This is a fully functional prototype of the new DNS API based on new
>> options instead of new commands. It still has rough edges (missing
>> tests, extended help) but should give a very good picture about the new
>> API and provide a base for WebUI guys.
>>
>> -------
>> Use new structured DNSRecord parameters to generate per-type API
>> for all supported DNS RR types. This should help significantly
>> the end-user with manipulating complex DNS record type (MX, LOC,
>> etc.).
>>
>> All enhancements are integrated to current DNS record commands:
>>
>> 1) dnsrecord-add
>>    - Records can be either entered as a raw value (e.g. --mx-rec=
>>      "1 srv1.example.com" for MX record) or per-part:
>>      --mx-preference=1 --mx-exchanger=srv1.example.com
>>    - CLI interactive help behavior was changed. It will ask for
>>      a record type and then ask for all DNS record part values
>>      (e.g. MX Preference value, MX Exchanger value).
>>
>> 2) dnsrecord-mod
>>    - This command can now operate in 2 modes. When only a raw DNS
>>      record is entered (e.g. --mx-rec="1 srv1.example.com") it
>>      operates in standard mode and replaces any previous mxrecord
>>      value with the --mx-rec value.
>>
>>      When any structured parameter (e.g. --mx-preference) is passed
>>      it modifies just the specified parts of one mxrecord value
>>      referred by --mx-rec:
>>        --mx-rec="1 srv1.example.com" --mx-preference=2
>>    - New interactive help has been implemented. It will ask for a
>>      record to be modified (in the same manner as dnsrecord-del)
>>      and then let user change DNS record part(s) for chosen
>>      records.
>>
>> 3) All dnsrecord-* commands have now --structured option
>>    - When this option is passed, instead of displaying raw DNS values
>>      all DNS records are parsed and displayed per-part. Example:
>>
>> $ ipa dnsrecord-show example.com @ --structured
>>    Record name: @
>>    Records:
>>      Record type: MX
>>      Record data: 0 server1.example.com.
>>      MX Preference: 0
>>      MX Exchanger: server1.example.com.
>>
>>      Record type: NS
>>      Record data: ns1.example.com.
>>      NS Hostname: ns1.example.com.
>>
>> All API changes are compatible with clients without this patch.
>>
>> https://fedorahosted.org/freeipa/ticket/2082
>>
>> ------------------------------------------------
>> A little demonstration of the new API capabilities:
>>
>> #### New help with option groups for per-type options
>> # ipa dnsrecord-add --help
>> Usage: ipa [global-options] dnsrecord-add DNSZONE NAME [options]
>>
>> Options:
>> ...
>>    --structured          Parse all raw DNS records and return them in a
>>                          structured way
>> ...
>>    A Record:
>>      --a-rec=ARECORD     Comma-separated list of raw A records
>>      --a-ip-address=STR  IP Address
>>
>>    AAAA Record:
>>      --aaaa-rec=AAAARECORD
>>                          Comma-separated list of raw AAAA records
>>      --aaaa-ip-address=STR
>>                          IP Address
>> ...
>>    MX Record:
>>      --mx-rec=MXRECORD   Comma-separated list of raw MX records
>>      --mx-preference=INT
>>                          Preference given to this exchanger. Lower values
>> are
>>                          more preferred
>>      --mx-exchanger=STR  A host willing to act as a mail exchanger
>>
>> #### Standard dnsrecord-add
>> # ipa dnsrecord-add example.com server1 --a-rec=10.0.0.1
>>    Record name: server1
>>    A record: 10.0.0.1
>>
>> #### New interactive help for dnsrecord-add
>> # ipa dnsrecord-add example.com server1
>> Please choose a type of DNS resource record to be added
>> The most common types for this type of zone are: A, AAAA
>>
>> DNS resource record type: AAAA
>> AAAA IP Address: 2001:db8::1428:57ab
>>    Record name: server1
>>    A record: 10.0.0.1
>>    AAAA record: 2001:db8::1428:57ab
>>
>> # ipa dnsrecord-add example.com @
>> Please choose a type of DNS resource record to be added
>> The most common types for this type of zone are: NS, MX, LOC
>>
>> DNS resource record type: MX
>> MX Preference: 0
>> MX Exchanger: server1.example.com.
>>    Record name: example.com
>>    MX record: 0 server1.example.com.
>>    NS record: vm-068.idm.lab.bos.redhat.com.
>>
>> #### Old-stype mod command
>> # ipa dnsrecord-mod example.com @ --mx-rec="1 server1.example.com."
>>    Record name: example.com
>>    MX record: 1 server1.example.com.
>>    NS record: vm-068.idm.lab.bos.redhat.com.
>>
>> #### Modification via new structured options:
>> # ipa dnsrecord-mod example.com @ --mx-rec="1 server1.example.com." --mx-preference=2
>>    Record name: example.com
>>    MX record: 2 server1.example.com.
>>    NS record: vm-068.idm.lab.bos.redhat.com.
>>
>> #### Modification via new interactive help:
>> # ipa dnsrecord-mod example.com @
>> No option to modify specific record provided.
>> Current DNS record contents:
>>
>> MX record: 2 server1.example.com.
>> NS record: vm-068.idm.lab.bos.redhat.com.
>>
>> Modify MX record '2 server1.example.com.'? Yes/No (default No): y
>> MX Preference [2]: 3
>> MX Exchanger [server1.example.com.]:
>> Modify NS record 'vm-068.idm.lab.bos.redhat.com.'? Yes/No (default No):
>>    Record name: example.com
>>    MX record: 3 server1.example.com.
>>    NS record: vm-068.idm.lab.bos.redhat.com.
>>
>> #### Example of use of --structured option (this will be useful for WebUI):
>> # ipa dnsrecord-show example.com @ --structured
>>    Record name: @
>>    Records:
>>      Record type: MX
>>      Record data: 3 server1.example.com.
>>      MX Preference: 3
>>      MX Exchanger: server1.example.com.
>>
>>      Record type: NS
>>      Record data: vm-068.idm.lab.bos.redhat.com.
>>      NS Hostname: vm-068.idm.lab.bos.redhat.com.
>>
>> #### dnsrecord-del works in the same way as the old one:
>> # ipa dnsrecord-del example.com server1
>> No option to delete specific record provided.
>> Delete all? Yes/No (default No):
>> Current DNS record contents:
>>
>> AAAA record: 2001:db8::1428:57ab
>> A record: 10.0.0.1
>>
>> Delete AAAA record '2001:db8::1428:57ab'? Yes/No (default No): y
>> Delete A record '10.0.0.1'? Yes/No (default No):
>>    Record name: server1
>>    A record: 10.0.0.1
>
> I prepared a rebased version of the patch set for easier review. There
> are few changes:
> - DNS module was extended to mention new interactive modes and options
> - one bug in dnsrecord-mod interactive mode was fixed - only one value
> per DNS type can be modified at one time
> - all translatable strings in DNS module with more than one placeholder
> were converted to dict format
>
> Martin

Just fix these few things before pushing, otherwise ACK x 4:

- Add continuation \\ to the example "Add new reverse zone specified by 
network IP address:"
- Bump VERSION so it applies cleanly against master
- This is probably not an issue since the older clients won't have this 
updated help, but this example does not work on older clients:

# ipa dnsrecord-add example.com @ --mx-preference=20 --mx-exchanger=mail2
Usage: ipa [global-options] dnsrecord-add DNSZONE NAME [options]

ipa: error: no such option: --mx-preference

Something to consider outside the scope of this patch is now that we 
have option groups, break out the standard options into groups. I'm 
thinking about things like output (--all, --raw, --structured), direct 
attribute modification (--addattr, --setattr, --delattr) and 
command-specific. Some balance would be required to not bloat the help 
too much but this kind of clarity has been requested for a while.

This functionality is really good. I'm sure the full rewrites and weeks 
of back and forth have been a drag but the end product is very nice.

Great work.

rob