Update readme
This commit is contained in:
parent
a17c55292c
commit
9002d6dd0b
GPG key ID:
0A400FFE10097C30
1 changed files with 131 additions and 0 deletions
131
README.md
131
README.md
|
|
@ -0,0 +1,131 @@
|
||||||
|
# DDNS for Cloudflare
|
||||||
|
|
||||||
|
Small binary to update Cloudflare DNS entries via a config file.
|
||||||
|
|
||||||
|
## How does it work
|
||||||
|
|
||||||
|
This system is split into two portions, the binary itself and an external timer
|
||||||
|
that periodically executes the binary.
|
||||||
|
|
||||||
|
To install the binary, either build your own `.deb` file or find a release. More
|
||||||
|
distro support is appreciated but not currently promised.
|
||||||
|
|
||||||
|
An external timer can be a system provided one or something like `crontab`.
|
||||||
|
For convenience, a `systemd` system and timer file is provided that activates it
|
||||||
|
on an hourly interval. This is automatically installed if you use the `.deb`.
|
||||||
|
|
||||||
|
The binary contains various subcommands:
|
||||||
|
|
||||||
|
|Subcommand|Description|
|
||||||
|
|----------|-----------|
|
||||||
|
|`run`|Reads from a config file and calls into Cloudflare's API|
|
||||||
|
|`list`|Read the config file to list information about your zones|
|
||||||
|
|
||||||
|
This binary must be activated at your preferred interval via an external timer.
|
||||||
|
|
||||||
|
This only supports updating one IP address to any number of zones and DNS
|
||||||
|
entries. For another IP address, install and run this on the machine with
|
||||||
|
different IP address.
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
First, create an initial file at `/etc/cloudflare-ddns.toml`. Populate it with
|
||||||
|
the following:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[account]
|
||||||
|
email = "your@email.com"
|
||||||
|
api_key = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
|
||||||
|
|
||||||
|
[ip_reflector]
|
||||||
|
ipv4 = "https://what.is.my.ipv4.example"
|
||||||
|
ipv6 = "https://what.is.my.ipv6.example"
|
||||||
|
|
||||||
|
[zone."example.com"]
|
||||||
|
id = "deadbeefdeadbeefdeadbeefdeadbeef"
|
||||||
|
```
|
||||||
|
|
||||||
|
### `account` section
|
||||||
|
|
||||||
|
The `email` should be the email associated with your Cloudflare account.
|
||||||
|
|
||||||
|
The `api_key` field should be populated with your Global API Key. This is found
|
||||||
|
at on your [account profile].
|
||||||
|
|
||||||
|
[account profile]: https://dash.cloudflare.com/profile/api-tokens
|
||||||
|
|
||||||
|
### `ip_reflector` section
|
||||||
|
|
||||||
|
The `ipv4` and `ipv6` fields should be populated with a URL that when provided
|
||||||
|
a `GET` request, returns the IP address in the body as a string, without a
|
||||||
|
newline.
|
||||||
|
|
||||||
|
For example, `curl` should return something similar to this:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ curl https://what.is.my.ipv4.example
|
||||||
|
1.2.3.4%
|
||||||
|
```
|
||||||
|
The `%` is added by `curl` to indicate no line ending.
|
||||||
|
|
||||||
|
### `zone` section
|
||||||
|
|
||||||
|
Each zone subsection should contain a website registered to your account. Each
|
||||||
|
zone needs an `id`, which can be found on the Overview tab of the respective
|
||||||
|
website.
|
||||||
|
|
||||||
|
Once you've populated all fields, run `cloudflare-ddns list` to list the ids of
|
||||||
|
each DNS entry:
|
||||||
|
|
||||||
|
```
|
||||||
|
example.com (deadbeefdeadbeefdeadbeefdeadbeef)
|
||||||
|
+--------------------+------+--------------------------+---------+----------------------------------+
|
||||||
|
| Name | Type | IP Address | Proxied | Id |
|
||||||
|
+--------------------+------+--------------------------+---------+----------------------------------+
|
||||||
|
| example.com | A | 6.6.6.6 | false | fefefefefefefefefefefefefefefefe |
|
||||||
|
+--------------------+------+--------------------------+---------+----------------------------------+
|
||||||
|
| irys.example.com | A | 6.6.6.6 | true | c0ffeec0ffeec0ffeec0ffeec0ffeec0 |
|
||||||
|
+--------------------+------+--------------------------+---------+----------------------------------+
|
||||||
|
| suisei.example.com | AAAA | 1111:11::1111 | true | 1337c0d31337c0d31337c0d31337c0d3 |
|
||||||
|
+--------------------+------+--------------------------+---------+----------------------------------+
|
||||||
|
```
|
||||||
|
|
||||||
|
This lists all relevant data necessary for dynamically updating each DNS entry.
|
||||||
|
|
||||||
|
For each DNS entry for `example.com` you want to dynamically update, create an
|
||||||
|
entry as follows:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[[zone."example.com".record]]
|
||||||
|
name = "@" # Use @ for the root domain
|
||||||
|
id = "fefefefefefefefefefefefefefefefe"
|
||||||
|
proxy = false
|
||||||
|
type = "A"
|
||||||
|
|
||||||
|
[[zone."example.com".record]]
|
||||||
|
name = "irys"
|
||||||
|
id = "c0ffeec0ffeec0ffeec0ffeec0ffeec0"
|
||||||
|
proxy = true
|
||||||
|
type = "A"
|
||||||
|
|
||||||
|
[[zone."example.com".record]]
|
||||||
|
name = "suisei"
|
||||||
|
id = "1337c0d31337c0d31337c0d31337c0d3"
|
||||||
|
proxy = true
|
||||||
|
type = "AAAA"
|
||||||
|
```
|
||||||
|
|
||||||
|
A full example config can be found in the repo.
|
||||||
|
|
||||||
|
At this point, you can run `cloudflare-ddns run` to verify that everything
|
||||||
|
works. If you run into issues, you can provide `--log=debug` or `--log=trace`
|
||||||
|
for more information.
|
||||||
|
|
||||||
|
If successful, attempt to trigger it via the external timer. If that is
|
||||||
|
successful, installation is complete.
|
||||||
|
|
||||||
|
## Building packages
|
||||||
|
|
||||||
|
A `.deb` package is created via [`cargo-deb`].
|
||||||
|
|
||||||
|
[`cargo-deb`]: https://github.com/kornelski/cargo-deb
|
||||||
Loading…
Reference in a new issue