Updated readme to conform with markdown standards and fixed typos.

README.md

@@ -3,64 +3,81 @@ # CloudflareDDNS
 Update your CloudFlare DNS records with your current (dynamic) IP address via
 systemd timers and a bash script.
 
-**NOTE: You can rename *cfddns.sh* anything you want, the script will
+**NOTE: You can rename *cfddns.sh* to anything you want, the script will
-auto-update itself.  However, you MUST update the systemd service file,
+auto-update itself.  However, you MUST update the systemd service file
-*cfddns.service*, *ExecStart* line manually as explained below**
+*(cfddns.service)* *ExecStart* line manually as explained below.**
+
+## cfddns.sh
 
-## cfddns.sh
 #### Installation:
-I recommend putting this in your */usr/local/bin* directory or somewhere else in
+
-your path so it's easy to run.
+I recommend putting this script in your */usr/local/bin* directory or somewhere
-1. Copy the script file to your desired path (/usr/local/bin recommended) and
+else in your path so it's easy to run.
-   rename as desired.
+
+1. Copy the script file to your desired path and rename if you want.
+
    ```Bash
-   sudo cp cfddns.sh /usr/local/bin/
+   sudo cp cfddns.sh /usr/local/bin/   # just copy it
+   sudo cp cfddns.sh /usr/local/bin/myscript.sh   # copy and rename
    ```
+
 2. Make it executable:
+
    ```Bash
    sudo chmod +x /usr/local/bin/cfddns.sh
    ```
+
 #### Usage:
 If you run the script with no parameters, it will display the help screen.  The
 script accepts several parameters with 2 being required.  The parameters are
-summarized here (taken from the help screen).  You can access the help screen
+summarized here.  You can access the help screen and example usage screens by 
-and example usage screens by running: *cfddns.sh -h* for help and *cfddns.sh -x*
+running:
-for examples.
+
+```Bash
+cfddns.sh -h   # display help screen
+cfddns.sh -x   # show script usage examples
+```
+
+**-f: full path and filename containing account details (REQUIRED)**
+This is the full path to a plain-text file containing your CloudFlare account 
+details.  This file must contain 3 lines in the following order:
 
-**-f: account details file with path**
-This parameter is *required*.  This is the full path to a plain-text file
-containing your CloudFlare account details.  This file must contain 3 lines in
-the following order:
 * authorized email address
    This is an email address that is permitted to login to your CloudFlare account.
 * global api-key
    You can get your Global API-key by going to your CloudFlare dashboard,
    clicking on your profile picture in the upper-right and opening your profile.
-   Scroll to the very bottom to the API Keys section.  Click on the View button
+   Scroll down to to the API Keys section.  Click on the 'View' button next to
-   next to Global API Key.
+   Global API Key.
 * zone identifier
    You should be able to find this on the Overview page of your CloudFlare dashboard.
   
-Your completed file should look like:
+Your completed file should look like (these are not real credentials):
-> johndoe@example.com
+> johndoe<span>@example.com
 > e7882db52804aca6fab22780e055b97056466
 > 492af8aa69f8c44baf043342c74319fd
 
-You should secure this file by changing the owner of the file to root
+Your global API-key is equivalent to your account password, so you should
+secure this file by changing the owner of the file to root
+
 ```Bash
 chown root:root path/to/filename
 ```
+
 and then restricting access to only the root user
+
 ```Bash
 chmod 600 path/to/filename
 ```
-**-r: target DNS entry to update**
+
-At least one entry here is *required*  This is the A or AAAA record you want to
+**-r: target DNS entry to update (REQUIRED)**
+At least one entry here is *required*.  This is the A or AAAA record you want to
 update the IP address for in your DNS zone file.  If you have multiple A or AAAA
 records you want to update, simply specifiy multiple -r parameters.
+
 *Note: You can only specify *either* A records *or* AAAA records.  You have to
-update IP4 and IP6 records by running this script multiple times (once for A
+update IP4 and IP6 records separately by running this script multiple times
-records, once for AAAA records even if the hostname is the same).*
+(once for A records, once for AAAA records even if the hostname is the same).*
 
 **-4 or -6: type of record to update**
 The default option is -4 and it does not need to be specified.  This will update
@@ -71,10 +88,14 @@ #### Usage:
 The script will auto-detect the IP address of the machine it's being run on by
 accessing an external service and asking for that service to echo the machine's
 IP address.  If running with -4, then the IP4 will be requested for echo.  If
-running with -6, then the IP6 addresses will be requested for echo.
+running with -6, then the IP6 address will be requested for echo.
+
 This parameter let's you bypass auto-detection and specify a particular address
-to be used instead.
+to be used instead.  This parameter is most useful if running the script
-*NOTE: The address you supply is NOT checked for correctness.  So ensure you're
+manually to update a particular DNS record.  In most cases, you'd want your
+current IP address auto-detected (i.e. omit this parameter).
+
+*NOTE: The address you supply is NOT checked for correctness.  Ensure you're
 supplying a valid address of the correct type based on your choice of -4 or -6
 parameter!*
 
@@ -82,10 +103,17 @@ #### Usage:
 The script will default to writing it's log file in the same directory as the
 script is located.  It will use it's own name and append a *.log* extension.
 So, the default name for the log file is *cfddns.log*.  If you rename the script
-*something.sh* then the generated log file name will be *something.log*.
+*something&#46;sh* then the generated log file name will be *something.log*.
-This can be messy if you store the script in /usr/bin/local/ as recommended.
+
+This can be messy if you store the script in /usr/local/bin/ as recommended.
 Therefore, it's recommended you choose a different location for
-the logfile (*/var/log/cfddns.log* is recommended).
+the log file (*/var/log/cfddns.log* is recommended).
+
+```Ini
+[Service]
+...
+ExecStart=/usr/local/bin/cfddns.sh -l /var/log/cfddns.log ...
+```
 
 **-h: display help**
 Displays the help screen, which is an abbreviated version of this section you
@@ -96,53 +124,134 @@ #### Usage:
 provided
 
 ## cfddns.service
-This is the systemd file that **must** be copied to your */etc/systemd/system*
+This file **must** be copied to your */etc/systemd/system* directory (or
-directory.  If you change the name of the cfddns.sh file, you must update the
+equivalent directory if you're not running debian/ubuntu).  If you change the 
-filename in the *ExecStart* line as shown below:
+name of the cfddns&#46;sh file, you must update the filename in the *ExecStart*
+line as shown below:
+
 ````Ini
 ...
 [Service]
 Type=oneshot
-ExecStart=/full/path/to/your/renamed.file
+ExecStart=/full/path/to/your/renamed.file -parameter1 -parameter2 -parameter...
 ...
 ````
 
+#### IP4 and/or IP6
+The cfddns.service file includes two *ExecStart* lines, one without a specified
+IP-protocol parameter (default IP4) and the other with the -6 (IP6) parameter.
+The service will run the cfddns&#46;sh script in default (IP4) mode with specified
+parameters first and then will run the script again in IP6 mode with specified
+parameters.
+
+*Note: The parameters *can be different* in each case.*
+
+#### Examples:
+1. **Only update A records**
+  Update *mail<span>.example.com* A record with the current IP of this machine and log
+  results to */var/log/cfddns.log*.
+
+   ```Ini
+   [Service]
+   Type=oneshot
+   ExecStart=/usr/local/bin/cfddns.sh -f /root/accountDetails.cloudflare
+   -r mail.example.com -l /var/log/cfddns.log
+   ...
+   ```
+
+2. **Only update AAAA records**
+  Update *git<span>.example.com* and *mail<span>.example.com* AAAA records with the current
+  IP6 address of this machine. Log will be stored in the same directory as the
+  script file (/usr/local/bin).
+
+   ```Ini
+   [Service]
+   Type=oneshot
+   ExecStart=/usr/local/bin/cfddns.sh -6 -f /home/johndoe/account.details
+   -r git.example.com -r mail.example.com
+   ...
+   ```
+
+3. **Update A records then AAAA records**
+   Update *mail<span>.example.com* A record with current IP address of this machine and
+   write to log file stored at */var/log/DDNS_IP4.log*.  Then, update both
+   *mail<span>.example.com* and *git<span>.example.com* AAAA records with current IP address
+   of this machine and write to log file at */var/log/DDNS_IP6.log*.
+
+   ```Ini
+   [Service]
+   Type=oneshot
+   ExecStart=/usr/local/bin/cfddns.sh -f /dir1/account.cf -r mail.example.com
+   -l /var/log/DDNS_IP4.log
+   ExecStart=/usr/local/bin/cfddns.sh -6 -f /dir2/cloudflare.details
+   -r mail.example.com -r git.example.com -l /var/log/DDNS_IP6.log
+   ...
+   ```
+
 ## cfddns.timer
 This is the timer file that tells your system how often to call the
-cfddns.service file which runs the cfddns.sh script.  By default, the timer is
+cfddns.service file which runs the cfddns&#46;sh script.  By default, the timer is
 set for 5 minutes after the system boots up (to allow for other processes to
-initialize even on slower systems like a RasPi) and then run every 15 minutes
+initialize even on slower systems like a RasPi) and is then run every 15
-thereafter as long as the system is powered on.  Remember when settings your
+minutes thereafter.  Remember when setting your timer that CloudFlare limits
-timer that CloudFlare limits API calls to 1200 every 5 minutes
+API calls to 1200 every 5 minutes.
+
 You can change the timer by modifying the relevant section of the cfddns.timer
 file:
-````Ini
+
+```Ini
 [Timer]
 OnBootSec=5min
 OnUnitActiveSec=15min
-````
+```
-OnBootSec is how long to wait after the system boots up before executing calling
+
-thd cfddns.service.  OnUnitActiveSec will then wait the specified time from that
+*OnBootSec* is how long to wait after the system boots up before executing
-first (after boot) call before calling cfddns.service again.  Therefore,
+the cfddns.service.  *OnUnitActiveSec* will then wait the specified time from that
-eveything is relative to your system boot up.  I recommend setting
+first (after boot) call or after the timer is explicitly started before calling
-OnUnitActiveSec to a low value (like 2 minutes) for testing then setting it to a
+cfddns.service again.  I recommend setting OnUnitActiveSec to a low value (like
-more reasonable time (like 15 minutes) after everything is working.
+2 minutes) for testing then setting it to a more reasonable time (like 15
+minutes) after everything is working.
+
+#### Activation
+You can start the timer system immediately via systemctl
+
+```Bash
+systemctl start cfddns.timer
+```
+
+and can enable it to start automatically on system start up by typing
+
+```Bash
+systemctl enable cfddns.timer
+```
+
+You can check the status of the timer via systemctl also
+
+```Bash
+systemctl status cfddns.timer
+```
+
+It is NOT necessary to enable/start the *cfddns.service*, only the timer needs
+to be active.
 
 ## The log file
 The script logs every major action it takes and provides details on any errors
 it encounters in the log file (see the above section for details on log file
 location and name).  If errors are encountered, they are colour coded red and
 an explanation of the error code is provided.
+
 While the log file is as terse as I felt reasonable, you may still want to
-configure any logwatch programs to further filter things for you so you don't
+configure any log-watch programs to further filter things for you so you don't
 have to review this log as part of your daily routine.  To make that easier, the
-following conventions are observed in the log file:
+following conventions are observed in the log file and can be used to program
-* Errors always appear as "-- [ERROR] text and error code here --"
+your log-watch system:
+
+* Errors always appear as **-- [ERROR] text and error code here --**
 * Errors are followed by an explanation of the specific error code on a new line
-* A clean exit appears as "-- [SUCCESS] some text here --"
+* A clean exit appears as **-- [SUCCESS] some text here --**
-* The script always starts a new set of log entries with "-- Start CloudFlare
+* The script always starts a new set of log entries with **-- Start CloudFlare
-  DDNS script execution --
+  DDNS script execution --**
-* All log file entries start with a time-stamp in [square brackets]
+* All log file entries start with a time-stamp in **[square brackets]**
 
 ## Final thoughts
 I'm by no means an expert in BASH scripting and I only program/script as a hobby