Updated readme to conform with markdown standards and fixed typos.
This commit is contained in:
parent
0ef29d2ba6
commit
f41d16646e
217
README.md
217
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
|
||||
auto-update itself. However, you MUST update the systemd service file,
|
||||
*cfddns.service*, *ExecStart* line manually as explained below**
|
||||
**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.**
|
||||
|
||||
## 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.
|
||||
1. Copy the script file to your desired path (/usr/local/bin recommended) and
|
||||
rename as desired.
|
||||
|
||||
I recommend putting this script 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 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
|
||||
and example usage screens by running: *cfddns.sh -h* for help and *cfddns.sh -x*
|
||||
for examples.
|
||||
summarized here. You can access the help screen and example usage screens by
|
||||
running:
|
||||
|
||||
```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
|
||||
next to Global API Key.
|
||||
Scroll down to 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
|
||||
Your completed file should look like (these are not real credentials):
|
||||
> 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
|
||||
records, once for AAAA records even if the hostname is the same).*
|
||||
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**
|
||||
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.
|
||||
*NOTE: The address you supply is NOT checked for correctness. So ensure you're
|
||||
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!*
|
||||
|
||||
@ -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*.
|
||||
This can be messy if you store the script in /usr/bin/local/ as recommended.
|
||||
*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 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*
|
||||
directory. If you change the name of the cfddns.sh file, you must update the
|
||||
filename in the *ExecStart* line as shown below:
|
||||
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:
|
||||
|
||||
````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.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.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
|
||||
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
|
||||
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
|
||||
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.
|
||||
```
|
||||
|
||||
*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
|
||||
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:
|
||||
* Errors always appear as "-- [ERROR] text and error code here --"
|
||||
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 --**
|
||||
* 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]
|
||||
* 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
|
||||
|
Loading…
Reference in New Issue
Block a user