[Dnsmasq-discuss] Query regarding --leasefile-ro

[Simon Kelley]

On 30/06/14 20:46, Nehal J Wani wrote:
> On Tue, Jul 1, 2014 at 12:27 AM, Simon Kelley <simon at thekelleys.org.uk> wrote:
>> On 30/06/14 10:39, Nehal J Wani wrote:
>>> Hi!
>>>
>>> The man page of dnsmasq (under the section "-9, --leasefile-ro"), states:
>>> When called like this the script should write the saved state of the
>>> lease database, in dnsmasq leasefile format, to stdout and exit with
>>> zero exit code.
>>>
>>> Q1. What is the purpose of printing to stdout? I guess it is for
>>> dnsmasq to know the information of previous leases, but I am not sure.
>>
>>
>> Exactly that. Dnsmasq keeps a working copy of the lease database in
>> memory, and it calls the lease script whenever this changes so that the
>> lease-script can maintain the external copy in whatever non-volatile
>> storage it wants (a database, disk file, NVRAM, etc). When dnsmasq first
>> starts it has to copy the state of the lease database from the
>> non-volatile storage to the in-memory copy. It does this by running the
>> lease-script with the "init" method and the lease-script should dump the
>> contents of the database. The reason the format is exactly the same as
>> the lease-file and to stdout is that the whole thing can be done simply
>> by replacing 'fopen(leasefile)' with 'popen(lease-script, "init")', the
>> rest of the code is unchanged.
>>
>>> Q2. What all information do I need to print in 'dnsmasq leasefile
>>> format' ? What is the exact format? Is there an example for this (like
>>> the example file macscript)?
>>
>> The file starts with IPv4 leases, one per line. There are five fields on
>> each line, seperated by spaces.
>>
>> Expiry time - decimal number, seconds since start of epoch
>>
>> MAC address - a hex "ARP type", followed by '-' followed by zero to 16
>> hex bytes, separated by ':'. If the ARP type is 1, for ethernet (this is
>> most common) then the ARP type is skipped, UNLESS the MAC address in
>> zero length. So
>>
>> 99-00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff
>> 01-
>> 00:11:22:33:44:55
>>
>> are valid strings.
>>
>> IP address in dotted-quad format.
>>
>> Hostname, as specified in RFC 1123, para 2.1, or '*' if no hostname known.
>>
>> Client-id, up to 255 hex bytes separated by ':', or * if no client-id
>> known.
>>
>>
>> Next, if DHCPv6 is in use there may be a single line
>>
>> duid 00:11:22:33
>>
>> which records the DUID used by the server. Max length of a duid is not
>> specified in the standards, I think. dnsmasq limits it to 85 bytes. The
>> longest defined DUID format is currently about 28 bytes, I think.
>>
>> If the duid line exists, then it will be followed by the DHCPv6 leases,
>> one per line, five fields as for IPv4. The fields are different.
>>
>> Expiry time - same definition as for IPv4.
>>
>> IP address - in standard hex-and-colons format
>>
>> IAID Unsigned 32-bit decimal number, possibly preceded by "T" for a
>> temporary lease.
>>
>> Hostname - same as IPv4
>>
>> Client DUID - same representation as IPv4 client-ID.
>>
>>
>>> Q3. Apart from the leases, dnsmasq also prints some extra information
>>> like "duid 00:01:00:01:1b:40:8d:94:00:25:64:8b:e4:2c" in the lease
>>> file. Is this also mandatory to print to stdout in case I use
>>> leasefile-ro ?
>>
>> If you don't want to support DHCPv6, then you don't need the duid and
>> the DHCPv6 lease format. It would be a pity not to support DHPCv6 though.
>>
> 
> That explains almost everything.
> Yes, libvirt wants to support DHCPv6. Right now, the leases helper
> program of ours takes in whatever useful information is available and
> dumps it to a JSON formatted database.
> 
> Example of our custom leases file content:
>     [
>         {
>             "iaid": "1221229",
>             "ip-address": "2001:db8:ca2:2:1::95",
>             "mac-address": "52:54:00:12:a2:6d",
>             "hostname": "Fedora20",
>             "client-id": "00:04:1a:c1:d9:6b:5a:0a:e2:bc:f8:4b:1e:37:2e:38:22:55"
> ,
>             "expiry-time": 1393244216
>         },
>         {
>             "ip-address": "192.168.150.208",
>             "mac-address": "52:54:00:11:56:b3",
>             "hostname": "Wani-PC",
>             "client-id": "01:52:54:00:11:56:b3",
>             "expiry-time": 1393244248
>         }
>     ]
> 
> Q1. The libvirt leases helper script/program takes in whatever
> variable value it receives and stores it unmodified. So, my question
> is, is it safe to just print the content of each lease in the
> field-format that you specified just by copying these values which I
> received earlier as either argument or environment variable (so that
> my code doesn't have to worry about the details about ARP type, etc)?

Yes, completely. The only think you have to worry about the distinction
between ipv4 and ipv6 leases. The second field of a lease line can is
either the MAC address (IPv4) or the IAID, so you need to copy either
argv[2] or the contents of $DNSMASQ_IAID there, depending on the flavour
of the lease. Similary, the fifth field is either the client-id for IPv4
(from $DNSMASQ_CLIENT_ID) or the DUID (from argv[2]) You can reliably
distinguish between IPv4 and IPv6 leases by looking for the presence of
$DNSMASQ_IAID, the way the mactable script does.

> 
> Q1. What harm will we encounter in case we don't store the server DUID
> and not print out when the 'init' argument is received?

You'll break DHCPv6. If the DUID is recreated it will have a different
value (it includes the time of creation), and the clients won't accept
answers from the server, as they will have the old DUID stored as part
of the lease. The value to provide is always in $DNSMASQ_SERVER_DUID for
any call with a DHCPv6 lease,  so the simplest thing might be to store
that with _each_ lease. When responding to an "init" call, just look to
see if there are any IPv6 leases. If there are provide the DUID from any
one (they'll all be the same) before dumping them all.


> 
> Take a sneakpeak at our leasehelper program:
> http://libvirt.org/git/?p=libvirt.git;a=blob;f=src/network/leaseshelper.c

That looks sensible. I guess from these questions that you're thinking
about storing the lease database just in the custom format, and using
--leasefile-ro


Cheers,

Simon.