gen

README

Odysseus

Odysseus is your friendly DNS pathfinder.

Description

Odysseus is designed to update a list of Cloudflare DNS A Records with your ISP Dynamic IP Address. The app reads the config from a YAML file, queries the Cloudflare API and if the content of each record has changed (i.e. the content of the DNS record != your IPS public IP), it'll go ahead and update it for you.

If you wrap this tool in a crontab, you might be all set to host your website/blog on a cluster of Raspberry Pis.

How to use it

Run it as a binary

First things first, download the odysseus binary:

mdir -p /opt/odysseus && cd /opt/odysseus
wget https://github.com/darkraiden/odysseus/releases/download/<version>/odysseus_<version>_<Linux|Darwin>_<i386|x86_64|armv6>.tar.gz
tar zxvf odysseus_<version>_<Linux|Darwin>_<i386|x86_64|armv6>.tar.gz
rm odysseus_<version>_<Linux|Darwin>_<i386|x86_64|armv6>.tar.gz

In the same directory where odysseus was downloaded, create a file called cloudflare.yml:

cat <<EOF > ./cloudflare.yml
cloudflare:
  zone_name: example.com
  email: user@example.com
  api_key: cloudflareapikeygoeshere
  records:
    - www.example.com
    - api.example.com
EOF

To establish a connection with Cloudflare, you need the email address you use to log in and the api_key which can be found in My Profile > API Tokens > Global API Key. Ensure that the rest of the details (zone_name and records) are correct too.

Now that your config is ready, simply type:

./odysseus

Alternatively, the config file can be stored elsewhere with a different name; if so, ensure to pass the appropriate flags when running the binary:

./odysseus -config-name someName.yml -config-path /path/to/config/file

Run it as a Docker container

First things first, create a file called cloudflare.yml, as showed in the Run It as a Binary section, and save it somewhere in your filesystem;

Finally, run odysseus' Docker container:

docker run -v /path/to/cloudflare.yml:/app/cloudflare.yml davidedimauro88/odysseus:<version>

Installing from source

Odysseus can be built on Linux, Mac OS or Windows; the build commands might change slightly depending on the OS or Processor Architecture.

Requirements

• git
• go 1.14+
• a Cloudflare API Key
• docker (optional)
• docker-compose (optional)

Setting up workspace

Clone the project in your $GOPATH:

cd $GOPATH
mkdir -p src/github.com/darkraiden
git clone https://github.com/darkraiden/odysseus src/github.com/darkraiden/odysseus
cd src/github.com/darkraiden/odysseus

Building

Install the app dependencies using go mod:

export GO111MODULE=on
go mod download

Finally, build odysseus:

env GOOS=<targetOsHere> GOARCH=<targetArchitecture> go build cmd/odysseus/main.go -o odysseus

To execute the application, ensure the cloudflare.yml file is created; check the cloudflare.yml.example file for more information.

If you don't want to compile odysseus on your workstation, a docker-compose.yml file is provided so that the app can be compiled inside a Docker container:

docker-compose up --build

Testing

The test suite can be run with go test:

go test ./...

License

Licensed under the MIT License: https://mit-license.org