Documentation not so clear on "dynamic" nature

[Chealer]

The cloudflare-ddns command helps dealing with dynamic IP addresses. However, the command itself is not really "dynamic"; it merely verifies that the target record is up-to-date (and updates it if not).

A couple parts of documentation might be misleading (or just make it harder to understand cloudflare-ddns's nature):

Simple utility to dynamically change a DNS record

This description is found on GitHub and in cloudflare-ddns.service.

To make it clearer that cloudflare-ddns(1) is not a daemon, but that the package provides infrastructure to help using it akin to one, I would suggest changing:

1. the service file's description to "Update a domain's IP address using Cloudflare's DNS API"
2. the GitHub description to "Automate DNS updates when using Cloudflare's domain name servers with dynamic IP addresses".

By the way, "oneshot program" is not a common term. I suggest rephrasing "This tool is a oneshot program" as:

The cloudflare-ddns command is not a daemon

[Tachi107]

Hi Philippe. To me, the fact that the tool is not a "true" daemon is an implementation detail. People using the tool don't have to be familiar with the concept of daemons.

I've initially wrote this tool because a friend of mine wanted to get into self-hosting, but his ISP gave him a dynamic IP address. He was not familiar with systemd, daemons, or timers. He just installed the deb package, added his domain name in the config file, and started playing around.

I agree that calling this tool "dynamic" does not accurately reflect the fact that, if looking at it the way you are, it doesn't actually hook into your network stack and listen for events in a truly dynamic fashion, but the point is that you shouldn't have to care. As above, writing something more pedantic is not really in line with the goal of helping all the kinds of users, especially newbies.

That being said, if you're asking me to change the description of the tool I have failed at doing something, and this "implementation detail" has probably caused some issue to you. Could you please help me understand why you've opened this issue? Was the tool not "dynamic enough" for you?

Let me know!

[Chealer]

Hi @Tachi107,

Hi Philippe. To me, the fact that the tool is not a "true" daemon is an implementation detail. People using the tool don't have to be familiar with the concept of daemons.

I fully agree. The only reason why I suggested using that term is because it is immensely more known than the term "oneshot program" (which I would say is not a term at all). So referring to daemons would cause less confusion than referring to "oneshot programs".

I've initially wrote this tool because a friend of mine wanted to get into self-hosting, but his ISP gave him a dynamic IP address. He was not familiar with systemd, daemons, or timers. He just installed the deb package, added his domain name in the config file, and started playing around.

I agree that calling this tool "dynamic" does not accurately reflect the fact that, if looking at it the way you are, it doesn't actually hook into your network stack and listen for events in a truly dynamic fashion, but the point is that you shouldn't have to care. As above, writing something more pedantic is not really in line with the goal of helping all the kinds of users, especially newbies.

That being said, if you're asking me to change the description of the tool I have failed at doing something, and this "implementation detail" has probably caused some issue to you. Could you please help me understand why you've opened this issue? Was the tool not "dynamic enough" for you?

First of all, I applaud the way you approach this report; congratulations for thinking in terms of use cases and about source problems. I found it hard to answer your question, but I hope I managed to explain with the following.

cloudflare-ddns is a project, a package, a software utility and a command. Its README also describes it as a tool, as a library and as a program. Some of these terms can be synonymous, but this plural nature can cause confusion. If a claim in its documentation describes the package a certain way, users may be misled if they understand that claim as about the command.

To answer your question, I have been hosting my personal websites on my friend's Debian server for over a decade. After leaving DynDNS, we went to DNSEXIT. But following poor reliability there, my friend switched his domain to Cloudflare, using cloudflare-ddns. In December, I followed his advice and did the same, without realizing that doing so would be more complicated for me (due to issue #25).

This difficulty prompted me to explore cloudflare-ddns to look for a solution. It took me some time to understand that the command was "oneshot" whereas the package is (arguably) not. Part of my difficulty must be simply due to my experience and the resulting expectations (in the good old days, we used ddclient). This caused me to spend some more time than I should have to understand the architecture enough to find a workaround.

The current documentation can be improved to avoid that (or reduce that risk). Here are a few (mostly related) suggestions:

1. Change the GitHub description to "Simple utility to automate DNS updates when using Cloudflare's domain name servers to point to dynamic IP addresses"
2. Avoid the term "tool" (the occurrence which matters most is solved by my "daemon" suggestion):
   1. in the README (except maybe the third occurrence)
   2. and in the manpage, particularly in the SYNOPSIS.
3. Change the README's first paragraph to something like:

   The cloudflare-ddns package contains the cloudflare-ddns(1) command and libcloudflare-ddns, the C++ library on which the former relies. This package provides a little utility that is really useful when you want to host something but your ISP only provides you dynamic IP addresses and your DNS server is Cloudflare. It uses Cloudflare's web API to update your domain's DNS record(s) when needed.

4. Rename the README's "systemd timer" section to "systemd service", just "systemd", "Service", "Periodic execution", "Automation" or something like that.
5. Add an Installation section to the README, including the Build section and the last paragraph of Usage.
6. Change the service file's description to something like "Cloudflare Dynamic DNS IP address update".

By the way, "eventualmente" and "eventually" are false friends; I suggest s/checks and eventually updates/checks and―if necessary―updates/.