Updated readme with overview of the script and systemd files.
This commit is contained in:
Asif Bacchus
parent
c5b53a1c50
commit
ed7182b665
153
README.md
153
README.md
@ -1,3 +1,154 @@
|
|||||||
# CloudflareDDNS
|
# CloudflareDDNS
|
||||||
|
|
||||||
Update DNS records at CloudFlare for dynamic IP address changes via curl and CloudFlare API.
|
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
|
||||||
|
auto-update itself. However, you MUST update the systemd service file,
|
||||||
|
*cfddns.service*, *ExecStart* line manually as explained below**
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
1. Copy the script file to your desired path (/usr/local/bin recommended) and
|
||||||
|
rename as desired.
|
||||||
|
```Bash
|
||||||
|
sudo cp cfddns.sh /usr/local/bin/
|
||||||
|
```
|
||||||
|
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
|
||||||
|
and example usage screens by running: *cfddns.sh -h* for help and *cfddns.sh -x*
|
||||||
|
for examples.
|
||||||
|
|
||||||
|
**-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
|
||||||
|
next to 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:
|
||||||
|
> johndoe@example.com
|
||||||
|
> e7882db52804aca6fab22780e055b97056466
|
||||||
|
> 492af8aa69f8c44baf043342c74319fd
|
||||||
|
|
||||||
|
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
|
||||||
|
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
|
||||||
|
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
|
||||||
|
*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 addresses will be requested for echo.
|
||||||
|
This parameter let's you bypass auto-detection and specify a particular address
|
||||||
|
to be used instead.
|
||||||
|
*NOTE: The address you supply is NOT checked for correctness. So 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/bin/local/ as recommended.
|
||||||
|
Therefore, it's recommended you choose a different location for
|
||||||
|
the logfile (*/var/log/cfddns.log* is recommended).
|
||||||
|
|
||||||
|
**-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
|
||||||
|
This is the systemd file that **must** be copied to your */etc/systemd/system*
|
||||||
|
directory. If you change the name of the cfddns.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
|
||||||
|
...
|
||||||
|
````
|
||||||
|
|
||||||
|
## 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
|
||||||
|
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
|
||||||
|
thereafter as long as the system is powered on. Remember when settings 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
|
||||||
|
file:
|
||||||
|
````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
|
||||||
|
first (after boot) call before calling cfddns.service again. Therefore,
|
||||||
|
eveything is relative to your system boot up. 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.
|
||||||
|
|
||||||
|
## 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
|
||||||
|
have to review this log as part of your daily routine. To make that easier, the
|
||||||
|
following conventions are observed in the log file:
|
||||||
|
* 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 --"
|
||||||
|
* The script always starts a new set of log entries with "-- Start CloudFlare
|
||||||
|
DDNS script execution --
|
||||||
|
* 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
|
||||||
|
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 [https://mytechiethoughts.com](https://mytechiethoughts.com) where I tackle
|
||||||
|
problems like this all the time and find free/cheap solutions to tech problems.
|
||||||
Loading…
Reference in New Issue
Block a user