Updated readme with overview of the script and systemd files.
This commit is contained in:
parent
c5b53a1c50
commit
ed7182b665
153
README.md
153
README.md
@ -1,3 +1,154 @@
|
||||
# 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