Added README with documentation and usage details

README.md

@@ -0,0 +1,87 @@
+Cloudflare Dynamic DNS Updater
+==
+
+`cloudflare_dyndns_update` is a simple tool written in Ruby to update
+Dynamic DNS entries on Cloudflare. Following APIs are used in this tool:
+
+  > https://developers.cloudflare.com/api/operations/dns-records-for-a-zone-list-dns-records
+  > https://developers.cloudflare.com/api/operations/dns-records-for-a-zone-patch-dns-record
+
+Installation
+--
+
+The tool can be run by executing `cloudflare_dyndns_update.rb` script from a
+clone of this repository.
+
+Configuration
+--
+
+This tool uses a configuration file, located by default in `~/.cfdyndns.yaml`,
+to get information on hosts to update. An alternate configuration file can be
+specified with the `-f|--config_file` option. Configuration is specified in
+YAML format with a template as follows:
+
+```YAML
+hosts:
+- host: hostone.com
+  zone_id: <cloudflare hostone zone_id>
+- host: hosttwo.com
+  zone_id: <cloudflare hosttwo zone_id>
+- ...
+```
+
+Zone IDs for this file can be obtained from the Cloudflare
+dashboard as mentioned in the URL below.
+
+  > https://developers.cloudflare.com/fundamentals/setup/find-account-and-zone-ids/
+
+Caching
+--
+
+To avoid frequent queries to Cloudflare, tool stores the status of latest update
+to a cache file, located by default in `~/.cfdyndns.cache`. Alternate location
+may be provided with `-c|--cache_file` option.
+
+Cloudflare is updated only if public IP of the host has changed. An update
+can, however, be forced with the `-u|--force_update` option.
+
+Usage
+--
+
+Following usage help is available with the `--help` option:
+
+```
+$ cloudflare_dyndns_update.rb --help
+Usage: cloudflare_dyndns_update.rb [options]
+    -d, --debug                      Enable debug messages
+    -u, --force_update               Force DNS update
+    -f, --config_file FILE           Location of configuration file
+    -c, --cache_file FILE            Location of cache file
+    -k, --api_key KEY                Cloudflare API authorization key
+    -h, --help                       Display this help
+```
+
+Sample log
+--
+
+```log
+I, [2024-02-04T12:04:54.361716 #878203]  INFO -- /home/mahesh/tools/cloudflare_dyndns_update/cloudflare_dyndns_update.rb: Starting...
+I, [2024-02-04T12:04:54.538701 #878203]  INFO -- : Public IP: <public IP>
+I, [2024-02-04T12:04:54.995094 #878203]  INFO -- : Successfully updated DNS entry type A - <host one> - <public IP>
+I, [2024-02-04T12:04:55.725365 #878203]  INFO -- : Successfully updated DNS entry type A - <host two> - <public IP>
+I, [2024-02-04T12:04:56.009757 #878203]  INFO -- : Successfully updated DNS entry type A - <host three> - <public IP>
+I, [2024-02-04T12:04:56.010129 #878203]  INFO -- : Writing updated cache file
+I, [2024-02-04T12:04:56.011406 #878203]  INFO -- /home/mahesh/tools/cloudflare_dyndns_update/cloudflare_dyndns_update.rb: Done.
+...
+I, [2024-02-04T12:07:24.238077 #879022]  INFO -- /home/mahesh/tools/cloudflare_dyndns_update/cloudflare_dyndns_update.rb: Starting...
+I, [2024-02-04T12:07:24.419129 #879022]  INFO -- : Public IP: <same public IP>
+I, [2024-02-04T12:07:24.419249 #879022]  INFO -- : Skipping <host one> - Already pointing to <same public IP>
+I, [2024-02-04T12:07:24.419295 #879022]  INFO -- : Skipping <host two> - Already pointing to <same public IP>
+I, [2024-02-04T12:07:24.419331 #879022]  INFO -- : Skipping <host three> - Already pointing to <same public IP>
+I, [2024-02-04T12:07:24.419365 #879022]  INFO -- /home/mahesh/tools/cloudflare_dyndns_update/cloudflare_dyndns_update.rb: Done.
+```
+
+License
+--
+
+This tool is licensed under the MIT License.