README.me

README.md

@@ -0,0 +1,59 @@
+# GLD Updater
+
+## What's this?
+This script is meant to update the zones of a domain name registered on Gandi and which can be managed using the Gandi LiveDNS API.
+
+This utility replaces all the zones of the given domain(s) by the zones provided in the config file.
+
+As a safety measure, snapshots and local backups of the current zones are provided by default when the script is ran.
+
+Check [full documentation for Gandi LiveDNS API](https://api.gandi.net/docs/livedns/)
+
+## Requirements
+The script uses basic Python 3 modules. So an out-of-the-box Python 3 interpreter should be enough.  
+It has first been written and tested using Python 3.7.3
+
+## Usage
+
+### Config file
+The config file provides all the zones of the domain and is using the YAML format.
+
+```
+example.org:
+    items:
+      - { rrset_name: '@', rrset_type: AAAA, rrset_values: ['2606:2800:220:1:248:1893:25c8:1946'] } 
+      - { rrset_name: 'dns', rrset_type: A, rrset_values: ['1.1.1.1'] } 
+
+```
+See `zones-example.yml` file for full examples.
+
+Notes : 
+* `rrset_type` field must be capital letters only (ex: `AAAA`, `A`, `CNAME`, `SRV` etc.)
+* `rrset_values` must be an array of strings even when composed with only one value (ex: `['127.0.0','1.1.1.1']`)
+* The config file can be composed of multiple domains to manage
+
+### Running the script
+The minimal command goes as simple as:
+```
+# python3 gldns-zones-updater.py -c mydomain-zones.yml -k secretapikey
+```
+
+### Snapshots and backups
+
+#### Snapshots
+Snapshot with the name 'Snapshot from GLD-updater' are automatically created before the new zones are applied.
+
+The snapshot creation can be disabled using the `--no-snapshot` option.  
+
+#### Backups
+Backups are locally created by saving the current zone records as a json file.
+
+By default, the backups will be saved in the same folder as the script in the `BACKUP` directory (will be automatically created if doesn't exist) but the backup destination can be changed using the `--backup-dir` option.
+
+Local backups can be disabled using the `--no-backup` option
+
+## TODO
+* Option to set a custom name for the snapshot
+* Option to revert zones to an existing backup
+* Possibility to specify API key as a field in the config file (?)
+