Craig Oates
999bb27352
|
3 months ago | |
|---|---|---|
| src | 3 months ago | |
| tests | 3 months ago | |
| .gitignore | 4 months ago | |
| README.org | 3 months ago | |
| ddns-updater.asd | 3 months ago | |
| makefile | 4 months ago | |
README.org
DDNS UPDATER
A CLI program which uses the DNSimple REST API to update IP addresses associated with a domain name.
Prerequisites
- Common Lisp
- SBCL
- DNSimple Account
- Telegram Account (optional)
Installation
If you are already familiar with this repository, you should be able to get away with the following commands (on Debian 11+):
cd ~/dev
git clone git@git.abbether.net:craig.oates/ddns-updater.git
make install
make lisp-install
make quicklisp-add
# To build the binary...
make build
# dup should be in the bin/ directory.If this is your first time with the repository, please read the following below.
Install Common Lisp Environment
At the time of writing, I've only used this system on Debian 11 (bullseye), with the Steel Bank Common Lisp (SBCL) implementation (for Common Lisp) and Quicklisp (package manager). For a guide on how to install and set up Common Lisp and Quicklisp on your machine, please use the following link:
- Lisp Cookbook (Getting Started Guide)
Clone Repository
# Change the path to where you normally store your git repositories.
cd ~/dev
# Using SSH
git clone git@git.abbether.net:craig.oates/ddns-updater.git
# Using HTTP
git clone https://git.abbether.net/craig.oates/ddns-updater.git
cd ddns-updater
# Add the repository to you Quicklisp set-up if you haven't cloned the
# repository into a directory recognised by Quicklisp or ASDF. Change the paths
# to match your system. The one you'll most likely need to change is the first
# path.
ln -s ~/dev/larder.web ~/quicklisp/local-projects/
# To build the binary (and run the program from the command-line),
make build
The build of the program will be in the bin/ directory, named dup.
Usage
The first thing you need to do after you've built the program is create a configuration file.
Set-Up
cd bin
# This makes a template file which you can then fill out with your own personal
# information.
./dup -m "~/ddns-updater.json"Access Tokens
Fill out the ddns-updater.json file to match set-up. Unfortunately, this means
you need to know how to find your Access Tokens on the DNSimple website. They
should be found in your Account Settings under 'Access Tokens', but website are
prone to change and DNSimple's is the same. So, putting more information here
would mean it becoming dated/incorrect over time. You're on your own
here… sorry.
After you've acquired your Account Id and Account Token, and added them to
your ~/ddns-updater.json file, it should start to look like the following,
{
"token": "d79f2e37784e5cd8631963896ebc6c9c",
"server-name": "your_sever_name",
"account-id": "12345",
"record-ids": [
"your_domain_name_record_id",
"your_domain_name_record_id"
],
"telegram-token": "your_telegram_token",
"chat-id": "your_chat_id",
"notify-on-success": "false",
"notify-on-fail": "true",
"last-recorded-ip": "0.0.0.0"
}Record Id's (I.E. Subdomains)
DNSimple attaches a Record Id. to any A Records you make under a particular
domain name. For example, let's say you own the domain name, example.com and
create a subdomain called test.example.com. DNSimple will give that subdomain
a Record Id. It is this Record Id. which you'll add to the records-id array in
~/ddns-updater.json. To get a list of the Record Id's and the subdomains
they're attached to, use the below.
;; Assuming you've already started to fill out the ddns-updater.json file...
;; In SLIME (Emacs) or SBCL REPL.
(ql:quickload :ddns-updater)
(utils::get-records-in-zone
(utils:read-config-file #P"~/ddns-updater.json")
#P"~/domain-record-ids.json")
In the ~/domain-record-ids.json file, you want to look for the id and name
values in each object in the data array. An example of what an object looks
like is below.
{
"data": [
{
"id": 12345678, // <======= You want this.
"zone_id": "example.net",
"parent_id": null,
"name": "testing", // <===== Which is linked to this subdomain.
"content": "ns1.dnsimple.com admin.dnsimple.com 1234567890 12345 1234 132456 123",
"ttl": 3600,
"priority": null,
"type": "SOA",
"regions": [
"global"
],
"system_record": true,
"created_at": "2023-11-20T17:48:50Z",
"updated_at": "2023-12-17T11:48:42Z"
}
]
}
Make a note of every id you currently running on the server you're running
this program on, and add them to the record-ids array in
~/ddns-updater.json. Oh, now would be a good time to fill out the
server-name part of the file, as well. This is the name included in the
Telegram notification. It doesn't need to match the server's name exactly, but
it's usually a good default option. After you've made the changes, your
ddns-updater.json should look something like the code below.
{
"token": "d79f2e37784e5cd8631963896ebc6c9c",
"server-name": "fancy-server-001", // Doesn't need to match your server name.
"account-id": "12345",
"record-ids": [
"12345678", // Refers to testing.example.net from code-block above.
"87654321", // Add as many Record Id's as you need.
"12348765"
],
"telegram-token": "your_telegram_token",
"chat-id": "your_chat_id",
"notify-on-success": "false",
"notify-on-fail": "true",
"last-recorded-ip": "0.0.0.0"
}Telegram Notifications
This is an optional feature. To turn this feature off, make sure
notify-on-success and notify-on-fail are set to false in the
~/ddns-updater.json file. You can, also, ignore the telegram-token and
chat-id.
- Telegram Website (to download the app.)
For you to use this feature, you need to be somewhat familiar with Telegram and making a bot on its system. I don't know how long the linked article below will be of use, but it seems to give a simple enough introduction to those new to Telegram.
When that is done, you will need to get a chat id. To do this you need to make
sure you've created a username via Telegram's settings. From there, start a
new channel with Telegram Bot Raw and send /start. You will then receive a
JSON object. You need to copy the id number from the chat object.
Once you've got these two bits of information, you can add them to your
~/ddns-updater.json file. And, that file should look something like the
example below.
{
"token": "d79f2e37784e5cd8631963896ebc6c9c",
"server-name": "fancy-server-001",
"account-id": "12345",
"record-ids": [
"12345678",
"87654321",
"12348765"
],
"telegram-token": "d79f2e37784e5cd8631963896ebc6c9c66934af94a1854",
"chat-id": "1234567890",
"notify-on-success": "false",
"notify-on-fail": "true",
"last-recorded-ip": "0.0.0.0"
}
The example above is set up to only send a Telegram notification if the program
fails to update the IP address' for listed record-ids. You can adjust it to
send only messages on success or success and failure by changing the 'notify'
sections to true or false. The last-recorded-ip section is for the
program. You don't need to touch this part.
Running the Program
cd bin
# To test the Telegram notification system.
./dup -t 1
# Update the Record Id's listed in the ~/ddns-updater.json file.
./dup
# To run the program with a non-default config. file.
./dup -c <PATH TO YOUR CUSTOM DDNS-UPDATER.JSON FILE>
# To create a config. file template (populate it with your data). You can use
# whatever path you want but ~/ddns-updater.json is the default file this
# program looks for. If you do use a custom path, you will to use -c whenever
# you run this program.
./dup -m ~/ddns-updater.json
# To validate the schema of your config. file. Note, this only checks to make
# sure your config. file has the correct ‘keys’ in it. Your access tokens and
# Id’s are not validated. Incorrect access token and Id’s will produce and error
# messges stating which ones are wrong when you try and use the program, though.
./dup -a <PATH TO YOUR DDNS-UPDATER.JSON FILE>
# Run the program in 'verbose' mode.
./dup -v