update readme files
This commit is contained in:
Asif Bacchus
parent
ac4cf940ff
commit
d8fe395a19
327
README.md
327
README.md
@ -1,39 +1,53 @@
|
|||||||
# CloudflareDDNS <!-- omit in toc -->
|
# CloudflareDDNS <!-- omit in toc -->
|
||||||
|
|
||||||
Update your CloudFlare DNS records with your current (dynamic) IP address via
|
Update your *existing* Cloudflare DNS records with your current (dynamic) IP address via systemd timers and a (POSIX) shell script.
|
||||||
systemd timers and a bash script.
|
|
||||||
|
|
||||||
**NOTE: You can rename *cfddns.sh* to anything you want, the script will
|
|
||||||
auto-update itself. However, you MUST update the systemd service file
|
|
||||||
*(cfddns.service)* *ExecStart* line manually as explained below.**
|
|
||||||
|
|
||||||
## Contents <!-- omit in toc -->
|
## Contents <!-- omit in toc -->
|
||||||
|
|
||||||
- [cfddns.sh](#cfddns46sh)
|
<!-- toc -->
|
||||||
- [Installation:](#installation)
|
|
||||||
- [Usage:](#usage)
|
- [Prerequisites](#prerequisites)
|
||||||
|
- [cfddns.sh](#cfddns%2346sh)
|
||||||
|
* [Installation](#installation)
|
||||||
|
* [Usage](#usage)
|
||||||
|
+ [Parameters](#parameters)
|
||||||
|
- [Cloudflare credentials file](#cloudflare-credentials-file)
|
||||||
|
* [File structure](#file-structure)
|
||||||
|
* [Bearer token](#bearer-token)
|
||||||
|
* [Zone ID](#zone-id)
|
||||||
- [cfddns.service](#cfddnsservice)
|
- [cfddns.service](#cfddnsservice)
|
||||||
- [IP4 and/or IP6](#ip4-andor-ip6)
|
* [IP4 and/or IP6](#ip4-andor-ip6)
|
||||||
- [Examples](#examples)
|
+ [Examples](#examples)
|
||||||
- [cfddns.timer](#cfddnstimer)
|
- [cfddns.timer](#cfddnstimer)
|
||||||
- [Activation](#activation)
|
* [Activation](#activation)
|
||||||
- [The log file](#the-log-file)
|
- [Logging](#logging)
|
||||||
- [Using Logwatch to monitor this script](#using-logwatch-to-monitor-this-script)
|
* [Using Logwatch to monitor this script](#using-logwatch-to-monitor-this-script)
|
||||||
- [Using Logrotate to control log file size](#using-logrotate-to-control-log-file-size)
|
* [Using Logrotate to control log file size](#using-logrotate-to-control-log-file-size)
|
||||||
- [Final thoughts](#final-thoughts)
|
- [Final thoughts](#final-thoughts)
|
||||||
|
|
||||||
|
<!-- tocstop -->
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
This script requires that `curl` and `jq` are installed. `curl` is used to interact with the Cloudflare API and `jq` is used to efficiently and reliably construct/deconstruct the JSON strings and arrays which is how the Cloudflare API communicates. In most cases you can install these programs using your package manager running as root or via sudo. On Debian/Ubuntu, for example, you would run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apt install -y curl jq
|
||||||
|
```
|
||||||
|
|
||||||
|
While the script does *not* require root privileges, you will need sudo/root access to install the *systemd* service and timer.
|
||||||
|
|
||||||
## cfddns.sh
|
## cfddns.sh
|
||||||
|
|
||||||
### Installation:
|
### Installation
|
||||||
|
|
||||||
I recommend putting this script in your */usr/local/bin* directory or somewhere
|
I recommend putting this script in your */usr/local/bin* directory or somewhere else in your path so it's easy to run.
|
||||||
else in your path so it's easy to run.
|
|
||||||
|
|
||||||
1. Copy the script file to your desired path and rename if you want.
|
1. Copy the script file to your desired path and rename if you want.
|
||||||
|
|
||||||
```Bash
|
```Bash
|
||||||
sudo cp cfddns.sh /usr/local/bin/ # just copy it
|
sudo cp cfddns.sh /usr/local/bin/ # just copy it
|
||||||
sudo cp cfddns.sh /usr/local/bin/myscript.sh # copy and rename
|
sudo cp cfddns.sh /usr/local/bin/cloudflare-update.sh # copy and rename (choose any name)
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Make it executable:
|
2. Make it executable:
|
||||||
@ -42,112 +56,77 @@ ### Installation:
|
|||||||
sudo chmod +x /usr/local/bin/cfddns.sh
|
sudo chmod +x /usr/local/bin/cfddns.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
### Usage:
|
> Note: You can rename *cfddns.sh* to anything you want, the script will auto-update itself. However, you **must** manually update the systemd service file (*cfddns.service*) `ExecStart` line as [explained below](#cfddns.service).
|
||||||
|
|
||||||
If you run the script with no parameters, it will display the help screen. The
|
### Usage
|
||||||
script accepts several parameters with 2 being required. The parameters are
|
|
||||||
summarized here. You can access the help screen and example usage screens by
|
If you run the script with no parameters, it will display the help screen. The script accepts several parameters with only one (1) being required. The parameters are summarized below. You can access the help screen and example usage screens by running:
|
||||||
running:
|
|
||||||
|
|
||||||
```Bash
|
```Bash
|
||||||
cfddns.sh -h # display help screen
|
cfddns.sh --help # display help screen
|
||||||
cfddns.sh -x # show script usage examples
|
cfddns.sh --examples # show script usage examples
|
||||||
```
|
```
|
||||||
|
|
||||||
**-f: full path and filename containing account details (REQUIRED)**
|
#### Parameters
|
||||||
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
|
|Parameter|Description|Default|Required?|
|
||||||
This is an email address that is permitted to login to your CloudFlare account.
|
|---|---|---|:---:|
|
||||||
- global api-key
|
|-r<br>--record<br>--records|The fully qualified hostname(s) that should be updated with new IP addresses. You can supply a comma-delimited list (no spaces) or just one. Note that the script can only update *either* A *or* AAAA records during a single run so you may need to batch your hostnames, depending on your set-up.<br>N.B. This script will only update *existing* host records, it will **not** create new ones!|none|YES|
|
||||||
You can get your Global API-key by going to your CloudFlare dashboard,
|
|-c<br>--cred<br>--creds<br>--credentials<br>-f|Full path to your CloudFlare credentials file. This file contains your access token and zone id. See the [relevant section](#cloudflare-credentials-file) of this readme for more information.|scriptPath/cloudflare.credentials|NO|
|
||||||
clicking on your profile picture in the upper-right and opening your profile.
|
|-i<br>--ip<br>--ip-address<br>-a<br>--address|The IP address that should be used to update Host A/AAAA records. If you omit this value, the script will attempt to auto-detect your public IP4/IP6 address and use that as appropriate. Use this option to manually force a specific IP to be used or when auto-detection fails. Note that the script does *not* check your IP addresses for correctness or proper form!|IP4 auto-detect|NO|
|
||||||
Scroll down to to the API Keys section. Click on the 'View' button next to
|
|-4<br>--ip4<br>--ipv4|Update Host A records only (IP4). The script can only update *either* A *or* AAAA records in a single run. If you specify this and also use the IP6 mode switch, the most recent one will take effect.|Enabled, update A records|NO|
|
||||||
Global API Key.
|
|-6<br>--ip6<br>--ipv6|Update Host AAAA records only (IP6). The script can only update *either* A *or* AAAA records in a single run. If you specify this and also use the IP4 mode switch, the most recent one will take effect.|Disabled, update A records|NO|
|
||||||
- zone identifier
|
|||||
|
||||||
You should be able to find this on the Overview page of your CloudFlare dashboard.
|
|-l<br>--log|Full path where the script should save its log. Recommend */var/log/scriptName.log*|scriptPath/scriptName.log|NO|
|
||||||
|
|--nc<br>--no-color<br>--no-colour|Do not use ANSI colour-coding when writing to the log. This is useful if you review the logs using a reader that does not support ANSI colour-coding and instead displays control symbols which makes your log difficult to read.|Disabled, do colourful logs|NO|
|
||||||
Your completed file should look like (these are not real credentials):
|
|--log-console|Output the log to the console instead of a log file. You may use `--nc` with this option also.|Disabled, write to log file|NO|
|
||||||
|
|--no-log|Do not write a log file or output to the console. You will not have **any** feedback from the script if you run in this mode so you will not know if updates were successful or not. I’m not really sure why you’d want this option, but it’s available.|Disabled, write to log file|NO|
|
||||||
|
|-h<br>--help<br>-?|Display built-in help screen explaining these same parameters.|||
|
||||||
|
|--examples|Display some usage examples. Sometimes it's just easier to understand by seeing rather than reading.|||
|
||||||
|
|
||||||
|
## Cloudflare credentials file
|
||||||
|
|
||||||
|
This repo includes a sample credentials file (*cloudflare.credentials* at the root of the repo) with pretty self-explanatory variable names. The script reads this file to get the credentials it needs to connect to your Cloudflare account and update DNS entries. It should be noted that the script is designed to use a *bearer token* and **not** your username/password or your Global API token! Let’s break this down in case things are a little fuzzy still...
|
||||||
|
|
||||||
|
### File structure
|
||||||
|
|
||||||
|
The file is a basic shell script variables file. Make sure you **do not** put spaces between the variable name, equal sign and the value. Also, **do not** add any executable code since it will be run! The file should contain values for the following two variables:
|
||||||
|
|
||||||
|
| Variable | Value |
|
||||||
|
| -------- | ------------------------------------------------------------ |
|
||||||
|
| cfKey | The bearer token granting access to *edit* the DNS records of the zone (domain) in question. |
|
||||||
|
| cfZoneId | The Cloudflare Zone ID of the zone (domain) you wish to update. |
|
||||||
|
|
||||||
|
You can add comments if you’d like since the script will ignore them. In the end, your file should look something like this, but obviously with your data instead of this nonsense sample information:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
#
|
||||||
|
# Cloudflare token for my.domain.tld
|
||||||
|
#
|
||||||
|
|
||||||
|
cfKey=_dLuyyRNaKN8SLG4-csmNYYfC39nnCmPVA7aYUJj
|
||||||
|
cfZoneId=83d564234134513245311b23412331dd
|
||||||
|
|
||||||
```
|
|
||||||
johndoe@example.com
|
|
||||||
e7882db52804aca6fab22780e055b97056466
|
|
||||||
492af8aa69f8c44baf043342c74319fd
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Your global API-key is equivalent to your account password, so you should
|
You can save the file as anything you like and anywhere you’d like as long as you inform the script of its location using the `--credentials` parameter. By default, the script will look for a file named *cloudflare.credentials* in the same path as the script.
|
||||||
secure this file by changing the owner of the file to root
|
|
||||||
|
|
||||||
```Bash
|
### Bearer token
|
||||||
chown root:root path/to/filename
|
|
||||||
```
|
|
||||||
|
|
||||||
and then restricting access to only the root user
|
I chose to use an API bearer token instead of a username/password or Global API token for security reasons. Your username/password and Global API token provide unfettered access to your account so if anyone gets hold of them, they can do anything to your account. An API bearer token, by contrast, can only do what you authorize it to do and you can revoke it at any time. Therefore, I suggest making a bearer token that is based on the “Edit zone DNS” template and restricted to the specific domain/zone you wish to update. Cloudflare provides an [excellent article](https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys) on how to generate this token.
|
||||||
|
|
||||||
```Bash
|
> N.B. This is a breaking change from previous versions of this script!
|
||||||
chmod 600 path/to/filename
|
|
||||||
```
|
|
||||||
|
|
||||||
**-r: target DNS entry to update (REQUIRED)**
|
### Zone ID
|
||||||
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
|
This is required by the Cloudflare API so it knows which zone you are editing and can check the permissions of the bearer token. This script only caters to one zone so likely only one domain per configuration file. If you need to update multiple zones, you can have multiple configuration files and call them as required on separate invocations of the script.
|
||||||
update IP4 and IP6 records separately by running this script multiple times
|
|
||||||
(once for A records, once for AAAA records even if the hostname is the same).*
|
|
||||||
|
|
||||||
**-4 or -6: type of record to update**
|
To get your Zone ID, log into your Cloudflare account and open the domain in question. On the overview page, scroll down a bit and look to the right. You will see your Zone ID listed there. Copy that string into your configuration file.
|
||||||
The default option is -4 and it does not need to be specified. This will update
|
|
||||||
*A records* specified by the -r parameter(s). If you specify -6, then *AAAA
|
|
||||||
records* will updated as specified by the -r parameter(s).
|
|
||||||
|
|
||||||
**-i: use the specified IP address**
|
|
||||||
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 address will be requested for echo.
|
|
||||||
|
|
||||||
This parameter let's you bypass auto-detection and specify a particular address
|
|
||||||
to be used instead. This parameter is most useful if running the script
|
|
||||||
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!*
|
|
||||||
|
|
||||||
**-l (lower-case L): specify where the log file should be written**
|
|
||||||
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*.
|
|
||||||
|
|
||||||
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 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
|
|
||||||
are currently reading.
|
|
||||||
|
|
||||||
**-x: display examples**
|
|
||||||
This is the best way to learn how this script works. Several examples are
|
|
||||||
provided
|
|
||||||
|
|
||||||
## cfddns.service
|
## cfddns.service
|
||||||
|
|
||||||
This file **must** be copied to your */etc/systemd/system* directory (or
|
This file **must** be copied to your */etc/systemd/system* directory (or equivalent directory if you're not running Debian/Ubuntu). If you change the name of the cfddns.sh file, you must update the filename in the `ExecStart` line as shown below:
|
||||||
equivalent directory if you're not running debian/ubuntu). If you change the
|
|
||||||
name of the cfddns.sh file, you must update the filename in the *ExecStart*
|
|
||||||
line as shown below:
|
|
||||||
|
|
||||||
````Ini
|
````Ini
|
||||||
...
|
...
|
||||||
@ -157,66 +136,58 @@ ## cfddns.service
|
|||||||
...
|
...
|
||||||
````
|
````
|
||||||
|
|
||||||
|
Don’t forget to reload systemd after copying this file so it is recognized by the system! On most systems you can do this by running the following as root or via sudo:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
systemctl daemon-reload
|
||||||
|
```
|
||||||
|
|
||||||
### IP4 and/or IP6
|
### IP4 and/or IP6
|
||||||
|
|
||||||
The cfddns.service file includes two *ExecStart* lines, one without a specified
|
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.sh script in default (IP4) mode with specified parameters first and then will run the script again in IP6 mode with specified parameters.
|
||||||
IP-protocol parameter (default IP4) and the other with the -6 (IP6) parameter.
|
|
||||||
The service will run the cfddns.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.*
|
*Note: The parameters *can be different* in each case.*
|
||||||
|
|
||||||
#### Examples
|
#### Examples
|
||||||
|
|
||||||
1. **Only update A records**
|
1. **Only update A records**
|
||||||
Update *mail<span>.example.com* A record with the current IP of this machine and log
|
Update *mail<span>.example.com* A record with the current auto-detected public IP4 address of this machine and log results to */var/log/cfddns.log*.
|
||||||
results to */var/log/cfddns.log*.
|
|
||||||
|
```Ini
|
||||||
```Ini
|
|
||||||
[Service]
|
[Service]
|
||||||
Type=oneshot
|
Type=oneshot
|
||||||
ExecStart=/usr/local/bin/cfddns.sh -f /root/accountDetails.cloudflare -r mail.example.com -l /var/log/cfddns.log
|
ExecStart=/usr/local/bin/cfddns.sh -c /root/cloudflare.credentials -r mail.example.com -l /var/log/cfddns.log
|
||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **Only update AAAA records**
|
2. **Only update AAAA records**
|
||||||
Update *git<span>.example.com* and *mail<span>.example.com* AAAA records with the current
|
Update *git<span>.example.com* and *mail<span>.example.com* AAAA records with the current auto-detected public IP6 address of this machine. Log will be stored in the same directory as the script file (/usr/local/bin).
|
||||||
IP6 address of this machine. Log will be stored in the same directory as the
|
|
||||||
script file (/usr/local/bin).
|
|
||||||
|
|
||||||
```Ini
|
```Ini
|
||||||
[Service]
|
[Service]
|
||||||
Type=oneshot
|
Type=oneshot
|
||||||
ExecStart=/usr/local/bin/cfddns.sh -6 -f /home/johndoe/account.details -r git.example.com -r mail.example.com
|
ExecStart=/usr/local/bin/cfddns.sh -6 -c /home/johndoe/cloudflare.credentials -r git.example.com,mail.example.com
|
||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
3. **Update A records then AAAA records**
|
3. **Update A records then AAAA records**
|
||||||
Update *mail<span>.example.com* A record with current IP address of this machine and
|
Update *mail<span>.example.com* A record with auto-detected public IP4 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 the specified IP6 address and write to log file at */var/log/DDNS_IP6.log*.
|
||||||
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
|
```Ini
|
||||||
[Service]
|
[Service]
|
||||||
Type=oneshot
|
Type=oneshot
|
||||||
ExecStart=/usr/local/bin/cfddns.sh -f /dir1/account.cf -r mail.example.com -l /var/log/DDNS_IP4.log
|
# update IP4 addresses
|
||||||
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
|
ExecStart=/usr/local/bin/cfddns.sh -c /dir1/account.cf -r mail.example.com -l /var/log/DDNS_IP4.log
|
||||||
|
# update IP6 addresses
|
||||||
|
ExecStart=/usr/local/bin/cfddns.sh -6 -c /dir2/cloudflare.details -r mail.example.com,git.example.com --ip fd3f:e6db:9817:df84::a001 -l /var/log/DDNS_IP6.log
|
||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
## cfddns.timer
|
## cfddns.timer
|
||||||
|
|
||||||
This is the timer file that tells your system how often to call the
|
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 set for 5 minutes after the system boots up (to allow for other processes to initialize even on slower systems like a RasPi) and is then run every 15 minutes thereafter. Remember when setting your timer that Cloudflare limits API calls to 1200 every 5 minutes.
|
||||||
cfddns.service file which runs the cfddns.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 is then run every 15
|
|
||||||
minutes thereafter. Remember when setting your timer that CloudFlare limits
|
|
||||||
API calls to 1200 every 5 minutes.
|
|
||||||
|
|
||||||
You can change the timer by modifying the relevant section of the cfddns.timer
|
You can change the timer by modifying the relevant section of the *cfddns.timer* file:
|
||||||
file:
|
|
||||||
|
|
||||||
```Ini
|
```Ini
|
||||||
[Timer]
|
[Timer]
|
||||||
@ -224,22 +195,18 @@ ## cfddns.timer
|
|||||||
OnUnitActiveSec=15min
|
OnUnitActiveSec=15min
|
||||||
```
|
```
|
||||||
|
|
||||||
*OnBootSec* is how long to wait after the system boots up before executing
|
*OnBootSec* is how long to wait after the system boots up before executing the *cfddns.service*. *OnUnitActiveSec* will then wait the specified time from that first (after boot) call or after the timer is explicitly started before calling *cfddns.service* again. I recommend setting OnUnitActiveSec to a low value (like 2 minutes) for testing then setting it to a more reasonable time (like 15
|
||||||
the cfddns.service. *OnUnitActiveSec* will then wait the specified time from that
|
|
||||||
first (after boot) call or after the timer is explicitly started before calling
|
|
||||||
cfddns.service again. I recommend setting OnUnitActiveSec to a low value (like
|
|
||||||
2 minutes) for testing then setting it to a more reasonable time (like 15
|
|
||||||
minutes) after everything is working.
|
minutes) after everything is working.
|
||||||
|
|
||||||
### Activation
|
### Activation
|
||||||
|
|
||||||
You can start the timer system immediately via systemctl
|
You can start the timer system immediately via *systemctl*
|
||||||
|
|
||||||
```Bash
|
```Bash
|
||||||
systemctl start cfddns.timer
|
systemctl start cfddns.timer
|
||||||
```
|
```
|
||||||
|
|
||||||
and can enable it to start automatically on system start up by typing
|
and can enable it to start automatically on boot by typing
|
||||||
|
|
||||||
```Bash
|
```Bash
|
||||||
systemctl enable cfddns.timer
|
systemctl enable cfddns.timer
|
||||||
@ -251,55 +218,45 @@ ### Activation
|
|||||||
systemctl status cfddns.timer
|
systemctl status cfddns.timer
|
||||||
```
|
```
|
||||||
|
|
||||||
It is NOT necessary to enable/start the *cfddns.service*, only the timer needs
|
It is NOT necessary to enable/start the *cfddns.service*, only the timer needs to be active.
|
||||||
to be active.
|
|
||||||
|
|
||||||
## The log file
|
## Logging
|
||||||
|
|
||||||
The script logs every major action it takes and provides details on any errors
|
The script logs every major action it takes and provides details on any errors it encounters in the log file (see the [parameters section](#parameters) for details about setting log location and name). If errors are encountered, they are colour coded red and an explanation of the error code is provided.
|
||||||
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
|
While the log file is as terse as I felt reasonable, you may still want to 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 and can be used to program your log-watch system:
|
||||||
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 and can be used to program
|
|
||||||
your log-watch system:
|
|
||||||
|
|
||||||
- Errors always appear as **-- [ERROR] text and error code here --**
|
- Specific update process errors: **[TIMESTAMP] ERR: message**
|
||||||
- Errors are followed by an explanation of the specific error code on a new line
|
- These can be counted/filtered separately if you only care about update errors and not any other errors.
|
||||||
- A clean exit appears as **-- [SUCCESS] some text here --**
|
- Error messages: **[TIMESTAMP] ERROR: message (code: number)**
|
||||||
- The script always starts a new set of log entries with **-- Start CloudFlare
|
- Only one summary error message will be displayed for any/all update errors. This message contains a tally of failed updates. If you want to count individual update errors, filter for the above process error message format.
|
||||||
DDNS script execution --**
|
- While process error messages only relate to updates, these general error messages are logged for a variety of error conditions so it’s a good idea to include them in any filters.
|
||||||
- All log file entries start with a time-stamp in **[square brackets]**
|
- Cloudflare API error messages: **[TIMESTAMP] CF-ERR: message (code: cf-error-code)**
|
||||||
|
- These are only logged when update process errors occur so that you can see exactly what the Cloudflare API is complaining about.
|
||||||
|
- Specific update process warnings: **[TIMESTAMP] WARN: message**
|
||||||
|
- These can be counted/filtered separately from general warning messages. Presently, there are *no* general warning messages.
|
||||||
|
- Warning messages: **[TIMESTAMP] WARNING: message**
|
||||||
|
- Summary of each type of warning. Contains a tally of the specific warning.
|
||||||
|
- Currently, warnings are only issued for hostnames that are not found (i.e. update process warnings).
|
||||||
|
- Success messages: **[TIMESTAMP] SUCCESS: message**
|
||||||
|
- Each successful update generates a success message. There is no process or tally message.
|
||||||
|
- Already up-to-date: **[TIMESTAMP] IP address for {fqdn} is already up-to-date**
|
||||||
|
- Already up-to-date host entries generate a success message but you may still want to filter for them separately using this criteria.
|
||||||
|
- A session log always starts with **[TIMESTAMP] -- Cloudflare DDNS update-script: starting --**
|
||||||
|
- A successful session log always ends with **[TIMESTAMP] -- Cloudflare DDNS update-script: completed successfully --**
|
||||||
|
- A session ending with errors always ends with **[TIMESTAMP] -- Cloudflare DDNS update-script: completed with error(s) --**
|
||||||
|
|
||||||
### Using Logwatch to monitor this script
|
### Using Logwatch to monitor this script
|
||||||
|
|
||||||
If you are using the Logwatch package to monitor your system, **see the README
|
If you are using the Logwatch package to monitor your system, see the README in the */etc/logwatch* folder for details about the pre-configured service files already done for you :-)
|
||||||
in the /etc/logwatch folder** for details about the pre-configured service files
|
|
||||||
already done for you :-)
|
|
||||||
|
|
||||||
### Using Logrotate to control log file size
|
### Using Logrotate to control log file size
|
||||||
|
|
||||||
Logrotate is pre-installed on standard Debian/Ubuntu distributions and is a great
|
Logrotate is pre-installed on standard Debian/Ubuntu distributions and is a great way to automatically rotate your log files and control how many old logs you keep on your system so they don't accumulate and eat up your disk space. I've included a sample configuration file you can copy to your */etc/logrotate.d/* folder. This file is set up to rotate your logs once a week, keep 3 weeks worth of history (compressed) and delete all logs older than that. The configuration file is located in this git archive at
|
||||||
way to automatically rotate your log files and control how many old logs you
|
*/etc/logrotate.d/cfddns* and is fully commented to help you customize it to suit your needs.
|
||||||
keep on your system so they don't accumulate and eat up your disk space.
|
|
||||||
|
|
||||||
I've included a sample configuration file you can copy to your
|
|
||||||
*/etc/logrotate.d/* folder. This file is set up to rotate your logs once a
|
|
||||||
week, keep 3 weeks worth of history (compressed) and delete all logs older than
|
|
||||||
that. The configuration file is located in this git archive at
|
|
||||||
*/etc/logrotate.d/cfddns* and is fully commented to help you customize it to
|
|
||||||
suit your needs.
|
|
||||||
|
|
||||||
## Final thoughts
|
## Final thoughts
|
||||||
|
|
||||||
I'm by no means an expert in BASH scripting and I only program/script as a hobby
|
Hopefully this helps you with an easy and reliable way to update your Cloudflare DNS entries with a dynamic IP address. Please feel free to comment and provide feedback and suggestions to make this script better!
|
||||||
when I find stuff that irritates me and no other good solutions seem easily
|
|
||||||
available. So, by all means, please comment, provide feedback and suggestions
|
|
||||||
to make this script better! Thanks, I hope this helps someone else out!
|
|
||||||
|
|
||||||
Please check out my blog at
|
Please check out my blog at [https://mytechiethoughts.com](https://mytechiethoughts.com) where I tackle problems like this all the time and find free/cheap solutions to tech problems.
|
||||||
[https://mytechiethoughts.com](https://mytechiethoughts.com) where I tackle
|
|
||||||
problems like this all the time and find free/cheap solutions to tech problems.
|
|
||||||
@ -1,45 +1,25 @@
|
|||||||
# Using Logwatch to monitor Cloudflare DDNS updater script <!-- omit in toc -->
|
# Using Logwatch to monitor Cloudflare DDNS updater script <!-- omit in toc -->
|
||||||
|
|
||||||
The Cloudflare DDNS update script's log file has been set up so that utilities
|
The Cloudflare DDNS update script's log file has been set up so that utilities like Logwatch can easily parse it. In order to make that happen, a LogFile Group file, Service and Script have to be created for Logwatch to generate reports. The correct (general) directory structure has been created in this git archive already. Below are the details of each file.
|
||||||
like Logwatch can easily parse it. In order to make that happen, a LogFile
|
|
||||||
Group file, Service and Script have to be created for Logwatch to generate
|
|
||||||
reports. The correct (general) directory structure has been created in this git
|
|
||||||
archive already. Below are the details of each file.
|
|
||||||
|
|
||||||
## Contents <!-- omit in toc -->
|
## Contents <!-- omit in toc -->
|
||||||
|
|
||||||
- [LogFile Group file (/etc/logwatch/conf/logfiles/cfddns.conf)](#logfile-group-file-etclogwatchconflogfilescfddnsconf)
|
<!-- toc -->
|
||||||
- [Log file location](#log-file-location)
|
|
||||||
- [Archive location and name format](#archive-location-and-name-format)
|
<!-- tocstop -->
|
||||||
- [External script for timestamp processing](#external-script-for-timestamp-processing)
|
|
||||||
- [Service definition file (/etc/logwatch/conf/services/cfddns.conf)](#service-definition-file-etclogwatchconfservicescfddnsconf)
|
|
||||||
- [LogFile Group file definition](#logfile-group-file-definition)
|
|
||||||
- [Report title](#report-title)
|
|
||||||
- [Detail level](#detail-level)
|
|
||||||
- [Service script (/etc/logwatch/scripts/services/cfddns)](#service-script-etclogwatchscriptsservicescfddns)
|
|
||||||
- [Detail levels](#detail-levels)
|
|
||||||
- [Timestamp processing script (/etc/logwatch/scripts/shared/sqfullstampanywhere)](#timestamp-processing-script-etclogwatchscriptssharedsqfullstampanywhere)
|
|
||||||
- [The time format specification](#the-time-format-specification)
|
|
||||||
- [The search REGEX](#the-search-regex)
|
|
||||||
- [Testing](#testing)
|
|
||||||
- [Final thoughts](#final-thoughts)
|
|
||||||
|
|
||||||
## LogFile Group file (/etc/logwatch/conf/logfiles/cfddns.conf)
|
## LogFile Group file (/etc/logwatch/conf/logfiles/cfddns.conf)
|
||||||
|
|
||||||
### Log file location
|
### Log file location
|
||||||
|
|
||||||
Update this as needed to point to the location and name of the log file
|
Update this as needed to point to the location and name of the log file generated by the updater script. Remember, by default, the log file is created in the same directory as the script itself.
|
||||||
generated by the updater script. Remember, by default, the log file is created
|
|
||||||
in the same directory as the script itself.
|
|
||||||
|
|
||||||
```Ini
|
```Ini
|
||||||
LogFile = /path/to/your/cfddns.log
|
LogFile = /path/to/your/cfddns.log
|
||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
Best practices suggest you use the *-l*
|
Best practices suggest you use the `--log` flag to change this location to something like */var/log/cfddns.log*, for example. In that case, the entry would look like:
|
||||||
flag to change this location to something like */var/log/cfddns.log*, for
|
|
||||||
example. In that case, the entry would look like:
|
|
||||||
|
|
||||||
```Ini
|
```Ini
|
||||||
LogFile = /var/log/cfddns.log
|
LogFile = /var/log/cfddns.log
|
||||||
@ -48,12 +28,7 @@ ### Log file location
|
|||||||
|
|
||||||
### Archive location and name format
|
### Archive location and name format
|
||||||
|
|
||||||
If you want Logwatch to process old (archived) log files generated by something
|
If you want Logwatch to process old (archived) log files generated by something like *Logrotate*, then you have to specify the location and file name format of those files. I've included the generalized compressed format of such rotated files as the default in the script. Suppose you store your log files in the recommended location (*/var/log/*) and are using *Logrotate* with compression enabled, the archive line would look like:
|
||||||
like *Logrotate*, then you have to specify the location and file name format of
|
|
||||||
those files. I've included the generalized compressed format of such rotated
|
|
||||||
files as the default in the script. Suppose you store your log files in the
|
|
||||||
recommended location (*/var/log/*) and are using *Logrotate* with compression
|
|
||||||
enabled, the archive line would look like:
|
|
||||||
|
|
||||||
```Ini
|
```Ini
|
||||||
...
|
...
|
||||||
@ -61,19 +36,13 @@ ### Archive location and name format
|
|||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
This would tell Logwatch, when the archive option is set to true, that your
|
This would tell Logwatch, when the archive option is set to true, that your *cfddns.log* files are archived as: *cfddns.log.1.gz*, *cfddns.log.2.gz*, etc. and are all located in */var/log/*.
|
||||||
*cfddns.log* files are archived as: *cfddns.log.1.gz*, *cfddns.log.2.gz*, etc.
|
|
||||||
and are all located in */var/log/*.
|
|
||||||
|
|
||||||
**Note: This line is totally optional and only used if you set the archive
|
> Note: This line is totally optional and only used if you set the archive option in Logwatch to true. You can comment/delete this line if you wish.
|
||||||
option in Logwatch to true. You can comment/delete this line if you wish.**
|
|
||||||
|
|
||||||
### External script for timestamp processing
|
### External script for timestamp processing
|
||||||
|
|
||||||
Since the log file uses a non-standard (according to Logwatch) method of
|
Since the log file uses a non-standard (according to Logwatch) method of datestamping, a custom filter had to be created. See the [relevant](#timestamp-processing-script-etclogwatchscriptssharedsqfullstampanywhere) section of this document for more information.
|
||||||
datestamping, a custom filter had to be created. See the
|
|
||||||
[relevant](#timestamp-processing-script-etclogwatchscriptssharedsqfullstampanywhere)
|
|
||||||
section of this document for more information.
|
|
||||||
|
|
||||||
The script file is called with an *\** before the filename.
|
The script file is called with an *\** before the filename.
|
||||||
|
|
||||||
@ -83,31 +52,24 @@ ### External script for timestamp processing
|
|||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
If you change the name of this file, you will have to change this line.
|
If you change the name of this file, you will have to change this line. Remember that whatever you type here as a name is converted to all-lowercase so your filename should be all lowercase also.
|
||||||
Remember that whatever you type here as a name is converted to all-lowercase
|
|
||||||
so your filename should be all lowercase also.
|
|
||||||
|
|
||||||
## Service definition file (/etc/logwatch/conf/services/cfddns.conf)
|
## Service definition file (/etc/logwatch/conf/services/cfddns.conf)
|
||||||
|
|
||||||
### LogFile Group file definition
|
### LogFile Group file definition
|
||||||
|
|
||||||
The service file needs to know what group of log files it is responsible for
|
The service file needs to know what group of log files it is responsible for processing. This MUST match the name of your *LogFile Group file*:
|
||||||
processing. This MUST match the name of your *LogFile Group file*:
|
|
||||||
|
|
||||||
```Ini
|
```Ini
|
||||||
LogFile = cfddns
|
LogFile = cfddns
|
||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
If you change your LogFile Group filename, then update it here too without the
|
If you change your LogFile Group filename, then update it here also without the *.conf* extension.
|
||||||
*.conf* extension.
|
|
||||||
|
|
||||||
### Report title
|
### Report title
|
||||||
|
|
||||||
The Logwatch output file (html or text) is divided into sections. You can
|
The Logwatch output file (html or text) is divided into sections. You can define the title to be anything that has meaning for you. I have arbitrarily chosen *"CloudFlare DDNS update"* but you can change it to anything you want by modifying the line:
|
||||||
define the title to be anything that has meaning for you. I have arbitrarily
|
|
||||||
chosen *"CloudFlare DDNS update"* but you can change it to anything you want by
|
|
||||||
modifying the line:
|
|
||||||
|
|
||||||
```Ini
|
```Ini
|
||||||
...
|
...
|
||||||
@ -115,10 +77,7 @@ ### Report title
|
|||||||
```
|
```
|
||||||
### Detail level
|
### Detail level
|
||||||
|
|
||||||
If you want to set the *detail* level of this service differently from your
|
If you want to set the *detail* level of this service differently from your other services (which will use the *--detail* switch value or the value in your *logwatch.conf*), then you can define that level here. By default, it appears like this in the service configuration file:
|
||||||
other services (which will use the *--detail* switch value or the value in your
|
|
||||||
*logwatch.conf*), then you can define that level here. By default, it appears
|
|
||||||
like this in the service configuration file:
|
|
||||||
|
|
||||||
```Ini
|
```Ini
|
||||||
...
|
...
|
||||||
@ -127,8 +86,7 @@ # Remember the levels are: 0, 1-4, 5, 6+
|
|||||||
# Detail = 0
|
# Detail = 0
|
||||||
```
|
```
|
||||||
|
|
||||||
Simply change it to the value you want enforced. For example, here I'm setting
|
Simply change it to the value you want enforced. For example, here I'm setting it to output level 5 regardless of whatever settings everything else is using.
|
||||||
it to output level 5 regardless of whatever settings everything else is using.
|
|
||||||
|
|
||||||
```Ini
|
```Ini
|
||||||
# Override the detail level for this service
|
# Override the detail level for this service
|
||||||
@ -138,16 +96,10 @@ # Remember the levels are: 0, 1-4, 5, 6+
|
|||||||
|
|
||||||
## Service script (/etc/logwatch/scripts/services/cfddns)
|
## Service script (/etc/logwatch/scripts/services/cfddns)
|
||||||
|
|
||||||
Logwatch calls any script with a name that **matches the service name**. You'll
|
Logwatch calls any script with a name that **matches the service name**. You'll notice that I just named everything *cfddns* to keep things simple. You can change this to whatever you want, however. If you changed the service name to *"cloudflare*.conf", for example, you would have to rename this script file to "*cloudflare*" with no extension. Note: The script is a PERL file (note the
|
||||||
notice that I just named everything *cfddns* to keep things simple. You can
|
|
||||||
change this to whatever you want, however. If you changed the service name to
|
|
||||||
*"cloudflare*.conf", for example, you would have to rename this script file to
|
|
||||||
"*cloudflare*" with no extension. Note: The script is a PERL file (note the
|
|
||||||
shebang) but it can be written in any language.
|
shebang) but it can be written in any language.
|
||||||
|
|
||||||
In essence, Logwatch just spits out the log file(s) defined in the LogFile Group
|
In essence, Logwatch just spits out the log file(s) defined in the LogFile Group file as standard input (STDIN) for the script and then takes whatever is output (STDOUT) from the script to assemble into its report.
|
||||||
file as standard input (STDIN) for the script and then takes whatever is output
|
|
||||||
(STDOUT) from the script to assemble into it's report.
|
|
||||||
|
|
||||||
### Detail levels
|
### Detail levels
|
||||||
|
|
||||||
@ -192,20 +144,11 @@ ### Detail levels
|
|||||||
|
|
||||||
## Timestamp processing script (/etc/logwatch/scripts/shared/sqfullstampanywhere)
|
## Timestamp processing script (/etc/logwatch/scripts/shared/sqfullstampanywhere)
|
||||||
|
|
||||||
This is basically a modified version of the '*applyeurodate*' script that comes
|
This is basically a modified version of the '*applyeurodate*' script that comes with Logwatch. It had to be modified to search within [square brackets] and to accept characters coming before the stamp (i.e. ANSI colour codes). If you change the '**stamp**' variable in the updater script to update the timestamp to your liking (which to totally fine!) then you'll probably have to update this file. There are two lines you need to modify to suit your new '**stamp**' variable.
|
||||||
with Logwatch. It had to be modified to search within [square brackets] and to
|
|
||||||
accept characters coming before the stamp (i.e. ANSI colour codes). If you
|
|
||||||
change the '**stamp**' variable in the updater script to update the timestamp to
|
|
||||||
your liking (which to totally fine!) then you'll probably have to update this
|
|
||||||
file. There are two lines you need to modify to suit your new '**stamp**'
|
|
||||||
variable.
|
|
||||||
|
|
||||||
### The time format specification
|
### The time format specification
|
||||||
|
|
||||||
'*$SearchDate*' is the variable used in the PERL script to do exactly what it
|
'*$SearchDate*' is the variable used in the PERL script to do exactly what it says, search for the date stamp. I have it set up to look for the format '*year-month-date hour:minute:second*'. Note, we don't care about brackets or anything here, we're just defining the format of the date/time stamp.
|
||||||
says, search for the date stamp. I have it set up to look for the format
|
|
||||||
'*year-month-date hour:minute:second*'. Note, we don't care about brackets or
|
|
||||||
anything here, we're just defining the format of the date/time stamp.
|
|
||||||
|
|
||||||
```Perl
|
```Perl
|
||||||
...
|
...
|
||||||
@ -213,9 +156,7 @@ ### The time format specification
|
|||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
If you changed the '**stamp**' variable so it was formatted as '*month/day/year
|
If you changed the '**stamp**' variable so it was formatted as '*month/day/year hour:minute*' (ex: '*[09/27/2018 18:38]*') then you'd update the **$SearchDate** variable as follows (note: no mention of the square brackets!):
|
||||||
hour:minute*' (ex: '*[09/27/2018 18:38]*') then you'd update the **$SearchDate**
|
|
||||||
variable as follows (note: no mention of the square brackets!):
|
|
||||||
|
|
||||||
```Perl
|
```Perl
|
||||||
...
|
...
|
||||||
@ -225,8 +166,7 @@ ### The time format specification
|
|||||||
|
|
||||||
### The search REGEX
|
### The search REGEX
|
||||||
|
|
||||||
The PERL script uses a '*regular expression*' (REGEX) to search within the log file for
|
The PERL script uses a '*regular expression*' (REGEX) to search within the log file for '*$SearchDate*'. For the default datestamp, this specification looks like:
|
||||||
'*$SearchDate*'. For the default datestamp, this specification looks like:
|
|
||||||
|
|
||||||
```Perl
|
```Perl
|
||||||
...
|
...
|
||||||
@ -234,12 +174,7 @@ ### The search REGEX
|
|||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
The REGEX appears between '*m/*' and '*/o*'. In this case, it searches for
|
The REGEX appears between '*m/*' and '*/o*'. In this case, it searches for '*$SearchDate*' inside [square brackets] appearing anywhere on the line. This is because ANSI colour-codes often appear before the datestamp in the default log file. If you have modified this so that your datestamp appears at the beginning of the line and in the example format in the section above (using slashes instead of dashes) then you'd rewrite this REGEX as follows:
|
||||||
'*$SearchDate*' inside [square brackets] appearing anywhere on the line. This
|
|
||||||
is because ANSI colour-codes often appear before the datestamp in the default
|
|
||||||
log file. If you have modified this so that your datestamp appears at the
|
|
||||||
beginning of the line and in the example format in the section above (using
|
|
||||||
slashes instead of dashes) then you'd rewrite this REGEX as follows:
|
|
||||||
|
|
||||||
```Perl
|
```Perl
|
||||||
...
|
...
|
||||||
@ -265,16 +200,14 @@ ### The search REGEX
|
|||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
||||||
Run *logwatch --help* and note the options. You can test just this service
|
Run *logwatch --help* and note the options. You can test just this service locally on your screen with the following command (assuming you kept default names for everything):
|
||||||
locally on your screen with the following command (assuming you kept default
|
|
||||||
names for everything):
|
|
||||||
|
|
||||||
```Bash
|
```Bash
|
||||||
# Summary output, entire duration of log file
|
# Summary output, entire duration of log file
|
||||||
logwatch --service cfddns --output stdout --format text --range all --detail 0
|
logwatch --service cfddns --output stdout --format text --range all --detail 0
|
||||||
|
|
||||||
# Minimal detail, yesterday only
|
# Minimal detail, yesterday only
|
||||||
logwatch --service cfddns --output stdout --format text --range yesterday --detail 3
|
logwatch --service cfddns --output stdout --format text --range yesterday --detail 1
|
||||||
|
|
||||||
# Verbose output, today only
|
# Verbose output, today only
|
||||||
logwatch --service cfddns --output stdout --format text --range today --detail 5
|
logwatch --service cfddns --output stdout --format text --range today --detail 5
|
||||||
@ -282,7 +215,4 @@ # Verbose output, today only
|
|||||||
|
|
||||||
## Final thoughts
|
## Final thoughts
|
||||||
|
|
||||||
That's it! I'm a horrible PERL programmer so if anyone can optimize/improve the
|
That's it! I'm a horrible PERL programmer so if anyone can optimize/improve the script file used for Logwatch then please do it! Otherwise, I hope this made sense and helped you integrate the updater script with Logwatch for easy monitoring :-)
|
||||||
script file used for Logwatch then please do it! Otherwise, I hope this made
|
|
||||||
sense and helped you integrate the updater script with Logwatch for easy
|
|
||||||
monitoring :-)
|
|
||||||
Loading…
Reference in New Issue
Block a user