IP Update API documentation clarifications

[fiwswe]

The following refers to: https://github.com/desec-io/desec-stack/blob/main/docs/dyndns/update-api.rst as last updated in #1112.

When using the myip parameter, a mixed-type list of both IPv4 and IPv6 addresses may be given.

https://github.com/desec-io/desec-stack/blame/7f753a9bdc43299cff15a8e9f019b01d2ee82ac5/docs/dyndns/update-api.rst#L138-L139

Both the myip and ip parameters can be used for IPv4 or IPv6 addresses. Does this imply that the above statement is also true for the ip parameter? If so, the documentation should be amended. If not, maybe that should also be mentioned?

In some cases, it is useful to only update the network prefix of existing A or AAAA records. To achieve this, append the prefix length to the IP address query parameter, such as ipv6=2a01:a:b:c::1/64.

https://github.com/desec-io/desec-stack/blame/7f753a9bdc43299cff15a8e9f019b01d2ee82ac5/docs/dyndns/update-api.rst#L141-L143

1. Should it be mentioned that a prefix can be specified for myip, myipv4, ip, myipv6 and ipv6 parameters, i.e. wherever an IP can be specified, not just for the ipv6 parameter shown in the example above?

2. Are there restrictions when specifying both a prefix and an IP in a comma separated list for an address family? (I'm not sure what the result should be if both a prefix and an IP are specified. So this might result in an error?) My guess is that the documentation should state, that either one or more IPs can be specified or one prefix for an address family. Or would specifying both first set the IPs then apply the prefix? (That would kind of negate the requirement that for applying a prefix the RRset must previously exist.)

3. When specifying a list of IPs the rules for using the value preserve or the empty value need to be clarified.

4. When specifying a prefix does the Interface Identifier need to have a non-zero value as implied in the example above? Or should e.g. 2a01:a:b:c::/64 work just as well?

5. Are there any technical restrictions for the value of the prefix? I.e. for IPv4 should any value from 1 to 32 be allowed, and for IPv6 any value from 1-128? Should it be mentioned that for IPv6 any value >64 will interfere with standard Interface Identifiers using the lower 64 bits?

Thanks!
fiwswe

[peterthomassen]

Thanks for this, and apologies for the delay.

When using the myip parameter, a mixed-type list of both IPv4 and IPv6 addresses may be given.

https://github.com/desec-io/desec-stack/blame/7f753a9bdc43299cff15a8e9f019b01d2ee82ac5/docs/dyndns/update-api.rst#L138-L139

Both the myip and ip parameters can be used for IPv4 or IPv6 addresses. Does this imply that the above statement is also true for the ip parameter?

Yes!

In some cases, it is useful to only update the network prefix of existing A or AAAA records. To achieve this, append the prefix length to the IP address query parameter, such as ipv6=2a01:a:b:c::1/64.

https://github.com/desec-io/desec-stack/blame/7f753a9bdc43299cff15a8e9f019b01d2ee82ac5/docs/dyndns/update-api.rst#L141-L143

1. Should it be mentioned that a prefix can be specified for myip, myipv4, ip, myipv6 and ipv6 parameters, i.e. wherever an IP can be specified, not just for the ipv6 parameter shown in the example above?

Feel free to create a PR that makes this more explicit. (In my view, however, it is already clear, because the example given is labeled as such.)

2. Are there restrictions when specifying both a prefix and an IP in a comma separated list for an address family? (I'm not sure what the result should be if both a prefix and an IP are specified. So this might result in an error?) My guess is that the documentation should state, that either one or more IPs can be specified or one prefix for an address family. Or would specifying both first set the IPs then apply the prefix? (That would kind of negate the requirement that for applying a prefix the RRset must previously exist.)

3. When specifying a list of IPs the rules for using the value preserve or the empty value need to be clarified.

Specifying an address along with a subnet or the preserve or empty keyword is an error.

However, I'm not sure we need to spell this out: the docs are for "how to use", not to fully re-tell the implementation. If people configure an invalid scenario, a meaningful error message will be returned. Maybe that's enough, and keeping the docs concise is a goal, too.

4. When specifying a prefix does the Interface Identifier need to have a non-zero value as implied in the example above? Or should e.g. 2a01:a:b:c::/64 work just as well?

Should work, yes. In fact, I think we should zero out the host bits in the example.

5. Are there any technical restrictions for the value of the prefix? I.e. for IPv4 should any value from 1 to 32 be allowed, and for IPv6 any value from 1-128? Should it be mentioned that for IPv6 any value >64 will interfere with standard Interface Identifiers using the lower 64 bits?

There are no restrictions, but I don't think we need to explain what good prefix length values are. Users can't choose the value anyway, but get that assigned by someone else.

[fiwswe]

Thanks for your answers.

I have created PR #1170 for review.